Scopes and claims

When your application initiates an authentication, it sends a “scope” parameter which lists the API scopes and identity scopes needed by the application.

plain text
scope=openid profile @myteam.is/some-api-scope

Example

As part of the authentication, Kenni verifies this value and uses it to customise the resulting tokens.

API scopes

These start with the team domain (@myteam.is in the example above). Kenni will verify that the client has been authorised to access the requested API scopes, and add them to the scope claim of authenticated access tokens.

The application can then send these access token to your APIs to request application resources. The API needs to verify the validity of the access tokens, and authorise access based on the scope claim.

See API Scopes and Authorizing API Scopes for more information about creating API scopes and authorising applications to request them.

Identity scopes

These are built into Kenni and can be requested by the application to get specific user information in the ID token.

Make sure to keep an eye on this page, as more identity scopes and claims will be implemented.

openid

The openid scope is required to authenticate users. It provides one user-specific claim to ID tokens:

sub uniquely identifies the user. This value does not include any sensitive information, like the user’s kennitala. Every time the user logs in with Kenni into any of your applications, they have the same sub. These identifiers are team specific.

profile

The profile scope provides basic profile information about the user. It provides one claim to ID tokens:

name which is the full name of the user. Currently this is the name which is stored on the user’s electronic ID from Auðkenni. It may not match the user’s current legal name.

Later we may add more claims here, including up-to-date name fields from Þjóðskrá.

national_id

The national_id scope adds the user’s Icelandic national ID (kennitala) as a claim to the ID token:

national_id for the user. Formatted without dashes (1234567890)

You should be careful about validating this value or parsing information from it. Some users may authenticate with a kerfiskennitala which has random digits starting with 8 or 9. Also, Kenni test users may not have valid national IDs.

phone_number

The phone_number scope adds the user’s phone number as a claim to the ID token:

phone_number of the user. Formatted without dashes (1234567) This claim is only provided if the user has authenticated to Kenni with a SIM-based electronic ID.

Offline access

The offline_access scope is different from other identity scopes. It adds a refresh token to the authentication which can be used to request new access tokens without user interaction. There are two common use cases for refresh tokens:

Extend application sessions, which employ short-lived access tokens, for days, months or years.

Access user resources from backend systems when the user is not around, eg in a CRON job.