Client Creation
Flow
After creating a client system with an API key, which is described in the following sections, the flow is like this:
- Create a client draft using the API
- Open a web browser and direct the end user to the confirmation page in Selvbetjening for HelseID
- The end user confirms the client
- The browser redirects to your local http server
- With a successful status, you can request access tokens from HelseID
- Check the status of the client's access to the specified scopes
End User Client System Selvbetjening API Selvbetjening Portal HelseID STS
| | | | |
| | client draft (1) | | |
| |----------------->| | |
| | client id | | |
| |<-----------------| | |
| | | | |
| | open url in browser (2) | |
| |-------------------------------------->| |
| | | |
| | Ask for confirmation | |
|<---------------------------------------------------| |
| Confirm (3) | |
|--------------------------------------------------->| |
| | | |
| | Redirect with status (4) | |
| |<--------------------------------------| |
| | |
| | Request access token for Selvbetjening API (5) |
| |------------------------------------------------------->|
| |<-------------------------------------------------------|
| | |
| | check status (6) |
| |----------------->|
| |<-----------------|
Prerequisites
- The client system must be registered through the Selvbetjening portal, and cannot be a multi-tenant system.
- The end user must have the required access in Altinn. See this documentation for information about the roles in Altinn (in Norwegian)
Authentication
To be able to create clients for a client system, the system first needs an API key. A key can be generated on the "automatisering" tab on the client system administration page.
The API key is passed to requests as a header with name "api-key". Example:
POST /v0.1/client-drafts HTTP/1.1
Host: api.selvbetjening.nhn.no
api-key: D-J1mmTqICvFRK3sgBZVKCqcBXq6NFhSZPjgPOgCxO8
The API key can be distributed with the client system installations. It is only used for creating client configurations. After this, the system installation must use its newly created HelseID client for further API calls.
Creating a client draft
POST to the client-drafts endpoint to create a new draft. Example:
POST /v0.1/client-drafts HTTP/1.1
Host: api.selvbetjening.nhn.no
api-key: D-J1mmTqICvFRK3sgBZVKCqcBXq6NFhSZPjgPOgCxO8
Content-Type: application/json
Accept: application/json
Content-Length: 926
{
"organizationNumber": "942110464",
"apiScopes": [
"nhn:selvbetjening/client",
"conceptos:eksempel/scope"
],
"publicJwk": "{\"foo\":\"bar\",\"kty\":\"RSA\",\"e\":\"AQAB\",\"use\":\"sig\",\"kid\":\"j9YVjN3VtXzCJ4-L4jyOlEjuJxQw7ojerRR8A9TbYI8\",\"alg\":\"RS256\",\"n\":\"suhcbnxLfPGW23xT3v3dePxpdUyC1sbXd_KWOf0GgwbGXleGG59BtaXXWZTSljXk8IQuKI43AhUDBGMWnuRR7IgMeh4HBSZgFfdAS9xL5qtp9SB1WmiUUF0DCjBUc9GzoRCS629cUdKJdGvpiTMyh0UXgl0ahMvqBbFLbJDwfkl_z2X-6tLpytvgsNeHHDtF35Xczo37UlbWK-zzennwLTGQrHl1E5UxdYiLQJb7x0Yy8yvWNCf8hGfDhEYnP6XQdDgmDJ9c7lEV-uyxr3oJtRGpThTZvY0jyT6_TZz20WZNvtVm6f52gfaLguDYfNx9Ff68bw7Cy1ELyxe5MDCyWQ\"}"
}
A successful response includes the client id for the new draft. Example:
{
"clientId": "4095f02f-008e-4413-98ef-5c040eb28b29"
}
See swagger for parameter details.
Note: nhn:selvbetjening/client is required in order to check status (step 6).
User confirmation
After a draft has been created, the system must open Selvbetjening in a browser using this URL template: https://selvbetjening.nhn.no/confirm-client/{clientId}?redirectPort={redirectPort}&redirectPath={redirectPath}.
As an example, with a response from the client draft endpoint like this:
{
"clientId": "4095f02f-008e-4413-98ef-5c040eb28b29"
}
and the system is listening for callbacks at port 8080 and path /client-confirm, the system should open URL https://selvbetjening.nhn.no/confirm-client/4095f02f-008e-4413-98ef-5c040eb28b29?redirectPort=8080&redirectPath=/client-confirm.
Note that the URL must be opened within 10 seconds of the client draft creation, and it can only be accessed from the same browser session after first being opened. The user must confirm the client within 3 hours of opening the page. This is a security measure to mitigate phishing attempts.
The end user will be asked to authenticate themselves and to confirm the client creation. When the user interaction is completed, the web page redirects back to the system using the port and path provided, and include a status. It will always redirect to http://localhost. For the example above, it would redirect to http://localhost:8080/client-confirm?status=Success when successful.
Statuses:
Success: User successfully confirmed the client draft, and the client is ready to be used.UserAccessRequested: User requested access to represent the organization in order to confirm the client at a later time. The client is not ready.Error: An error occurred. The client is not ready.
Checking status
On success, check the access to the specified scopes by using the /client-status endpoint.
If the status looks good, you are ready to request access tokens for APIs and start calling them.
Note that some APIs require manual approval, some APIs require signed terms of use, and some APIs will automatically approve your access. Thus you may have a mixed status where some scopes are ready to be used, while others are not.
Example Implementation
See example C# implementation on GitHub.
Handling expired client secrets (keys)
If an application is not used for long period of time, the public key of the client secret will not be automatically updated by the software, and might expire.
To handle this, do the following:
- Generate a new keypair
- Log into Selvbetjening and upload the new public key for the client configuration
- Make the application use the new private key
End users of the application might need assistance from the software vendor in order to perform this "revival" of the HelseID integration.
Please note: As long as the application is used regularly, and the public key is updated, the problem of key expiration will not occur.