Scopes and claims

OAuth 2.0 distinguishes the request from the response: your application asks for scopes, and Kenni delivers claims. A scope is a string in the authorization request; a claim is a key in the ID token, the user-info response, or — for delegated sessions — the access token.

This page explains the relationship between the two and how Kenni shapes the response. The full request mechanic lives on API scopes; the per-scope reference table lives on Standard scopes.

Where claims appear

Claims released by identity scopes show up in three places:

The ID token. Standard OIDC ID-token claims (sub, email, phone_number, …) plus Kenni's identity claims when the corresponding scope is granted. Validate the ID token's signature against JWKS before reading claims from it.
The user-info endpoint. GET /oidc/me returns the same claims using the access token. Useful when you don't want to ship every claim in a long-lived ID token.
The access token. Only when the access token is a JWT (i.e. when at least one custom API scope was requested). A few identity claims — national_id, actor.national_id, delegation_type — are also embedded in the access token so resource servers can authorize without an extra round-trip.

Whichever surface you use, the claim names are the same.

Claim sources

Identity claims come from one of three sources:

Audkenni. Authoritative name and phone number released as part of authentication. Surfaced as audkenni_name and audkenni_phone_number (and the corresponding actor.* claims). Auto-consent.
National registry. Legal name from the Icelandic national registry. Surfaced as registry_name, registry_given_name, and registry_family_name. Released by the registry_name scope. Used when a name claim is requested but no editable display name has been set.
User-managed profile. What the user has chosen to share — display name, picture, editable phone number, and email. These are the scopes that require consent.

The name claim is a convenience: Kenni resolves it from display_name, then registry_name, then audkenni_name, depending on which scopes were granted.

The actor namespace

In a delegated session, two identities are involved: the subject (the person or company being acted on behalf of) and the actor (the human signed in). Kenni keeps them separate by namespacing actor claims:

// ID token for an employee acting as their company
{
  "sub": "<company-account-id>",
  "national_id": "<company-kennitala>",
  "company_name": "Example ehf.",
  "actor": {
    "sub": "<employee-account-id>",
    "national_id": "<employee-kennitala>",
    "audkenni_name": "Anna Jónsdóttir",
  },
  "delegation_type": ["c:procurator"],
}

Root claims (sub, national_id, company_*, …) describe the subject. Nested actor.* claims describe the human. The delegation_type claim lists the delegation types the actor holds for this subject — a single delegated session can carry several types at once.

In a self-login (no delegation), actor is omitted entirely; the actor and the subject are the same person, and the root claims describe them directly.

Subject types and scope filtering

Some scopes only apply to one kind of subject. display_name, email, and picture describe a person; company_name, company_logo, and the rest of the company_* family describe a legal entity. Kenni filters automatically:

A request for company_email against an individual subject is silently dropped.
A request for display_name against a company subject is silently dropped.
The consent screen only shows the scopes that actually apply to the current subject type.

This means the same scope list can be reused for an individual login and a company-delegated login without your application special-casing.

Each scope has an autoConsent flag baked in:

Auto-consent scopes are released as soon as the user authenticates. openid, national_id, audkenni_name, audkenni_phone_number, and the company-registry scopes are all auto-consent.
Requires-consent scopes only release if the application has the Consent feature enabled and the user has agreed on the consent screen. display_name, picture, email, the editable phone_number, and the editable company_* scopes all require consent.

If consent is disabled on an application, requesting a non-auto-consent scope is a no-op — Kenni won't fail the request, but the claim won't be released either.