indigo-dc / oidc-agent

oidc-agent for managing OpenID Connect tokens on the command line

oidc-agent

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

Installation

oidc-agent is directly available for some newer debian-based distributions. Releases for all distributions are available at http://repo.data.kit.edu/

Linux

Debian 12 and newer / Ubuntu 22.04 and newer

sudo apt-get install oidc-agent

Other distributions

See http://repo.data.kit.edu/

MacOS

brew tap indigo-dc/oidc-agent
brew install oidc-agent

windows

The installer for windows is available at http://repo.data.kit.edu/windows/oidc-agent

From Source

Refer to the documentation

Quickstart

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.

Create an agent account configuration with oidc-gen

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.

Use oidc-add to load an 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.

Obtaining an access token

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.

List existing configuration

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

Updating an existing account configuration

An existing account configuration can be updated with oidc-gen:

oidc-gen -m <shortname>

Reauthenticating

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

Usage with SSH

oidc-agent supports your work on remote hosts in two ways:

Create an agent account configuration on a remote host

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>

Agent Forwarding

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.

oidc-agent's Issues

httpserver not correctly shutdown

json Merge Array only first element

When merging two json objects: If the second json object contains arrays not contained in the first one, they are not correctly merged. No array is added to the combined json, but only the first value.

parse config files before deamonizing

so the user gets the error output etc, once done with parsing daemonize.

Registering new client fails with "could not decode json: (null)"

When registering a new client using oidc-gen new-iam I get this error:

marcus@nemo:~/grid/m-team/oidc-agent-deb/oidc-agent$ oidc-gen new-iam
Cert Path [/etc/ssl/certs/ca-certificates.crt]:
[1] https://iam-test.indigo-datacloud.eu/
Issuer [https://iam-test.indigo-datacloud.eu/]:
Could not decode json: (null)
This seems to be a bug. Please hand in a bug report.

I was also using the /oidc and /oauth2 paths.

The error already appears before IAM could have possibly answered the request.

Account generation not working after dynamic client registration

When registering a client dynamically the account generation fails with an error: Error: could not connect to url.

This is already fixed in version 2.0.0 (will be released soon).

Temporal Workaround:
After the oidc-gen call failed call oidc-gen with the -f option and pass the created client config file:

Example:

$ oidc-gen IAM-DEEP
[1] https://iam-test.indigo-datacloud.eu/
[...]
[13] https://oidc-kc.scc.kit.edu/auth/realms/kit/
Issuer [https://iam-test.indigo-datacloud.eu/]: 2
Space delimited list of scopes [openid profile offline_access]: 
Registering Client ...
Writing client config to file '/home/gabriel/.config/oidc-agent/<XXX>.clientconfig'
Enter encryption password for client config file: 
Confirm encryption Password: 
Generating account configuration ...
Error: could not connect to url

$ oidc-gen IAM-DEEP -f /home/gabriel/.config/oidc-agent/<XXX>.clientconfig
Enter decryption Password for client config file: 
No account exists with this short name. Creating new configuration ...
[1] https://iam-test.indigo-datacloud.eu/
[...]
[13] https://oidc-kc.scc.kit.edu/auth/realms/kit/
Issuer [https://iam-test.indigo-datacloud.eu/]: 2
Client_id [xxx]: 
Client_secret [***]: 
Space delimited list of scopes [openid profile offline_access]: 
Refresh token: 
Username: 
Password: 
Space separated redirect_uris [http://localhost:8080 http://localhost:2912 http://localhost:19428]: 
Generating account configuration ...
accepted
To continue and approve the registered client visit the following URL in a Browser of your choice:
[...]

refactor http

one function to group options used for all curl calls

Include expire_at in the response to a token request

The response returned for an access token request currently includes the token and the issuer url.
It can be helpful for the requesting application if we also return the time where the token expires.

Note: A request can already provide a min_valid_time. The returned access token is guaranteed to be valid for at least that long (or the servers maximum valid time). But it is more helpful if we return the precise time where the token expires (also good, if requested time exceeds the server's maximum or a very small min_valid_time was used (e.g. 0))

oidc-agent hangs when adding certain configs

need the recvmsg syscall

Improve dynamic client registration

Improve the selection of response and grant types based on the used flows.
include the to be used flow(s) in the register request.
Also relates to the oidc-gen UI improvements (#86 and #87).

Combine Client Config and Account config

Because the default behavior of oidc-gen is to use dynamic client registration it can be inconvenient for a user to enter two different passwords - one for encrypting and saving the client configuration of the dynamically registered client and one for the actual account configuration.
The default behavior should be to save both in a single file, because most users wont reuse an previously registered client.

For advanced use cases separated files should be still supported

Support for issue #200

Hi,

I didn't know exactly if it was the right place.
Can you help on this?

erlef/oidcc#200

Thank you.

Best,

Sofiane.

access-token is not cache

Each time I run the oidc-token command it generates a fresh access token.

Some services and OPs allow an access token to be reused within some validity period. For such services, caching the access token can lead to significant improvement in responsiveness.

This could be done within oidc-agent (to allow caching across multiple clients) or implemented specifically for oidc-token.

Token requests should include an application_hint

An access token request should include a field 'application_hint'. The provided value can be used to make it easier to identify the application (e.g. when the user wants to approv each usage #65 or an application wants to use an currently not loaded configuartion #67)

please include jsmn globally

don't use include with '"" for jsmn, esp not relative paths like
https://github.com/zachmann/oidc-service/blob/master/src/config.h#L4

#include <jsmn.h>

oidc-gen echos client-secret to console

The oidc-gen command prompts for client information, including the client secret. Given this value should be private, the value should not appear on the console when typed in.

create obj/bin directories in Makefiles

when starting from scratch the code can't be compiled as the directories do not exist.

just add lines like

@mkdir -p $(BINDIR)
@mkdir -p $(OBJDIR)

so they get created

segfault on config code

the oidcd starts without a segfault once

readConfig();

is not used https://github.com/zachmann/oidc-service/blob/master/src/oidcd.c#L55

seccomp problem with auth code flow

Confirm usage of configuration

Loading a configuration with oidc-add -c requires that each usage of this configuration has to be confirmed by the user.

This requires a way to prompt the user for consent

Unloading configurations without password

An configuration should be unloadable without providing the encryption password

Dynamic client registration registers conflicting response types when using the password flow

Restrict seccomp filter to certain FD

We might be able to restrict some syscall to only stdin stdout stderr

oidc-token token request option

Include options for getting the issuer and expiration time returned from oidc-agent in the token request response.

UI Improvement: credentials for password flow

Only ask for credentials if the password flow is used.

It might not be clear that this information is usually optional (and not required)

oidc-add should not ask for a password when no connection to an agent can be made

Several FD not properly closed

FDs for pipes to http process and the unix socket FDs are not properly closed

Option for Removing all loaded configurations

Calling oidc-add -R should remove all loaded configurations

Autoregistered client should include host/node name

The oidc-gen command can auto-register the OIDC client within the OP. The name of the client is something like: oidc-agent:<ID> where <ID> is the short name for this identity.

It would be helpful if the client name included either the (simple) hostname, fqdn or some other identifier for the host on which oidc-agent is running.

The reason is that the same user may be oidc-agent running on multiple machines (a desktop and a laptop, for example). It may be useful to distinguish between these two oidc-agent registrations.

Google device flow

I'm not able to register Google device flow client. Neither manually nor from file. It says. Error: Device Flow not Supported. However Google supports it (doc). Maybe it is because googles .well-known configuration endpoint does not provide "device_authorization_endpoint" key. Is tehre a way to enter it maually?

Unable to specify a path for rediection URL

When running oidc-gen -m the user is prompted for a list of redirect URIs.

There are two problems:

1. It seems that the redirection URL is required not to have a path. For example, http://localhost:8888 is OK, but http://localhost:8888/ is not OK.

2. The problem is not picked up straight away: if the format requires exactly http://localhost: then the input should be validated and an error returned straight away.

debianisation clibs/list

Don't use git submodules to get the dependency.

Inlcude the source files into this repo.

do not test permanently for the password, limit it to e.g. 3 tries

https://github.com/KIT-SCC/oidc-agent/blob/db127e3d54701a33025ff2158eab772e4b22bbec/src/oidc-gen.c#L109

Support for Token Exchange

Add support for token exchange: https://tools.ietf.org/html/draft-ietf-oauth-token-exchange-16

http process still lives as a zombie

After the http process dies it still lives as a zombie

remove unused code

Autogenerate bashcompletion

oidc_gen: only delete file if all other went well

https://github.com/KIT-SCC/oidc-agent/blob/db127e3d54701a33025ff2158eab772e4b22bbec/src/oidc-gen.c#L115
(move to end of delete)

ipc partial read

Automatically loading a configuration if an access token is requested

If an access token is requested for an account configuration that is currently not loaded, the user can be prompt if it wants to load this configuration now.

Requires user prompting (including password) (linked to #65) and read file access.

new functions for config file access

the functions need to prepend the filename with the homedir of the current user

combine provider config and client config file

when a client was successfully registered the client config should be included into the provider config file. The client config file is not longer needed after the provider config is correctly in place.

UI Improvement: refresh_token prompt

When usign oidc-gen -m: Don't ask for a refresh token. It might not be clear that this information is optional and not required.

A use case where a refresh token is passed is very niche.
Make it a command line option.

Fix Headerfile dependencies for API library

gitignore file is missing

add a .gitignore file and include the bin/obj subdirectories in it

oidc-gen --flow no default value anymore

Getting encryption password from a user provided command

It might nice to provide a command to a command line option to obtain the password.
This makes it much easier to include oidc-add / oidc-gen in a script

Web server continues after client registration fails

I was using oidc-gen -m to register a client, but including the wrong redirection URL.

The web-server is started and the browser redirected to the OP. The OP then fails the request because the redirection URL is not one of the registered redirection URL.

However, because the redirection URL is not accepted, the browser is NOT redirected back to the oidc-agent web-server (the one running on localhost). The oidc-gen process shows a warning to indicate that something is going wrong.

Typing Control-C at this point terminates the oidc-gen process, but this does not kill the web-server. Any subsequent attempt to register will then fail as the agent attempts to start a new web-server, only to discover that port is already occupied (by the orphaned web-server).

Remove oidcdir creation from Makefile

Removing support for obtaining the list of currently loaded configurations

The C- and IPC-API can currently obtain a list of the loaded account configurations. This makes it easier for an application to obtain an access token that is not meant for it.
Also an application requesting an access token for a certain configuration does not have to check if this configuration is really loaded. It simply can try to obtain an access token. If it isn't loaded oidc-agent will return an error message.
Also #67 suggest that in this case the case can be asked if it wants to load the configuration ("on the fly").

Support for seccomp

We can restrict the system calls made by each component using seccomp.