Client registration

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:

• OpenID Connect Dynamic Client Registration

• OAuth 2.0 Dynamic Client Registration Management Protocol [RFC7592]

Authentication for dynamic client registration API

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.

Registration access token

To get this registration access token use the command:

waltid-idpkit config --oidc clients token

This will output a valid JWT token to use with the register API endpoint, like this:

Output

[...]
Client registration master token:
eyJraWQiOiJhNGFhM2U4MT[...]nE3jfPqMQlgEhh6l0VbwhbsDjy7Q

Open client registration

To allow unauthenticated client registration requests via the REST API, set the following configuration option in the idp-config.json:

{
  [...]
  "openClientRegistration": true,
  [...]
}

Authentication for existing client management

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!

Register new client

CLI

To register a new client use the register command, like e.g.:

waltid-idpkit config --oidc clients register -n "MyApp" -r "https://myapp.com/redirect_uri"

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:

POST /api/oidc/clients/register HTTP/1.1
[...]
Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJ[...]

{
  "client_name": "MyApp",
  "redirect_uris": [
    "https://myapp.com/redirect_uri"
  ],
  "all_redirect_uris": false
}

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:

{
    "client_secret_expires_at":0,
    "all_redirect_uris":false,
    "registration_client_uri":"https://[...]/api/oidc/clients/EI_9T[...]",
    "client_id_issued_at":1658239641,
    "client_secret":"884DUlIj4[...]",
    "redirect_uris":[
        "https://myapp.com/redirect_uri"
    ],
    "registration_access_token":"eyJraWQi[...]",
    "client_id":"EI_9TT[...]"
}

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

List registered clients

To list all registered clients, type

waltid-idpkit config --oidc clients list

This will output a list of keys and client information objects for all registered clients:

Output

[...]
* EI_9TTRXw0C7gzKNLNfwNEMH1jChqzj-l0n4LUWxYm4:
{
    "client_secret_expires_at":0,
    [...]
    "client_id":"EI_9TTRXw0C7gzKNLNfwNEMH1jChqzj-l0n4LUWxYm4"
}
--------------------
* [...]

Each listed object corresponds to the client registration response, described in the section Register new client.

Get client information by ID

CLI

To get a client information by the client ID, use this command, specifying the ID via the -i ... command argument:

waltid-idpkit config --oidc clients get -i 6s5YcV84Tg7cZ8BM2-b6qcJiHKDTZD8YdQt-cf4eDbM

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.

Update client registration

CLI

To update an existing client registration use the -u ... command flag of the register command, like so:

waltid-idpkit config --oidc clients register -n "MyApp" -r "https://myapp.com/UPDATED_URI" -u EI_9TTRXw0C7gzKNLNfwNEMH1jChqzj-l0n4LUWxYm4

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.

Remove client registration

CLI

Use the remove command to unregister an existing client registration:

waltid-idpkit config --oidc clients remove -i EI_9TTRXw0C7gzKNLNfwNEMH1jChqzj-l0n4LUWxYm4

Example output

[...]
[main] INFO id.walt.idp.oidc.OIDCClientRegistry - Unregistering client EI_9TTRXw0C7gzKNLNfwNEMH1jChqzj-l0n4LUWxYm4
Client removed

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.