oidc-agent is a set of tools to manage OpenID Connect tokens and make them easily usable from the command line. We
followed the
ssh-agent design, so users can handle OIDC tokens in a similar way as they do with ssh
keys.
oidc-agent is usually started in the beginning of an X-session or a login session. Through use of environment
variables the agent can be located and used to handle OIDC tokens.
The agent initially does not have any account configurations loaded. You can load an account configuration by
using oidc-add. Multiple account configurations may be loaded in oidc-agent concurrently. oidc-add is also used
to remove a loaded configuration from oidc-agent. oidc-gen is used to initially generate an account configurations
file (Help for different providers).
Full documentation can be found at https://indigo-dc.gitbooks.io/oidc-agent/.
We have a low-traffic mailing list with updates such as critical security incidents and new releases: Subscribe oidc-agent-user
oidc-agent is directly available for some newer debian-based distributions. Releases for all distributions are available at http://repo.data.kit.edu/
sudo apt-get install oidc-agentbrew tap indigo-dc/oidc-agent
brew install oidc-agent
The installer for windows is available at http://repo.data.kit.edu/windows/oidc-agent
Refer to the documentation
After installation the agent has to be started. Usually the agent is started on system startup and is then available on all terminals ( see integration). Therefore, after installation the options are to restart your X-Session or to start the agent manually.
eval `oidc-agent-service start`
This starts the agent and sets the required environment variables.
For most OpenID Connect providers an agent account configuration can be created with one of the following calls. Make
sure that you can run a web-browser on the same host where you run the oidc-gen command.
oidc-gen <shortname>
oidc-gen --pub <shortname>
For more information on the different providers refer to integrate with different providers.
oidc-gen supports different OIDC flows. To use the device flow instead of the authorization code flow include
the --flow=device option.
After an account configuration is created it can be used with the shortname to obtain access tokens. One does not need
to run oidc-gen again unless to update or create a new account configuration.
oidc-add <shortname>
However, usually it is not necessary to load an account configuration with
oidc-add. One can directly request an access token for a configuration and
oidc-agent will automatically load it if it is not already loaded.
oidc-token <shortname>
Alternatively, it is also possible to request an access token without specifying the shortname of a configuration but with the issuer url:
oidc-token <issuer_url>
This way is recommended when writing scripts that utilize oidc-agent to obtain access tokens. This allows that the script can be easily used by others without them having to update the shortname.
oidc-add -l
oidc-gen -l
These commands both give a list of all existing account configurations.
A list of the currently loaded accounts can be retrieved with:
oidc-add -a
An existing account configuration can be updated with oidc-gen:
oidc-gen -m <shortname>
If the refresh token stored in the account configuration expired a new one must be created. However, it is not required to create a new account configuration, it is enough to run:
oidc-gen <shortname> --reauthenticate
oidc-agent supports your work on remote hosts in two ways:
On remote hosts you usually have no way to start a web browser for authentication. In such scenarios, the device
flow can be used, but adding the flow=device option to oidc-gen:
oidc-gen --flow=device<shortname>
To use on oidc-agent on one host (typically your workstation or laptop)
from ssh-logins to other a remote host, you need to forward the local socket of oidc-agent to the remote side, and
there point the OIDC_SOCK
environment variable to the forwarded socket. Details for what we call
"agent-forwarding", are
described here in the gitbook.