Assisted Login API
Introduction
Keycloak provides two custom APIs for assisted login, one for employees and one for citizens.
The employee API is used for creating and managing assisted login sessions, and the citizen API is used for obtaining an Assisted login token, used for authenticating a citizen.
For more internal information about assisted login, see: https://ehealth-dk.atlassian.net/wiki/spaces/PI/pages/4235427841 .
Assisted Login Session States
Flow diagram and TTLs
There are 3 TTLs at play:
Asssisted Login Session TTL - this is the initial TTL of the Assisted Login session when it is created. Defaults to 24 hours.
Status Token TTL - The TTL of the Status Token received in the
CLAIMcall. Defaults to 24 hours.
After a CLAIM call, the TTL of the whole assisted login session resets and takes on the value of the Status Token TTL.
Assisted Login Token TTL - defaults to 1 minute.
Employee API
Access Control
The employee API can be used by authorized practitioner users, using bearer token authentication.
To be able to participate in an Assisted Login flow, the employee must have a JWT:
that has been provided by a whitelisted client
with user type
PRACTITIONERwith the privilege
$assist-login. This privilege is part of the FUT role calledLogin Assistor.
For more info, see OIO BPP Role to eHealth Privilege mapping
User Guide
The employee API supports 2 queries (search, get) and 4 commands (create, approve, revoke, archive).
Create Assisted Login Session
This is the first command in the flow. It happens when an employee initiates the Assisted Login process for a citizen.
The request body contains the FHIR Patient ID of the citizen that needs to login using Assisted Login. As a prerequisite, the Patient FHIR resource must already exist in the infrastructure.
Search Assisted Login Session
Use this query to search existing Assisted Login sessions.
The API optionally accepts a filter in the request body. Using this, the employee can filter and receive only Assisted Login sessions related to a patient or only sessions having a specific state.
If the filter is omitted, the server returns all sessions relevant for the employee.
Get Assisted Login Session
Use this query to get information about a specific session.
Provide the ID of the Assisted Login session as a parameter to the query.
Approve Assisted Login Session
Use this command to set a session’s status to APPROVED. This can only be done on a session after it has been claimed by a citizen and currently has status PENDING.
Provide the ID of the session to be approved in the request body.
Once a session is APPROVED, one can use Assisted Login API to activate the session.
Revoke Assisted Login Session
Use this command to revoke a session. A REVOKED session cannot be used to login a user. If a user has already logged in with a session and later that same session is revoked, the user is logged out. Revoking is not reversible.
Provide the ID of the session to be revoked in the request body.
Archive Assisted Login Session
Use this command to archive a session. Only REVOKED and EXPIRED sessions can be archived. Archiving is useful to mark sessions that are no longer of interest. In subsequent queries to search Assisted Login sessions, the employee can choose to hide the archived sessions.
Provide the ID of the session to be archived in the request body.
Open API specification
Citizen API
Access Control
The citizen API can be used by authorized service account users, using bearer token authentication.
The citizen is making calls to Keycloak through a service user (see Oprettelse og brug af Servicebruger on how to order one). As such the JWT used in the requests must:
have the user type
SYSTEMhave the privilege
$assisted-system-login. This role is setup on vendor clients enabled for Assisted Login.
User Guide
The citizen API supports 1 command (claim) and 1 query (check-status).
Claim Assisted Login Session
A citizen can use this command to claim a session. The session must have been created previously and have status NEW. If the request is successful, the session transitions into status PENDING.
The request must contain the identifier of the citizen that is the subject of the session. Right now only CPR identifiers are supported (using type urn:oid:1.2.208.176.1.2, see https://hl7.dk/fhir/core/StructureDefinition-dk-core-cpr-identifier.html )
Note: This command changes the expiry time of the session as explained below:
The response contains a status check token and an expiry date.
The status check token can be used by the citizen in subsequent requests to check if they have been granted permission to login using the
Check Assisted Login Session Statusquery.The returned expiry date refers to both when the status check token expires and when the Assisted Login session expires.
In case the server cannot find a session for the citizen identified by the request body, it will not return an error! Instead, it will create a fake status check token. Read more about fake claims: https://ehealth-dk.atlassian.net/wiki/spaces/PI/pages/edit-v2/4235427841#Fake-claims-mechanism
Check Assisted Login Session Status
The citizen can use this query to check if the session has been approved by the employee.
The request must contain a status check token from a Claim Assisted Login session request.
If it is a fake status check token, the server will always respond that the status of the session is PENDING.
If the status check token is genuine and the employee as not yet approved it, the server will respond with PENDING. If the employee has approved it, the server will return status APPROVED and an assisted login token. The assisted login token is used in the Assisted Login grant to get an access token and refresh token for the user.