How to create unique client attributes for an API

Owned by Dag Østerhagen
Last updated: Jan 03, 2024 by Øyvind Bech
1 min read

HelseID supports creation of claims associated with a client which may be unique for a particular API - “audience specific client claims”.

A use case for this is that an API need to associate a client with some API-internal identifier.

Defining which claims an API support

Before a claim of this type can be associated with a client, the API have to define the name of the claims it support.

Naming of claims (aka “claim types”)

An API can create any number of allowed claims of this type. All such claims are prefixed with a namespace unique for the audience: “[audience]/client/claims/[some_name]”.

For example, an API with audience (name) “nhn:test_api” and claim “internal_id”, the full name will be “nhn:test_api/client/claims/internal_id”.

Validation rules for claim names

  • Legal characters for claim names are a-z, 0-9, . (dot), - (hyphen), _ (underscore)

    • No uppercase-letters

  • Max length is 100 characters

Setting API-specific claims on clients

Any claim defined by an API may be set on a client with a value following these rules:

  • Legal characters for claim values are a-z, A-Z, øæå, ØÆÅ, 0-9, . (dot), - (hyphen), _ (underscore)

    • Uppcase-letters are allowed

  • Max length of 50 characters

Inclusion in tokens.

API-specific claims will be included in access tokens with an audience-claim (“aud”) corresponding to the name of the API. An access token with multiple audiences will contain whatever API-specific claims is set on the client for all the audiences in the token.

API-specific claims will never be included in identity tokens.

I want to use this, what do I do now?

HelseID self-service now supports this mechanism. If the API concerned supports this kind of claim, it will be available to use when creating a new client.