liboidc-agent4
Last updated
Last updated
The C-API provides functions for getting an access token for a specific configuration as well as the associated issuer. These functions are designed for easy usage. The C-API is available as a shared library through the liboidc-agent5
package. The developement files (i.e. header-files) and the static library are included in the liboidc-agent-dev
package.
The library depends on libsodium
therefore the -lsodium
linker flag must be included when linking liboidc-agent
. If the library was build with liblist
then -llist
must be included. If the library was build with libcjson
then -lcjson
must be included. On modern distros this is usually the case.
The following functions can be used to obtain an access token for a specific account configuration from oidc-agent
. If you / your application does not know which account configuration should be used, but you know for which provider you need an access token you can also .
It is recommended to use instead.
This function requests an access token from oidc-agent for the accountname
account configuration. The access token should have scope
scopes, be valid for at least min_valid_period
seconds, and have the audience
audience.
accountname
is the shortname of the account configuration that should be used.
If min_valid_period
is 0
no guarantee about the validity of the token can be made; it is possible that it expires before it can be used.
If scope
is NULL
, the default scopes for that account are used. So usually it is enough to use NULL
.
application_hint
should be the name of the application that requests an access token. This string might be displayed to the user for authorization purposes.
If audience
is NULL
, no special audience is requested for this access token. This parameter is used to request an access token with a specific audience.
A complete example can look the following:
This function requests an access token from oidc-agent for the accountname
account configuration. The access token should have scope
scopes, be valid for at least min_valid_period
seconds, and have the audience
audience.
accountname
is the shortname of the account configuration that should be used.
If min_valid_period
is 0
no guarantee about the validity of the token can be made; it is possible that it expires before it can be used.
If scope
is NULL
, the default scopes for that account are used. So usually it is enough to use NULL
.
application_hint
should be the name of the application that requests an access token. This string might be displayed to the user for authorization purposes.
If audience
is NULL
, no special audience is requested for this access token. This parameter is used to request an access token with a specific audience.
The function returns an agent_response struct
. The type
element indicates which type is returned, i.e. if an error occurred. On success the response has a token_response struct
that contains the requested access token, the url of the issuer that issued the token and the time when the token expires (in seconds since the Epoch, 1970-01-01 00:00:00 +0000 (UTC)
).
The values can be accessed the following way:
After usage the return value MUST be freed using secFreeAgentResponse
.
A complete example can look the following:
The getAccessTokenForIssuer
and getAgentTokenResponseForIssuer
methods can be used to obtain an access token for a specific OpenID Provider (issuer). This is useful for applications that only work with a specific provider and therefore know the issuer for which they need an access token, but do not require the user to provide an account configuration shortname.
This function requests an access token from oidc-agent for the provider with issuer_url
. The access token should have scope
scopes, be valid for at least min_valid_period
seconds, and have the audience
audience.
issuer_url
is the issuer url of the provider for which an access token should be obtained.
If min_valid_period
is 0
no guarantee about the validity of the token can be made; it is possible that it expires before it can be used.
If scope
is NULL
, the default scopes for that account are used. So usually it is enough to use NULL
.
application_hint
should be the name of the application that requests an access token. This string might be displayed to the user for authorization purposes.
If audience
is NULL
, no special audience is requested for this access token. This parameter is used to request an access token with a specific audience.
A complete example can look the following:
This function requests an access token from oidc-agent for the the provider with issuer_url
. The access token should have scope
scopes, be valid for at least min_valid_period
seconds, and have the audience
audience.
issuer_url
is the issuer url of the provider for which an access token should be obtained.
If min_valid_period
is 0
no guarantee about the validity of the token can be made; it is possible that it expires before it can be used.
If scope
is NULL
, the default scopes for that account are used. So usually it is enough to use NULL
.
application_hint
should be the name of the application that requests an access token. This string might be displayed to the user for authorization purposes.
If audience
is NULL
, no special audience is requested for this access token. This parameter is used to request an access token with a specific audience.
The function returns an agent_response struct
. The type
element indicates which type is returned, i.e. if an error occurred. On success the response has a token_response struct
that contains the requested access token, the url of the issuer that issued the token and the time when the token expires (in seconds since the Epoch, 1970-01-01 00:00:00 +0000 (UTC)
).
The values can be accessed the following way:
After usage the return value MUST be freed using secFreeAgentResponse
.
A complete example can look the following:
This function requests mytoken from oidc-agent for the accountname
mytoken account configuration. The mytoken should have the properties defined by the passed mytoken_profile
.
accountname
is the shortname of the account configuration that should be used.
application_hint
should be the name of the application that requests the mytoken. This string might be displayed to the user for authorization purposes.
The function returns an agent_response struct
. The type
element indicates which type is returned, i.e. if an error occurred. On success the response has a mytoken_response struct
that contains the requested mytoken as well as several additional information.
The values can be accessed the following way:
After usage the return value MUST be freed using secFreeAgentResponse
.
A complete example can look the following:
accountname
is the shortname of the account configuration that should be used.
application_hint
should be the name of the application that requests the mytoken. This string might be displayed to the user for authorization purposes.
A complete example can look the following:
The getLoadedAccountsList
and getAgentLoadedAccountsListResponse
functions can be used to obtain a list of account configurations that are currently loaded in the agent. This can be used to show users a list from which they can choose an account config to use. It is not necessary to check if an account is loaded through this function before requesting tokens for it.
LIB_PUBLIC char* getLoadedAccountsList(); LIB_PUBLIC struct agent_response getAgentLoadedAccountsListResponse();
This function requests the list of currently loaded accounts from oidc-agent.
The function returns an agent_response struct
. The type
element indicates which type is returned, i.e. if an error occurred. On success the response has a loaded_accounts_response struct
that contains the loaded accounts.
The value can be accessed the following way:
After usage the return value MUST be freed using secFreeAgentResponse
.
A complete example can look the following:
This function requests the list of currently loaded accounts from oidc-agent.
A complete example can look the following:
Since version 4.2.0
it is recommended to use functions that return an agent_response struct
. This struct can hold either a token_response
or an agent_error_response
depending on the success of the call. The agent_error_response struct
holds an error message and MIGHT additionally hold a help message (however, the help message might also be NULL
). If the help message is available it SHOULD be displayed to the user, since it gives useful information how the user can solve the problem.
Before accessing the agent_error_response struct
in an agent_response
one MUST ensure that the agent_response.type
is AGENT_RESPONSE_TYPE_ERROR
. This is also how one checks for the presence of an error.
liboidcagent4
also provides a helper function to easily print an agent_error_response
:
oidc_errno
In most cases it is enough to print an error message to the user. For that usage liboidc-agent4
provides some helper functions:
oidcagent_perror()
can be used similar to perror()
and prints an error message describing the last occurred error to stderr
. oidcagent_serror()
returns the string that describes the error without printing it. The return string MUST NOT be freed. This function behaves similar to strerror(errno)
.
OIDC_SUCCESS
success - no error
OIDC_EERROR
general error - check the error string
OIDC_ENOACCOUNT
the account is not loaded
OIDC_EOIDC
an error related to OpenID Connect happened - check the error string
OIDC_EENVVAR
the environment variable used to locate the agent is not set
OIDC_ECONSOCK
could not connect to the oidc-agent socket - most likely the agent is not running
OIDC_ELOCKED
the agent is locked and first has to be unlocked by the user
OIDC_EFORBIDDEN
the user forbid this action
OIDC_EPASS
wrong password - might occur if the account was not loaded and the user entered a wrong password in the autoload prompt
The function returns only the access token as a char*
. To additionally obtain other information use . After usage the return value MUST be freed using secFree
.
On failure NULL
is returned and oidc_errno
is set (see ).
On failure response.type
will be AGENT_RESPONSE_TYPE_ERROR
and response.error_response
can be accessed (see ). So applications should check response.type
before accessing any of the token response values.
The function returns only the access token as a char*
. To additionally obtain other information use . After usage the return value MUST be freed using secFree
.
On failure NULL
is returned and oidc_errno
is set (see ).
On failure response.type
will be AGENT_RESPONSE_TYPE_ERROR
and response.error_response
can be accessed (see ). So applications should check response.type
before accessing any of the token response values.
mytoken_profile
is a describing the properties of the requested mytoken.
On failure response.type
will be AGENT_RESPONSE_TYPE_ERROR
and response.error_response
can be accessed (see ). So applications should check response.type
before accessing any of the token response values.
This function requests mytoken from oidc-agent for the accountname
mytoken account configuration. The mytoken should have the properties defined by the passed .
mytoken_profile
is a describing the properties of the requested mytoken.
The function returns only the mytoken as a char*
. To additionally obtain other information use . After usage the return value MUST be freed using secFree
.
On failure NULL
is returned and oidc_errno
is set (see ).
On failure response.type
will be AGENT_RESPONSE_TYPE_ERROR
and response.error_response
can be accessed (see ). So applications should check response.type
before accessing any of the token response values.
The function returns the loaded accounts as a space delimited string char*
. To additionally obtain other information ( extended error information) use . After usage the return value MUST be freed using secFree
.
On failure NULL
is returned and oidc_errno
is set (see ).
Since version 4.2.0
it is recommended to use functions that return an agent_response struct
. This approach is described in . For functions that do not return an agent_response struct
must be used. This approach can also be used in addition to the error_response struct
.
If an error occurs in any API function, oidc_errno
is set to an error code. An application might want to check this variable and perform specific actions on some of the errors. A list of important error codes can be found at ; for all error codes refer to the oidc_error.h
header file.