= oidc-agent =

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 [[https://github.com/indigo-dc/oidc-agent/releases|GitHub]] or [[http://repo.data.kit.edu/|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`"
}}}

== troubleshooting ==

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': 
success
}}}

'''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: 
cta
radio
}}}