oidc-agent is a set of tools to manage OpenID Connect tokens and make them easily usable from the command line.

Installation instructions

Current releases are available at GitHub or KIT.

Bootstrapping oidc-agent

The first thing to do is to start oidc-agent. This can be done issuing the following command:

$ eval $(oidc-agent)
Agent pid 62088

How to register a client

In order to obtain a token, a user needs a client registered An example of a configuration:

oidc-gen -m

Enter short name for the account to configure: radio
Issuer [https://iam-test.indigo-datacloud.eu/]: https://keycloak.desy.de/auth/realms/Radio
Client_id: local
Client_secret: xxxxxxxxxxxxxxxx
The following scopes are supported: openid address phone roles email microprofile-jwt web-origins profile offline_access
Scopes or 'max' (space separated) [openid profile offline_access]: openid profile offline_access
Redirect_uris (space separated): http://localhost:4242
Generating account configuration ...

alternative method in which all information is passed via paramater

oidc-gen -m radio --client-id=local --redirect-uri="http://localhost:4242" --scope-max --client-secret="xxxxxxxxxxxxxxxxxxxxxx" --issuer="https://keycloak.desy.de/auth/realms/Radio/"

As of version 4.3.x , please specify the --flow=code and --scope="openid microprofile-jwt phone address email offline_access profile" parameter. Example:

oidc-gen -m radio --client-id=local --redirect-uri="http://localhost:4242" --scope="openid microprofile-jwt phone address email offline_access profile" --scope-max --client-secret="xxxxxxxxxxxxxxxxxxxxxx" --flow=code --issuer="https://keycloak.desy.de/auth/realms/Radio/"

test a client

To create a token:

oidc-token radio

To see the information of the token please open jwt.io and copy the generated token into the field "Encoded".

use a token

This example shows how to use the token as a bearer token

curl https://rnog-data-protected.zeuthen.desy.de/protected.csv -H "Authorization: Bearer `oidc-token radio`"


With the following error message the token must be loaded.

$ oidc-token radio
Error: account not loaded

load the token

$ oidc-add radio
Enter decryption password for account config 'radio': 

Error: could not parse json

please add parameter --flow=code

see: https://github.com/indigo-dc/oidc-agent/issues/430

helpful commands

show the configuration of an account:

$ oidc-gen --print radio
Enter decryption password for account config 'radio': 
        "name": "radio",
        "client_name":  "oidc-agent:radio-znpnb486",
        "issuer_url":   "https://keycloak.desy.de/auth/realms/Radio/",
        "device_authorization_endpoint":        "https://keycloak.desy.de/auth/realms/Radio/protocol/openid-connect/auth/device",
        "daeSetByUser": 0,
        "client_id":    "local",
        "client_secret":        "xxxxxxxxxxxxxxx",
        "refresh_token":        "xxxxxxxxxxxxxxx",
        "cert_path":    "/etc/ssl/certs/ca-certificates.crt",
        "scope":        "openid profile offline_access",
        "audience":     "",
        "redirect_uris":        ["http://localhost:4242"],
        "username":     "",
        "password":     ""

print a list of all configured accounts

$ oidc-gen -l
The following account configurations are usable: 

oidc-agent (last edited 2022-07-25 13:25:31 by JanPhilippBolle)