Client Registration

Clients and why we need one

To use the IDP Kits functionality, we need to register our frontend application as client and collect client_id and client_secret. Those credentials will be used by the frontend to make requests to the IDP Kit, which will in turn ask the user if they want to sign in and check if they are allowed to do so, based on the Verifiable Credential in their wallet. After collecting the consent of the user and validating that they are allowed to log in, the IDP Kit will give the frontend a secret with which it can request information about the authenticated the user.

The exchange of information between the client, which is in our case the frontend application and the authorization server which is the IDP Kit are based on the OpenID Connect standards. I won't go into more detail here, but you can learn more about it in the concept section or watch this great illustrative video from OktaDev, which gives a great overview about OpenID Connect. To understand how the base ideas are then translated to the Verifiable Credential use case, you can dive into Identity provision via SSI.

Client registration

Now that we know what we need and why we need it, let's go ahead and create our first client. Depending on the situation and personal preference, there are two options available: CLI tool, API.

CLI Tool

Register client

To register a new client, we can use the clients register command provided under the OIDC scope of the CLI tool.

idpkit config --oidc clients register -n "myFrontend" -r "http://localhost:3000/api/auth/callback/walt-id-ssi"

Parameter description

• -n - Name of the client

• -r - The redirect URL which should be used in the OIDC flow

Other Options:

• --all-redirect-uris - Redirect can go to any URL specified in the OIDC flow requests

Why we set a redirect URL?

If we set a redirect URL we can make sure that no other party will be able to use our authentication flow, even if they would get access to our secrets. For our project we set the URL http://localhost:3000 as this will be the URL under which our frontend application will be hosed. Later if we were to put the application into production it would be something like https://applicationName.com. In this case we would need to update our registerd client and reflect the new redirect URL.

Update client

To update an existing client, we can use the clients register command provided under the OIDC scope of the CLI tool and add the -u flag to note that we want to change a client with the specified id.

idpkit config --oidc clients register -n "myFrontend" -r "https://applicationName.com" -u "client_id"

Parameter description

• -n - Name of the client

• -r - The redirect URL which should be used in the OIDC flow

• -u - The ID of the client we would like to update

Learn more CLI tool commands and options.

API

Exposing the API

In order to use the API, we need to launch it first.

idpkit run

Register client

To register a new client, we can make a POST request to /api/oidc/clients/register. However, by default the registration of new clients via API, requires you to authenticate. Providing the master_token in the header of the request makes sure the registration goes through.

Get master_token

To get the master_token we can execute the clients token command under the OIDC scope of the CLI tool.

idpkit config --oidc clients token

Register client request

We need to replace master_token in the Authorization request header before executing.

curl -X POST http://localhost:8080/api/oidc/clients/register \
-H "Authorization: Bearer master_token" \
-H "Content-Type: application/json" \
-d '{"client_name": "MyApp","redirect_uris": ["http://localhost:3000/api/auth/callback/walt-id-ssi"],"all_redirect_uris": false}'

Save the response somewhere, where you can later retrieve the information. Most importantly, the client_id and client_secret.

Why we set a redirect URL?

If we set a redirect URL we can make sure that no other party will be able to use our authentication flow, even if they would get access to our secrets. For our project we set the URL http://localhost:3000 as this will be the URL under which our frontend application will be hosed. Later if we were to put the application into production it would be something like https://applicationName.com. In this case we would need to update our registerd client and reflect the new redirect URL.

Update client

To update a client we make a PUT request to the /api/oidc/clients/<client_id> and provide the registration_access_token, which we got during client registration. In order for the update to go through, we need to provide the whole response we got from the client registration step in the update request body.

Make sure before executing the request, to replace the clientid in the request URL and the registration_access_token

curl -X PUT http://localhost:8080/api/oidc/clients/96baIcn5YUD7z2H69nPkd1KrizaixBs3IWcRS_qDCmM \
-H "Authorization: Bearer eyJraWQiOiI2YzA2M2Y3NjBjNGM0M2VlYjNkMDNmNmQzODQ1NGU1OSIsInR5cCI6IkpXVCIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiI5NmJhSWNuNVlVRDd6Mkg2OW5Qa2QxS3JpemFpeEJzM0lXY1JTX3FEQ21NIn0.RgNdqkK_o2paGvJhM95jtrEqUPTiIQVB4kZFY8QIAKypAFC2Iq6WTll_nyAM_osbSluEQGlQvwpFf4xnF4aM2JxAkeTE1SCHA3EWODIn2uDzKDFkpNOdw9xJHiIstqy2WK1x8jsi1RK_iaa6gf_3Pm0xazEekkjvRGtXn9jfoyYiUVN75EJDU_pbSju9vXNIO2nd2FIBzmyd3DWohat0Lgb1m7fv8eFWXjC-PYICrv-qLP7-cVuhNnrkmCXSIwhXcXbdjyqAB6cgFVqecUaiTCi928uIxTRsAS7_vnPCiWxnPTGCTGsE05hspbnTuubxs0oYGFOZ7adURvCkgxFsHw" \
-H "Content-Type: application/json" \
-d '{"client_secret_expires_at": 0, "all_redirect_uris": false, "registration_client_uri": "http://localhost:8080/api/oidc/clients/96baIcn5YUD7z2H69nPkd1KrizaixBs3IWcRS_qDCmM", "redirect_uris": ["http://localhost:3000"], "client_id_issued_at": 1662617990, "client_secret": "hMAi7khf6cgZ2wRXlN89FQ1zB99654j8cyF4O3AAmk0", "client_name": "MyApp", "registration_access_token": "eyJraWQiOiI2YzA2M2Y3NjBjNGM0M2VlYjNkMDNmNmQzODQ1NGU1OSIsInR5cCI6IkpXVCIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiI5NmJhSWNuNVlVRDd6Mkg2OW5Qa2QxS3JpemFpeEJzM0lXY1JTX3FEQ21NIn0.RgNdqkK_o2paGvJhM95jtrEqUPTiIQVB4kZFY8QIAKypAFC2Iq6WTll_nyAM_osbSluEQGlQvwpFf4xnF4aM2JxAkeTE1SCHA3EWODIn2uDzKDFkpNOdw9xJHiIstqy2WK1x8jsi1RK_iaa6gf_3Pm0xazEekkjvRGtXn9jfoyYiUVN75EJDU_pbSju9vXNIO2nd2FIBzmyd3DWohat0Lgb1m7fv8eFWXjC-PYICrv-qLP7-cVuhNnrkmCXSIwhXcXbdjyqAB6cgFVqecUaiTCi928uIxTRsAS7_vnPCiWxnPTGCTGsE05hspbnTuubxs0oYGFOZ7adURvCkgxFsHw", "client_id": "96baIcn5YUD7z2H69nPkd1KrizaixBs3IWcRS_qDCmM"}' \

Learn more API endpoints and options or visit the swagger docs.