Detailed Information About All Options

Short Information About All Options

Option	Effect
--socket-path	Use this path for the UNIX-domain socket.
--always-allow-idtoken	Always allow id-token requests without manual approval by the user
--confirm	Requires user confirmation when an application requests an access token for any loaded
--console	Runs oidc-agent on the console, without daemonizing
--debug	Sets the log level to DEBUG
--json	Print agent socket and pid as JSON instead of bash
--kill	Kill the current agent (given by the OIDCD_PID environment variable)
--no-autoload	Disables the autoload feature: A token request cannot load the needed configuration
--no-autoreauthenticate	Disables the automatic re-authentication feature
--no-scheme	oidc-agent will not use a custom uri scheme redirect [Only applies if authorization code flow is used]
--no-webserver	oidc-agent will not start a webserver [Only applies if authorization code flow is used]
--pid-file	If set the agent's pid is written to this file
--quiet	Disable informational messages to stdout
--restart-on-update	Enables automatic restart of the agent if its binary changes
--lifetime	Sets a default value in seconds for the maximum lifetime of account configurations [..]
--log-stderr	Additionally prints log messages to stderr
--status	Connects to the currently running agent and prints status information
--with-group	Applications running under another user can access the agent [..]

Detailed explanation About All Options

--socket-path

By default oidc-agent creates the UNIX-domain socket at $TMPDIR/oidc-XXXXXX/oidc-agent.<ppid>, where <ppid> is the parent's process id and XXXXXX is a randomly generated. The -a or --socket-path or --bind-address option can be used to change the location where this UNIX-domain socket is created. Please note the following:

• If the passed argument has no trailing slash, the last part is the socket's filename.

• If the passed argument has a trailing slash, the socket will be created with a filename of oidc-agent.<ppid> in the passed directory.

• If the passed argument contains XXXXXX as the last part of one of the directories, the XXXXXX will be replaced with randomized characters. Example:

• The passed directory may not exist (oidc-agent can create the directory (including parents)).

• If a non-randomized path is passed and a socket already exists there, oidc-agent will overwrite it.

In the following we present some examples of the passed argument and the resulting full socket path:

• /tmp/oidc-agent -> /tmp/oidc-agent

• /tmp/oidc-agent/ -> /tmp/oidc-agent/oidc-agent.1234

• /tmp/oidc-agent-XXXXXX/ -> /tmp/oidc-agent-s4jdi2/oidc-agent.1234

• /tmp/oidc-agent-XXXXXX/socket -> /tmp/oidc-agent-s4jdi2/socket

• /tmp/oidc-agent-XXXXXX/socket/ -> /tmp/oidc-agent-s4jdi2/socket/oidc-agent.1234

• /tmp/XXXXXX-agent/ -> tmp/XXXXXX-agent/oidc-agent.1234

--always-allow-idtoken

oidc-token can also be used to request an id token from the agent. On default such requests have to be approved by the user, since this is only meant as a development tool and other applications should not request id tokens from the agent as they are not meant for authorization. If the --always-allow-idtoken option is specified id token requests do not need confirmation by the user.

--confirm

On default every application running as the same user as the agent can obtain an access token for every account configuration from the agent. The --confirm option can be used to change this behavior. If that option is used, the user has to confirm each usage of an account configuration, allowing fine grained control from the user. The --confirm option can be used when loading an account configuration through oidc-add, in that case only that specific account needs confirmation, or when starting the agent. If the option is used with the agent, every usage of every account configuration has to be approved by the user.

--console

Usually oidc-agent runs in the background as a daemon. This option will skip the daemonizing and run on the console. This might be sued for debugging.

--debug

This increases the log level to DEBUG and obviously should only be used to debug purposes. If enabled, sensitive information (among others refresh tokens and client credentials) are logged to the system log.

--json

Enables json output for values like agent socket and pid. Useful when starting the agent via scripts.

--kill

This will kill the currently running agent. The agent to be killed is identified by the OIDCD_PID environment variable. When integrated with Xsession this will kill the agent available in all terminals. A restarted agent will not automatically be available in already existing or new terminals. You can use oidc-keychain to make a newly started agent available in new terminals or login sessions.

--no-autoload

On default account configurations can automatically be loaded if needed. That means that an application can request an access token for every account configuration. If it is not already loaded the user will be prompted to enter the needed encryption password. After the user enters the password the account configuration is loaded and an access token returned to the application. the user can also cancel the autoload.

With --no-autoload enabled the agent will not load currently not loaded account configuration for which an access token is requested. The user then first has to add them manually by using oidc-add, before an application can obtain an access token for those.

--no-autoreauthenticate

It might happen that the refresh token used with an account configuration expires. If this happens oidc-agent is no longer able to provide access tokens to clients. When oidc-agent discovers that a refresh token is expired a helpful message is sent to the client. This message should be displayed to the user and helps solving the problem.

However, oidc-agent is also capable of triggering the needed re-authentication automatically. oidc-agent will also do this by default.

With --no-autoreauthenticate or --noauto-reauthenticate enabled the agent will not load currently not loaded account configuration for which an access token is requested. The user then first has to add them manually by using oidc-add, before an application can obtain an access token for those.

`--no-scheme

This option can be used when the authorization code flow is performed. The --no-scheme option tells oidc-agent that a custom uri scheme should never be used for redirection (for any account configuration). Normally a custom uri scheme can be used to redirect direct to (another) oidc-gen instance when performing the authorization code flow instead of using a web server. However, the redirect to oidc-gen requires a graphical desktop environment. If this is not present, redirection with custom uri schemes can be disabled with this option.

--no-webserver

This option can be used when the authorization code flow is performed. On default a small webserver is started by oidc-agent to be able to catch the redirect and complete the authorization code flow. The --no-webserver option tells oidc-agent that no webserver should be started (for any account configuration). The authorization code flow can still be completed. Either by using a redirect uri that follows the custom redirect uri scheme edu.kit.data.oidc-agent:/<path> - this will directly redirect to oidc-gen, or by copying the url the browser would normally redirect to and pass it to oidc-gen --codeExchange.

--pid-file

On default the agent outputs commands that - when executed - set certain environment variables. The $OIDCD_PID variable then contains the agent's process id, which is used by oidc-agent -k to stop that agent. For oidc-agent-service and maybe other tools the mechanism of an environment variable might not be sufficient and a pid file might be preferred.

Through the --pid-file option a file can be passed. If given the agent's pid is written to this file and other applications might use it.

--quiet

Silences informational messages. Currently only has effect on the generated bash echo when setting agent environments.

--restart-on-update

If enabled, the agent automatically restart after a (package) update. The agent will observe it's binary using inotify. When the file is changed (via a move), the agent restarts.

This option is included by default when the agent is started via oidc-agent-service.

It does not work with a non-daemonized agent and is generally only useful when the agent is started with oidc-agent-service or the socket path is persisted in another way.

--lifetime

The --lifetime option can be used to set a default lifetime for all loaded account configurations. This way all account configurations will only be loaded for a limited time after which they are automatically removed from the agent. When loading an account configuration with oidc-add this lifetime can be overwritten. So that a specific account configuration can be loaded with another lifetime (lower, higher, and also infinite).

Using --lifetime=0 means that account configuration are not automatically removed and they are kept loaded for an infinite time. This is also the default behavior.

--log-stderr

The --log-stderr option allows log messages to be printed to stderr. Note that the log messages are still logged to syslog as usual. This option is intended for debug purposes and is usually combined with -d.

--status

The --status option can be used to obtain information about a currently running agent. Therefore, the OIDC_SOCK environment variable must be set. The option prints information such as:

• the version of the running agent (this is useful to check what agent version is currently running and it might differ from the version installed)

• options that can be set on start up

• the loaded accounts

--with-group

On default only applications that run under the same user that also started the agent can obtain tokens from it. The --with-group option can be used to also allow other applications access to the agent. This can be useful in cases where applications must run under a specific user. The user first has to create a group (e.g. named oidc-agent) and add himself and all other users that need access to the agent to this group. It is the user's responsibility to manage this group. Then he can pass the group name to the --with-group option to allow all group members access to the agent. If the option is used without providing a group name, the default is oidc-agent.