Passing extended context information to HelseID

This functionality is not generally available yet. Contact us for more information.

Background

HelseID allows clients to pass contextual information about the user when requesting a user logon. This is done in the same manner as passing organization information by using an OpenID Connect mechanism called Request Objects in the OpenID Connect specification, or JWT-Secured Autorization Requests (JAR) in OAuth 2.0. These specifications are very similar, and we adhere to both.

To use this feature a resource (scope and claim) must be defined by HelseID. Access to this resource must be given to all clients and apis that need access to this information.

The information may be stored as part of the user session, and will then be available in:

Identity Tokens for clients who have access to the specific scope and that requests this scope in the authorize-call.
Access Tokens to API-resources who have access to the given claim.

If the information isn’t stored in the user session, it will only be available in Access Tokens.

Passing the information

Passing extended context information can be done either by the client as part of the authorize request or by the IDP as part og the user logon process.

The process for passing extended context information from the client is described here.

The process for passing extended context information from an IDP is described here.

Representation of the extended context information in tokens

Valid information which is passed by using the authorization_details structure will be included in JWT tokens, but only if the client and/or API is configured to allow this.

{
  ...
  regular access token claims
  ...
  "CLAIM NAME 1" : {
    "issuer_type":"client",
    "issuer_id": "ClientID or Identity Provider Scheme",
    "issued_at": "timestamp",
    "value": { Json structure here }    
  },
   "CLAIM NAME 2" : {
    "issuer_type":"client",
    "issuer_id": "ClientID or Identity Provider Scheme",
    "issued_at": "timestamp",
    "value": { Json structure here }    
  },
  ...
  regular access token claims
  ...
}

A real-world example

The AMK-project needs information about local role information for the user. This information can either be passed by the client software that requests a logon or it can be passed by the IDP. The name of the claim is amk/context.

The resulting tokens will look as follows:

{
  ...
  regular access token claims
  ...
  "helseid://claims/external/amk-context" : 
  {
    "issuer_type":"client", 
    "issuer_id": "746c1c18-dbc3-4928-a209-1a9aeed9d884",
    "issued_at": "1644329259",
    "value": 
    {
      "roles":
      [
        {"name": "role1"}, 
        {"name": "role2"}
      ]
    }    
  },
  ...
  regular access token claims
  ...
}

The claim is identitcal when included in an ID-Token.

Valid values for issuer_type are either "client" or "idp". Valid values for issuer_id are either the Client ID of the client that signed the Request Object or the IDP scheme for the IDP that was used to logon the user.