To connect to the OIDC APIs, a client application needs to be registered and has to authenticate itself using its client_id and client_secret.
See section Client registration, for details on how to register a client and obtain the client_id and client_secret values.
Endpoints affected by the client authentication are
token_endpoint
/api/oidc/token
pushed_authorization_request_endpoint
/api/oidc/par
The supported client authentication methods are published in the discovery document (token_endpoint_auth_methods_supported
) on the well-known openid-configuration endpoint.
Currently supported authentication methods:
client_secret_basic
the client needs to add the client_id and client_secret as Basic HTTP Authorization header, when calling the pushed authorization request or token endpoints.
The IDP Kit provides a command line interface (CLI) to register and manage clients. Furthermore, the dynamic client registration and management APIs are provided, according to the specifications in:
To register a new client via the dynamic client registration API, authentication using the registration access token is required by default. The IDP Kit can be configured to allow unauthenticated client registration.
To get this registration access token use the command:
This will output a valid JWT token to use with the register
API endpoint, like this:
Output
To allow unauthenticated client registration requests via the REST API, set the following configuration option in the idp-config.json
:
For managing registered clients, i.e. get, update or removal of client information, via the dynamic client management API, you have to use the registration_client_uri
and registration_access_token
as returned by the client registration response for the specific client.
The registration access token, for registering new clients, does NOT grant permission to manage existing client registrations!
CLI
To register a new client use the register
command, like e.g.:
To specify multiple redirect_uris, repeat the -r ...
flag for each URI.
Use --all-redirect-uris
and omit the -r ...
flags, to allow all redirect URIs for this client.
Use -u <client_id>
to update an existing client by its ID, instead of creating a new registration.
REST API
[POST] /api/oidc/clients/register
Post a client registration request object to this endpoint, using the registration access token described above, like shown in this simple example:
If open client registration is enabled, the registration access token in the Authorization
header can be omitted in this request.
Result
In case of success, the CLI and REST API will output a client information object, corresponding to the client registration response from the OIDC spec: Client Registration Response.
Example:
This example response has the following properties:
client_secret_expires_at
: Expiration timestamp of client secret, or 0 if no expiration
all_redirect_uris
: Specific to IDP Kit: allow all redirect URIs for this client if redirect_uris is empty or not set
registration_client_uri
: URI of API to get, update or delete this client information
registration_access_token
: access token for using registration_client_uri
API to get, update or delete this client information
client_id_issued_at
: Timestamp of first registration of this client
client_secret
: Client secret to use for token endpoint authentication method
client_id
: Client id to use for token endpoint authentication method
redirect_uris
: Array of redirect URIs that are allowed for this client
To list all registered clients, type
This will output a list of keys and client information objects for all registered clients:
Output
Each listed object corresponds to the client registration response, described in the section Register new client.
CLI
To get a client information by the client ID, use this command, specifying the ID via the -i ...
command argument:
REST API
[GET] /api/oidc/clients/<client_id>
To get the client info via the dynamic client management API, make a GET
call to the registration_client_uri
using the registration_access_token
given in the client information obtained from the initial client registration or the latest client update.
Clients MUST use the registration_client_uri
as returned by the server in the registration response object, and MUST NOT construct the URL from component pieces, such as API endpoint and client ID.
Result
The output is a client information object, that corresponds to the client registration response, described in the section Register new client.
CLI
To update an existing client registration use the -u ...
command flag of the register
command, like so:
All required parameters MUST be specified in the update command, as the existing registration will be replaced but not merged with parameters given in this command!
REST API
[PUT] /api/oidc/clients/<client_id>
Post the updated client information, including all required parameters, to the registration_client_uri
using the HTTP PUT
method and the registration_access_token
given in the client information obtained from the initial client registration or the latest client update.
All required parameters MUST be included in the update request body, as the existing registration will be replaced but not merged with object given in the update request!
Clients MUST use the registration_client_uri
as returned by the server in the registration response object, and MUST NOT construct the URL from component pieces, such as API endpoint and client ID.
Result
The output is a client information object, with the updated registration information, that corresponds to the client registration response, described in the section Register new client.
CLI
Use the remove
command to unregister an existing client registration:
Example output
REST API
[DELETE] /api/oidc/clients/<client_id>
To unregister the client via the dynamic client management API, make a DELETE
request to the registration_client_uri
using the registration_access_token
given in the client information obtained from the initial client registration or the latest client update.
The result of a successful delete request, is an empty response with the HTTP response code 204 No Content
.
Clients MUST use the registration_client_uri
as returned by the server in the registration response object, and MUST NOT construct the URL from component pieces, such as API endpoint and client ID.
By default, the OIDC Manager creates an RSA key for RS256 token signatures on first startup. On subsequent startups, the same key will be used again.
If you want to enforce a certain key or key type for token signatures, you may use the config
command, providing the key management functions of the SSI Kit to create a key.
The following key and token signature types are currently supported:
Signature | Key | Hash |
---|---|---|
The chosen key type implicitely defines the signature and hash type, according to the table above.
In the following example, I will show how to manually create an RSA key for the OIDC manager using the config command of the IDP Kit:
This command will generate an RSA key, save it in the key store, in the context of the OIDC manager, and prints the key ID:
Output:
To list all the available keys in the OIDC Manager context, you can type:
Output:
Now, to configure the key generated above, copy the key ID printed by the command, and paste it into the configuration file, like so:
RS256
RSA 2048
SHA256
EdDSA
EdDSA_Ed25519
SHA256
ES256K
ECDSA_Secp256k1
SHA256
In order to support mapping of SSI credential data or NFT token metadata to standard OIDC scopes and claims, you have to define which credential types or NFTs are required and which property or trait in the credential/NFT data contains the claimed information.
If the required VP token claim or NFT token claim cannot be derived from the authorization request, one can configure default claims, that will be sent to the SSI or NFT wallet in this case.
Based on the configured claim mappings and the required claims or scopes in the authorization request from the client application, the IDP will decide which credentials or NFTs need to be requested from the user wallet.
This list of claim mappings will be reflected in the well-known openid-configuration discovery document, publishing the supported claims and scopes (scopes_supported
, claims_supported
).
In general, we can configure the claim mappings in the IDP configuration file, in the claimConfig
property, which contains an array of mapping objects for verifiable credentials: vc_mappings
and NFT tokens: nft_mappings
.
Example:
Each mapping object contains the following properties:
scope
: One or multiple OIDC scope(s), this claim belongs to. E.g. profile
, address
, email
, etc.
claim
: The name of the OIDC claim. E.g. name
, given_name
, family_name
, email
, etc.
credentialType
: The type of credential from which the claim information should be read
valuePath
: A JSON path leading to the claim value in the credential data. This supports multiple JSON paths separated by blanks, to concatenate values, like shown in the example claim name
in the profile
scope.
Example:
Each mapping object contains the following properties:
scope
: One or multiple OIDC scope(s), this claim belongs to. E.g. profile
, address
, email
, etc.
claim
: The name of the OIDC claim. E.g. name
, given_name
, family_name
, email
, etc.
chain
: The chain on which the NFT must be held by the user
smartContractAddress
: The address of the NFT collection, which the user must hold an NFT of
trait
: Key of the NFT metadata, which will be used to fill this particular claim value
If the authorization request from the client application contains only the scope vp_token
or nft_token
, but does not specify any further scopes or claims to derive the required nft or verifiable presentation from, the IDP Kit will fall back to the default claims configured here:
The default claim used to fulfill an NFT token request.
Example:
The default nft token claim defines the following properties:
chain
: The chain on which the NFT must be held by the user
smartContractAddress
: The address of the NFT collection, which the user must hold an NFT of
The default claim used to request a verifiable presentation from the SSI wallet:
Example:
The default vp token claim contains a presentation_definition object as specified by the DIF specification: Presentation Definition.
In this example, a filter for credentials with the type VerifiableId
is definied.
In this section we look at the configuration of the OIDC Manager sub module.
If you haven't already, you may want to familiarize yourself with the basic IDP Kit Configuration, the Data Root and the Command Line Interface, in the previous sections, before moving on.
The configuration of the OIDC manager can be adapted, by modifying the file
config/idp-config.json
Configure the URL via which the IDP/OIDC API will be reachable from an external source (i.e. from the client application):
By default, the OIDC Manager creates an RSA key for RS256 token signatures on first startup.
To enforce a certain key or key/signature type, specify the key id in the configuration file like this:
Go to section Keys and signatures for details on how to create keys and on supported signature types.
To allow unauthenticated client registration via the dynamic client registration API, specify the following configuration option:
See also section Client registration for more details about registering and managing clients.
If the authorization mode, SIOP
or NFT
, can not be derived from the scopes and claims specified in the authorization request by the client application, or the request is ambiguous, the IDP Kit will choose the preferred mode based on this configuration option:
To configure how the IDP Kit maps the scopes and claims from the authorization request to verifiable presentation requests for SSI, or NFT claims, one can define claim mappings and default claims in the claim configuration object. E.g.:
See section Claim mapping for details about this configuration object and the available options.
Here's a complete example for the idp-config.json: