liboidc-agent4
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.
Requesting an Access Token For an Account Configuration
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 request an access token for a provider.
getAccessToken
It is recommended to use getAgentTokenResponse
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.
Parameters
accountname
is the shortname of the account configuration that should be used.If
min_valid_period
is0
no guarantee about the validity of the token can be made; it is possible that it expires before it can be used.If
scope
isNULL
, the default scopes for that account are used. So usually it is enough to useNULL
.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
isNULL
, no special audience is requested for this access token. This parameter is used to request an access token with a specific audience.
Return Value
The function returns only the access token as a char*
. To additionally obtain other information use getAgentTokenResponse
. After usage the return value MUST be freed using secFree
.
On failure NULL
is returned and oidc_errno
is set (see Error Handling).
Example
A complete example can look the following:
getAgentTokenResponse
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.
Parameters
accountname
is the shortname of the account configuration that should be used.If
min_valid_period
is0
no guarantee about the validity of the token can be made; it is possible that it expires before it can be used.If
scope
isNULL
, the default scopes for that account are used. So usually it is enough to useNULL
.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
isNULL
, no special audience is requested for this access token. This parameter is used to request an access token with a specific audience.
Return Value
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
.
On failure response.type
will be AGENT_RESPONSE_TYPE_ERROR
and response.error_response
can be accessed (see Error Handling). So applications should check response.type
before accessing any of the token response values.
Example
A complete example can look the following:
Requesting an Access Token For a Provider
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.
getAccessTokenForIssuer
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.
Parameters
issuer_url
is the issuer url of the provider for which an access token should be obtained.If
min_valid_period
is0
no guarantee about the validity of the token can be made; it is possible that it expires before it can be used.If
scope
isNULL
, the default scopes for that account are used. So usually it is enough to useNULL
.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
isNULL
, no special audience is requested for this access token. This parameter is used to request an access token with a specific audience.
Return Value
The function returns only the access token as a char*
. To additionally obtain other information use getAgentTokenResponseForIssuer
. After usage the return value MUST be freed using secFree
.
On failure NULL
is returned and oidc_errno
is set (see Error Handling).
Example
A complete example can look the following:
getAgentTokenResponseForIssuer
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.
Parameters
issuer_url
is the issuer url of the provider for which an access token should be obtained.If
min_valid_period
is0
no guarantee about the validity of the token can be made; it is possible that it expires before it can be used.If
scope
isNULL
, the default scopes for that account are used. So usually it is enough to useNULL
.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
isNULL
, no special audience is requested for this access token. This parameter is used to request an access token with a specific audience.
Return Value
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
.
On failure response.type
will be AGENT_RESPONSE_TYPE_ERROR
and response.error_response
can be accessed (see Error Handling). So applications should check response.type
before accessing any of the token response values.
Example
A complete example can look the following:
Requesting a Mytoken
getAgentMytokenResponse
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
.
Parameters
accountname
is the shortname of the account configuration that should be used.mytoken_profile
is a mytoken profile describing the properties of the requested mytoken.application_hint
should be the name of the application that requests the mytoken. This string might be displayed to the user for authorization purposes.
Return Value
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
.
On failure response.type
will be AGENT_RESPONSE_TYPE_ERROR
and response.error_response
can be accessed (see Error Handling). So applications should check response.type
before accessing any of the token response values.
Example
A complete example can look the following:
getMytoken
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
.
Parameters
accountname
is the shortname of the account configuration that should be used.mytoken_profile
is a mytoken profile describing the properties of the requested mytoken.application_hint
should be the name of the application that requests the mytoken. This string might be displayed to the user for authorization purposes.
Return Value
The function returns only the mytoken as a char*
. To additionally obtain other information use getAgentMytokenResponse
. After usage the return value MUST be freed using secFree
.
On failure NULL
is returned and oidc_errno
is set (see Error Handling).
Example
A complete example can look the following:
Getting a List of Loaded Accounts
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();
getAgentLoadedAccountsListResponse
This function requests the list of currently loaded accounts from oidc-agent.
Return Value
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
.
On failure response.type
will be AGENT_RESPONSE_TYPE_ERROR
and response.error_response
can be accessed (see Error Handling). So applications should check response.type
before accessing any of the token response values.
Example
A complete example can look the following:
getLoadedAccountsList
This function requests the list of currently loaded accounts from oidc-agent.
Return Value
The function returns the loaded accounts as a space delimited string char*
. To additionally obtain other information ( extended error information) use getAgentLoadedAccountsListResponse
. After usage the return value MUST be freed using secFree
.
On failure NULL
is returned and oidc_errno
is set (see Error Handling).
Example
A complete example can look the following:
Error Handling
Since version 4.2.0
it is recommended to use functions that return an agent_response struct
. This approach is described in Using the Error Response Structure. For functions that do not return an agent_response struct
oidc_errno
must be used. This approach can also be used in addition to the error_response struct
.
Using the Error Response Structure
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
:
Using oidc_errno
oidc_errno
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 Error Codes; for all error codes refer to the oidc_error.h
header file.
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)
.
Error Codes
error code | explanation |
---|---|
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 |
Last updated