# Kenni Documentation — Full Corpus
The complete contents of https://developers.kenni.is/docs, concatenated for use in LLM context windows. Each section below is the raw markdown of one page; section dividers mark page boundaries.
Last updated: 2026-05-07
---
# Overview
Kenni is an Iceland-first identity provider built on **OpenID Connect** and **OAuth 2.0**. Drop it into your application to get specification-compliant authentication, passkey-based sign-in, and access to Iceland's national identification flows — without writing your own auth.
These docs cover everything from your first integration to advanced features like delegations and single sign-on.
## Start here
If you're new to Kenni, the [Get started](https://developers.kenni.is/docs/get-started) guide walks you through creating a team and your first application in a few minutes.
## Using these docs with AI
Append `.md` to any docs URL for the raw markdown source — e.g. `https://developers.kenni.is/docs/applications.md`. The full corpus is also published in two AI-friendly forms:
- [`/llms.txt`](https://developers.kenni.is/llms.txt) — [llmstxt.org](https://llmstxt.org)-format index pointing to every page's raw markdown with a one-line description.
- [`/llms-full.txt`](https://developers.kenni.is/llms-full.txt) — the entire docs corpus concatenated into a single file for "drop into the context window" use.
Most agents don't auto-discover these yet, so point yours at the URL explicitly. Tools that read HTML `` tags will pick up `/llms.txt` automatically.
---
# Get started
Setting up Kenni takes three quick steps in the [developer portal](https://developers.kenni.is).
1. **Sign in** — open [developers.kenni.is](https://developers.kenni.is) and choose **Continue with Kenni** to create or open your account.
2. **Create a team** — pick a friendly name, a stable domain like `my-amazing-app.is` (it prefixes your client IDs and API scopes), and your invoice details.
3. **Create your first application** — choose a type (web, native, or machine-to-machine) and your redirect URIs. The portal generates a `client_id` and, for confidential clients, a `client_secret`.
> **Note.** New teams start on the **developer plan**: no costs, but only team members can sign in. Upgrade from team settings when you're ready to launch.
---
# Applications
An application (client) is the integration point between your software and Kenni. Each application has its own credentials, redirect URIs, branding, and feature configuration. You manage applications from the **Applications** section of the [developer portal](https://developers.kenni.is).
When you create an application, Kenni issues a `client_id` (prefixed with your team domain, e.g. `@my-app.is/web`) and — for confidential clients — a `client_secret`. These identify your application to the OIDC endpoints under `https://idp.kenni.is/`.
## Application types
Pick the type that matches how your software talks to Kenni. The type controls which grants are available, whether a `client_secret` is issued, and which fields you can configure.
| Type | Use for | Client secret | Grants |
| ---------------------- | --------------------------------------------------------- | ------------- | --------------------------------------------------------------- |
| **Web** | Server-rendered apps and APIs that can keep a secret | Yes | `authorization_code`, `refresh_token` |
| **Web (SPA)** | Single-page apps running entirely in the browser | No | `authorization_code` (PKCE), `refresh_token` |
| **Native** | iOS, Android, and desktop apps | No | `authorization_code` (PKCE), `refresh_token` |
| **Machine to Machine** | Backend-to-backend integrations with no end user | Yes | `client_credentials` |
| **Device** | Smart TVs, CLI tools, and other input-constrained devices | No | `urn:ietf:params:oauth:grant-type:device_code`, `refresh_token` |
> **Note.** The **Device** application type runs OAuth 2.0's [Device Authorization Grant](https://datatracker.ietf.org/doc/html/rfc8628) and is currently behind a plan-tier flag. [Get in touch](mailto:hello@kenni.is) and we'll enable it for your team. See [Device code flow](https://developers.kenni.is/docs/features/device-code) for the full request/response walkthrough.
## Redirect URIs
Web, SPA, and Native applications must declare every URI Kenni is allowed to redirect the user back to after authentication. Anything not on the list is rejected. Add one URI per line in the application settings.
Machine-to-Machine and Device applications don't use redirect URIs — M2M obtains tokens directly from the token endpoint, and Device flows verify the user out-of-band via the activation page.
## Client credentials
For confidential clients (Web and M2M), Kenni stores a hashed `client_secret`. The full secret is shown once when the application is created and is then masked. You can copy the masked value, but the only way to recover a lost secret is to **rotate** it from the application's Settings tab — which invalidates the old secret immediately.
Public clients (SPA, Native, Device) don't get a secret. They authenticate the user via PKCE (for code-flow clients) or the device verification step instead.
## Endpoints
Each team has its own OIDC issuer at `https://idp.kenni.is/`. The standard endpoints are derived from it:
- Discovery — `/.well-known/openid-configuration`
- Authorization — `/oidc/auth`
- Token — `/oidc/token`
- Token introspection — `/oidc/token/introspection`
- User info — `/oidc/me`
- JWKS — `/oidc/jwks`
Device applications also expose:
- Device authorization — `/oidc/device/auth`
- Device verification — `/activate`
The exact URLs for an application are available on its **Overview** tab in the portal.
---
# Settings
The **Settings** tab on an application controls everything from its identifiers and redirect URIs to token lifetimes and feature toggles. Changes take effect immediately — there's no separate publish step.
## Core fields
These fields are required and shown to every application type.
- **Name** — The display name shown to users in the login flow. Pick something they'll recognize.
- **Client ID** — The stable identifier your code uses. Auto-generated from the name on create, but you can edit it. Allowed characters: alphanumerics, underscores, and dashes. Kenni prefixes it with your team domain at runtime, e.g. `@my-app.is/web`.
- **Application type** — Web, Web (SPA), Native, Machine to Machine, or Device. See [Applications overview](https://developers.kenni.is/docs/applications) for what each one means.
- **Application URI** _(Web / SPA / Native)_ — The absolute URL of your app. If something goes wrong mid-login, Kenni offers users a button to return here.
- **Redirect URIs** _(Web / SPA / Native)_ — One URI per line. Kenni only redirects to URIs on this list. Wildcards are not allowed; list every callback explicitly.
## Client secret
Only Web and Machine-to-Machine applications get a `client_secret`. The full value is shown once when the application is created. After that, the Settings tab displays a masked value you can copy.
If you suspect the secret has leaked, use **Rotate client secret** at the bottom of the Settings tab. Rotation is immediate and irreversible — every integration using the old secret will start failing until updated.
> **Warning.** Never embed a `client_secret` in a SPA, native app, or anything that ships to end users. If you're unsure, use the SPA, Native, or Device application type instead — they authenticate without a secret.
## Token lifetimes
Hidden inside the **Token lifetimes (TTLs)** collapsible section. Values are in seconds.
- **Access token TTL** — How long an access token is valid. Default `7200` (2 hours).
- **ID token TTL** — How long an ID token is valid. Default `7200` (2 hours).
- **Refresh token TTL** — How long a refresh token is valid. Default `86400` (1 day). Not shown for M2M (no refresh tokens).
Shorter TTLs limit the blast radius of a leaked token but mean more refresh round-trips. The defaults are a reasonable starting point; tune only if you have a specific reason.
## Advanced settings
Hidden inside the **Advanced settings** collapsible section. Not available for Machine-to-Machine or Device clients.
- **Initiate login URI** — A URL on your side that can start the login flow. Used by Kenni for recoverable errors.
- **Post logout redirect URIs** — Allowed return URLs after RP-initiated logout. One per line. Particularly relevant when [single sign-on](https://developers.kenni.is/docs/features/single-sign-on) is enabled.
- **Require PKCE** _(Web only)_ — On by default. SPA and Native clients always require PKCE; this toggle exists only because confidential Web clients can disable it for legacy integrations. Leave it on unless you know you need to.
- **Enable test user access** — Lets [test users](https://developers.kenni.is/docs/features/test-users) (configured under **Settings → Test users**) authenticate to this application. Only shown if your plan supports test users.
- **Skip passkey prompt** — Hides the passkey registration prompt for this application. See [Skipping passkeys](https://developers.kenni.is/docs/features/skipping-passkeys). Only shown if your plan supports it.
## Branding, consent, scopes, delegation
These live on their own tabs alongside Settings:
- **Branding** — Logo, accent color, border radius, and light/dark appearance. See [Theming](https://developers.kenni.is/docs/applications/theming).
- **Consent** — Identity scopes the application can request and which ones the user must agree to. See [Consent](https://developers.kenni.is/docs/features/consent). Plan-gated.
- **API Scopes** — Authorize this application to request your team's API scopes.
- **Delegation** — Self-delegation toggle plus [company](https://developers.kenni.is/docs/features/company-delegations) and [custom](https://developers.kenni.is/docs/features/custom-delegations) delegation configuration. Plan-gated.
## Deleting an application
The **Delete your application** action at the bottom of the Settings tab is permanent and irreversible. Make sure no production traffic still depends on the `client_id` — once deleted, every authentication and token request against it will fail.
---
# Theming
Theming controls how the Kenni-hosted login screen looks when users authenticate to your application. You can match your brand's colors, set the corner radius, force a light or dark appearance, and upload a logo. Theming is configured per application from the **Branding** tab in the [developer portal](https://developers.kenni.is).
Machine-to-Machine clients have no user-facing surface, so they don't have a Branding tab. Every other application type — Web, SPA, Native, and Device — does.
> **Note.** Themed branding only applies to pages where Kenni knows which client is in play. For pages without a client context (the device activation entry page, error pages, and the post-logout screen) Kenni falls back to your team's global branding. Configure that under **Settings → Branding** in the portal.
## Logo
Upload separate logos for light and dark mode under **Branding → Logo**. The light-mode logo is used as the default if you don't supply a dark-mode variant.
- Square crop, sized to fit the login screen header.
- PNG or JPG.
- Use a transparent background so the logo blends with both light and dark themes.
The image is cropped in-browser before upload, so you can pick a larger source and trim it to a square in the portal.
## Theme
The **Theme** section under **Branding** maps directly onto the Radix Themes design tokens. Pick:
- **Accent color** — the primary color used for buttons, links, focus rings, and the Kenni accent. Choose something that pairs with your logo. The picker shows every available swatch.
- **Border radius** — `none`, `small`, `medium`, `large`, or `full`. Applied to inputs, buttons, and cards on the login screen.
- **Appearance** — `light`, `dark`, or `inherit`. `inherit` uses the user's system preference; `light` and `dark` force a specific mode regardless of the user's setting.
Changes save when you click **Save theme** and take effect on the next authentication.
## Tips
- Preview your theme by starting an authentication flow against the application. There's no in-portal preview yet.
- If your logo looks dim against a dark background, supply a dedicated dark-mode logo rather than relying on the light one.
- Picking an unfamiliar accent isn't free — `inherit` plus a strong logo is often a cleaner look than a custom accent that clashes with your brand.
---
# API scopes
Scopes are how OAuth 2.0 and OpenID Connect express what an access token is allowed to do. Your application asks for scopes during authentication, the user (or the consent configuration) approves them, and Kenni issues tokens that carry only those scopes.
Kenni separates scopes into two categories:
- **Identity scopes** — Built-in scopes that release information about the authenticated user (or, for delegated sessions, the actor). They map to claims on the ID token and the user-info endpoint. The full list lives on [Standard scopes](https://developers.kenni.is/docs/api-scopes/standard).
- **Custom API scopes** — Scopes you define for your team's own APIs. They protect your backend resources, not user data. They're prefixed with your team domain (e.g. `@my-app.is/orders.read`) and managed from **API scopes** in the [developer portal](https://developers.kenni.is).
## Requesting scopes
Scopes are sent as a space-separated `scope` parameter on the authorization request:
```
scope=openid profile email @my-app.is/orders.read
```
The token endpoint then issues an access token that carries only the scopes the client is allowed to request and the user has consented to. Anything you didn't ask for is silently dropped.
`openid` is mandatory for any OpenID Connect flow — without it Kenni won't issue an ID token. `offline_access` is required for a refresh token to be issued.
## Access token format
The access token Kenni issues comes in one of two shapes, depending on whether a custom API scope was requested:
- **JWT access token** — issued when the request includes at least one custom API scope. Self-contained, signed, and verifiable by your resource server using Kenni's JWKS endpoint without an extra round-trip.
- **Opaque access token** — issued when no custom API scope was requested. Not a JWT — it's a reference to a session held inside Kenni. You can still call `/oidc/me` (user-info) and `/oidc/token/introspection` with it, but it carries no claims your resource server can read directly.
If your application needs to validate access tokens at the edge of your own API, request at least one custom API scope so you get a JWT. If you only need user info, an opaque token is fine.
## Custom API scopes
Custom API scopes let you split your backend into independently authorizable surfaces. A typical pattern is one scope per resource and verb (`orders.read`, `orders.write`), but the granularity is yours to decide.
Create a scope from **API scopes** in the portal:
- **Name** — alphanumerics, underscores, and dashes. Kenni prefixes it with your team domain at runtime, so `orders.read` becomes `@my-app.is/orders.read` in the request.
- **Description** — internal note shown in the portal. Not visible to end users.
A new scope is inert until at least one application is authorized to request it. Open the application's **API Scopes** tab and toggle the scope on. From then on, that application can include the scope on its authorization or token request.
> **Note.** Scopes are case-sensitive. The name you create in the portal is the exact string your code must send.
## Machine-to-machine clients
M2M clients use the `client_credentials` grant and don't have an end user to consent to anything. The same opaque-vs-JWT rule applies: authorize at least one custom API scope so the resulting access token is a JWT your services can validate locally. An M2M client with no API scopes can still call user-info and introspection, but most M2M use cases want a verifiable token.
## Renaming and deleting scopes
Renaming a scope or deleting it is immediate and breaking. Every application requesting the old name will start failing on the next token request. Coordinate with downstream consumers before changing anything in production.
---
# Standard scopes
Kenni ships with a fixed set of identity scopes for the authenticated user, the company on whose behalf the user is acting (for delegated sessions), and the actor (the human in a delegation). Each scope releases one or more claims on the ID token and the user-info endpoint.
Scopes marked **auto-consent** are released without prompting the user. The remaining scopes require your application to have the consent feature enabled — they only show up in the **Consent** tab of an application once consent is on.
> **Note.** The exact scopes a given application can request — filtered by its plan tier and feature configuration — are listed under **Requestable identity scopes** on the application's **Overview** tab in the [developer portal](https://developers.kenni.is).
## Session
| Scope | Claims | Notes |
| ---------------- | ---------------- | -------------------------------------------------------- |
| `openid` | `sub`, `actor` | Required for any OIDC flow. Auto-consent. |
| `offline_access` | `offline_access` | Required for a refresh token to be issued. Auto-consent. |
## User identity
Released about the authenticated end user.
| Scope | Claims | Notes |
| ----------------------- | --------------------------------------- | --------------------------------------------------- |
| `display_name` | `display_name`, `name` | The user's editable display name. Requires consent. |
| `picture` | `picture` | Profile picture. Requires consent. |
| `national_id` | `national_id` | National identification number. Auto-consent. |
| `audkenni_name` | `audkenni_name`, `name` | Name as reported by Audkenni. Auto-consent. |
| `audkenni_phone_number` | `audkenni_phone_number` | Phone number as reported by Audkenni. Auto-consent. |
| `phone_number` | `phone_number`, `phone_number_verified` | Editable phone number. Requires consent. |
| `email` | `email`, `email_verified` | Email address. Requires consent. |
## Company
Released for delegated sessions where the user is acting on behalf of a company. Requires the company delegation feature.
| Scope | Claims | Notes |
| ---------------------- | ------------------------------ | --------------------------------------------------- |
| `company_display_name` | `company_display_name`, `name` | Company's editable display name. Requires consent. |
| `company_name` | `company_name`, `name` | Legal name from the company registry. Auto-consent. |
| `company_email` | `company_email` | Company email. Requires consent. |
| `company_phone_number` | `company_phone_number` | Company phone number. Requires consent. |
| `company_logo` | `company_logo` | Company logo. Requires consent. |
## Actor
In a delegated session the actor is the human acting on behalf of the subject. Released under the `actor.*` namespace. Requires the delegation feature.
| Scope | Claims | Notes |
| ----------------------------- | ----------------------------------- | ------------------------------------------------ |
| `actor_display_name` | `actor.display_name`, `actor.name` | Actor's editable display name. Requires consent. |
| `actor_audkenni_name` | `actor.audkenni_name`, `actor.name` | Actor's name from Audkenni. Auto-consent. |
| `actor_audkenni_phone_number` | `actor.audkenni_phone_number` | Actor's phone from Audkenni. Auto-consent. |
| `actor_picture` | `actor.picture` | Actor's profile picture. Requires consent. |
| `actor_national_id` | `actor.national_id` | Actor's national ID. Auto-consent. |
| `actor_phone_number` | `actor.phone_number` | Actor's editable phone number. Requires consent. |
| `actor_email` | `actor.email` | Actor's email. Requires consent. |
| `delegation_type` | `delegation_type` | The type(s) of delegation in use. Auto-consent. |
## Deprecated
These scopes are kept for backwards compatibility. Use the replacement instead.
| Scope | Replacement | Claims |
| --------------- | -------------------- | ------------ |
| `profile` | `display_name` | `name` |
| `actor_profile` | `actor_display_name` | `actor.name` |
---
# No framework (curl)
> **Note.** Use this guide to learn the protocol, debug other integrations, or build for a language or runtime not covered elsewhere. For production apps, prefer one of the framework guides — they handle the dance below for you.
This guide walks through a full Authorization Code + PKCE flow against Kenni using nothing but `curl` and a browser.
You'll need a Web or SPA application registered in the [developer portal](https://developers.kenni.is) with one redirect URI on the list (we'll use `http://localhost:8080/callback` below).
Replace `` with your team's domain throughout. Your `client_id` is shown on the application's Overview tab — it looks like `@my-app.is/web`.
## Prerequisites
The snippets below assume `bash`, `curl`, [`jq`](https://jqlang.org/), `openssl`, and `xxd`. On macOS, `jq` is not installed by default — `brew install jq`. `openssl` and `xxd` ship with the OS. The JWT-verification recipe at the end uses `openssl` exclusively (no `jq` substitutes for the cryptography).
## Discovery
Every Kenni team exposes an OIDC discovery document. It's the only URL your code needs to hard-code; everything else is derived from it.
```bash
curl -s https://idp.kenni.is//.well-known/openid-configuration | jq . > discovery.json
```
The response lists `authorization_endpoint`, `token_endpoint`, `userinfo_endpoint`, `jwks_uri`, `end_session_endpoint`, supported scopes, and supported response/grant types. Cache it for the rest of the session — re-fetch only when the JWKS rotates.
```bash
AUTH_ENDPOINT=$(jq -r .authorization_endpoint discovery.json)
TOKEN_ENDPOINT=$(jq -r .token_endpoint discovery.json)
USERINFO_ENDPOINT=$(jq -r .userinfo_endpoint discovery.json)
JWKS_URI=$(jq -r .jwks_uri discovery.json)
END_SESSION_ENDPOINT=$(jq -r .end_session_endpoint discovery.json)
```
## Generate PKCE values
PKCE binds the authorization request to the token exchange so an intercepted code is useless on its own. Generate a verifier (random) and a challenge (its SHA-256, base64url-encoded):
```bash
CODE_VERIFIER=$(openssl rand -base64 32 | tr -d '=\n' | tr '/+' '_-')
CODE_CHALLENGE=$(printf '%s' "$CODE_VERIFIER" | openssl dgst -sha256 -binary | openssl base64 -A | tr -d '=' | tr '/+' '_-')
```
The verifier is a 43-character base64url string drawn from the full RFC 7636 alphabet (`[A-Z][a-z][0-9]-._~`). Don't try to "simplify" the alphabet by stripping `-_` — every character of entropy counts.
`state` and `nonce` are also worth setting — both are echoed back on the callback and used to detect tampering and replay:
```bash
STATE=$(openssl rand -hex 16)
NONCE=$(openssl rand -hex 16)
```
## Build the authorization URL
Open this URL in a browser. Don't `curl` it — the response is a redirect into the Kenni login UI, which the user has to interact with.
```bash
URL="$AUTH_ENDPOINT?client_id=@/web"
URL+="&response_type=code"
URL+="&redirect_uri=http%3A%2F%2Flocalhost%3A8080%2Fcallback"
URL+="&scope=openid+profile+national_id+offline_access"
URL+="&state=$STATE"
URL+="&nonce=$NONCE"
URL+="&code_challenge=$CODE_CHALLENGE"
URL+="&code_challenge_method=S256"
# macOS: open "$URL" Linux: xdg-open "$URL" Windows: start "$URL"
echo "$URL"
```
`offline_access` is what gets you a refresh token — drop it if you don't need refresh.
## Receive the redirect
The browser redirects to `http://localhost:8080/callback?code=...&state=...` (or `?error=...&error_description=...` if the user declined). You need _something_ listening on that port to display or capture the URL. The simplest portable approach is a tiny static server:
```bash
mkdir -p callback
cat > callback/index.html <<'HTML'
Kenni callback
HTML
python3 -m http.server 8080
```
Open the auth URL, sign in, and copy the query string from the page that loads.
> **Note.** If nothing is listening on 8080 the browser shows "connection refused" — the URL still appears in the address bar, so copying from there works as a fallback.
Pull the values out of the redirect URL:
```bash
URL='http://localhost:8080/callback?code=...&state=...' # paste the URL
QUERY="${URL#*\?}"
get_param() {
printf '%s' "$QUERY" | tr '&' '\n' | awk -F= -v k="$1" '$1==k{print substr($0, length(k)+2); exit}'
}
urldecode() {
local s="${1//+/ }"
printf '%b' "${s//%/\\x}"
}
CODE=$(urldecode "$(get_param code)")
RETURNED_STATE=$(urldecode "$(get_param state)")
ERR=$(urldecode "$(get_param error)")
ERR_DESC=$(urldecode "$(get_param error_description)")
[[ -z "$ERR" ]] || { echo "auth failed: $ERR — $ERR_DESC" >&2; exit 1; }
[[ "$RETURNED_STATE" == "$STATE" ]] || { echo "state mismatch" >&2; exit 1; }
```
The `state` check is the CSRF defence; the `error` check covers the consent-decline path.
## Exchange the code for tokens
Confidential (Web) clients authenticate the token request with their `client_secret`. Public clients (SPA, Native) omit it — PKCE is the proof.
```bash
RESPONSE=$(curl -s -X POST "$TOKEN_ENDPOINT" \
-H "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "grant_type=authorization_code" \
--data-urlencode "code=$CODE" \
--data-urlencode "redirect_uri=http://localhost:8080/callback" \
--data-urlencode "client_id=@/web" \
--data-urlencode "client_secret=" \
--data-urlencode "code_verifier=$CODE_VERIFIER")
ACCESS_TOKEN=$(printf '%s' "$RESPONSE" | jq -r .access_token)
ID_TOKEN=$(printf '%s' "$RESPONSE" | jq -r .id_token)
REFRESH_TOKEN=$(printf '%s' "$RESPONSE" | jq -r .refresh_token)
```
`--data-urlencode` correctly escapes client IDs that contain `@` or `/`. `jq -r` strips the surrounding quotes; `printf '%s'` strips `jq`'s trailing newline so the values can be reused without contaminating the next request.
> **Warning.** **Do not trust the `id_token` payload before verifying its signature.** A naive `cut -d. -f2 | base64 -d | jq .` decode of an `id_token` tells you what someone claimed — you don't know it was Kenni. See [Verifying a JWT in shell](#verifying-a-jwt-in-shell) below — apply the same recipe to `$ID_TOKEN`, then check that `nonce` in the payload equals the `$NONCE` you sent.
## Call the user-info endpoint
The access token works against `/oidc/me`. The response contains the same identity claims released by the scopes the user consented to.
```bash
curl -s "$USERINFO_ENDPOINT" -H "Authorization: Bearer $ACCESS_TOKEN" | jq .
```
If you also requested a custom API scope, the access token is itself a JWT carrying many of the same claims — reading it directly skips a network round-trip when you only need to confirm identity. **Verify the signature first** (next section). If you didn't request a custom API scope, the access token is an opaque reference token — see [API scopes](https://developers.kenni.is/docs/api-scopes) for the difference.
## Verifying a JWT in shell
The whole point of a "no framework" guide is to make the protocol concrete, and Kenni's tokens are signed JWTs. The recipe below verifies an RS256 JWT (id_token or access token) using only `openssl` and `jq`.
```bash
verify_jwt_rs256() {
local TOKEN="$1" JWKS="$2"
local HEADER_B64="${TOKEN%%.*}"
local REST="${TOKEN#*.}"
local PAYLOAD_B64="${REST%%.*}"
local SIG_B64="${REST#*.}"
local SIGNED_INPUT="$HEADER_B64.$PAYLOAD_B64"
# base64url -> base64 with padding, then decode
b64url_decode() {
local s="$1" pad
s="${s//-/+}"; s="${s//_/\/}"
pad=$(( (4 - ${#s} % 4) % 4 ))
printf '%s%*s' "$s" "$pad" '' | tr ' ' '=' | openssl base64 -d -A
}
# 1. Read kid + alg from the JOSE header
local HEADER ALG KID
HEADER=$(b64url_decode "$HEADER_B64")
ALG=$(printf '%s' "$HEADER" | jq -r .alg)
KID=$(printf '%s' "$HEADER" | jq -r .kid)
[[ "$ALG" == "RS256" ]] || { echo "alg=$ALG, expected RS256" >&2; return 1; }
# 2. Find the matching JWK by kid, pull its n and e
local JWK N_B64URL E_B64URL
JWK=$(printf '%s' "$JWKS" | jq -c --arg kid "$KID" '.keys[] | select(.kid==$kid)')
[[ -n "$JWK" ]] || { echo "no JWK for kid=$KID" >&2; return 1; }
N_B64URL=$(printf '%s' "$JWK" | jq -r .n)
E_B64URL=$(printf '%s' "$JWK" | jq -r .e)
# 3. Convert n,e -> PEM. ASN.1 INTEGER is signed; if the RSA modulus's
# high bit is set (which it is for any real RSA key), prepend 00.
local TMP; TMP=$(mktemp -d)
b64url_decode "$N_B64URL" > "$TMP/n.bin"
b64url_decode "$E_B64URL" > "$TMP/e.bin"
prepend_zero_if_signed() {
local f="$1" first
first=$(xxd -p -l 1 "$f")
if [[ "$((16#$first))" -ge 128 ]]; then
{ printf '\x00'; cat "$f"; } > "$f.tmp" && mv "$f.tmp" "$f"
fi
}
prepend_zero_if_signed "$TMP/n.bin"
prepend_zero_if_signed "$TMP/e.bin"
# Build an ASN.1 RSAPublicKey SEQUENCE { n INTEGER, e INTEGER } via openssl asn1parse -genconf
local N_HEX E_HEX
N_HEX=$(xxd -p -c 9999 "$TMP/n.bin")
E_HEX=$(xxd -p -c 9999 "$TMP/e.bin")
cat > "$TMP/asn1.cnf" </dev/null
# 4. Verify signature
b64url_decode "$SIG_B64" > "$TMP/sig.bin"
if ! printf '%s' "$SIGNED_INPUT" \
| openssl dgst -sha256 -verify "$TMP/pub.pem" -signature "$TMP/sig.bin" >/dev/null 2>&1; then
echo "signature INVALID" >&2
rm -rf "$TMP"
return 1
fi
# 5. Emit the (now-trusted) payload for further claim checks
b64url_decode "$PAYLOAD_B64"
rm -rf "$TMP"
}
```
Use it:
```bash
JWKS=$(curl -s "$JWKS_URI")
PAYLOAD=$(verify_jwt_rs256 "$ID_TOKEN" "$JWKS") || exit 1
# Claim checks
NOW=$(date +%s)
EXP=$(printf '%s' "$PAYLOAD" | jq -r .exp)
ISS=$(printf '%s' "$PAYLOAD" | jq -r .iss)
AUD=$(printf '%s' "$PAYLOAD" | jq -r .aud)
TOK_NONCE=$(printf '%s' "$PAYLOAD" | jq -r .nonce)
[[ "$NOW" -lt "$EXP" ]] || { echo "token expired" >&2; exit 1; }
[[ "$ISS" == "https://idp.kenni.is/" ]] || { echo "wrong issuer: $ISS" >&2; exit 1; }
[[ "$AUD" == "@/web" ]] || { echo "wrong audience: $AUD" >&2; exit 1; }
[[ "$TOK_NONCE" == "$NONCE" ]] || { echo "nonce mismatch" >&2; exit 1; } # id_token only
printf '%s' "$PAYLOAD" | jq .
```
The same function verifies API access tokens (omit the `nonce` check, validate the API scope claim instead).
> **Note.** The leading `\x00` byte on the modulus is an ASN.1 quirk — `INTEGER` is signed two's-complement, so any value with the high bit set must be sign-extended to stay positive. Forget this and `openssl rsa` rejects the DER as "non-positive integer."
## Refresh
When the access token expires, swap the refresh token for a fresh pair:
```bash
curl -s -X POST "$TOKEN_ENDPOINT" \
-H "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "grant_type=refresh_token" \
--data-urlencode "refresh_token=$REFRESH_TOKEN" \
--data-urlencode "client_id=@/web" \
--data-urlencode "client_secret=" | jq .
```
## Client credentials (M2M)
For server-to-server calls there's no user, no PKCE, no browser — just a confidential client exchanging its credentials directly for an access token. Use the **Machine** application type in the developer portal.
```bash
# RFC 6749 §2.3.1 says client_id and client_secret in a Basic header must each be
# form-urlencoded *before* the Base64. Kenni client IDs contain '@' and '/', so the
# naive `client_id:secret` Basic header technically violates the spec.
ID_ENC=$(jq -rn --arg v "$CLIENT_ID" '$v|@uri')
SECRET_ENC=$(jq -rn --arg v "$CLIENT_SECRET" '$v|@uri')
BASIC=$(printf '%s:%s' "$ID_ENC" "$SECRET_ENC" | openssl base64 -A)
curl -s -X POST "$TOKEN_ENDPOINT" \
-H "Authorization: Basic $BASIC" \
-H "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "grant_type=client_credentials" \
--data-urlencode "scope=$M2M_SCOPE" | jq .
```
The response contains an `access_token` (a JWT, with the M2M scope as `scope`) and `expires_in`. No `refresh_token` and no `id_token` — there's no user to identify. Verify the JWT exactly the same way as the user-flow access token.
## Sign out
Clearing your local session is not enough. The user is still signed in to Kenni — the next time they hit your "Sign in" button, Kenni recognizes the existing session and logs them straight back in with no visible interaction. Users perceive this as "logout doesn't work."
The fix is **RP-initiated logout**: redirect the browser to Kenni's `end_session_endpoint` so Kenni clears its own session, then comes back to your app:
```bash
LOGOUT_URL="$END_SESSION_ENDPOINT?client_id=@/web"
LOGOUT_URL+="&id_token_hint=$ID_TOKEN"
LOGOUT_URL+="&post_logout_redirect_uri=http%3A%2F%2Flocalhost%3A8080%2Floggedout"
# macOS: open "$LOGOUT_URL"
echo "$LOGOUT_URL"
```
`id_token_hint` is the ID token you received at sign-in. `post_logout_redirect_uri` must be on the application's **Post logout redirect URIs** list in the [developer portal](https://developers.kenni.is) — register a separate path from the sign-in redirect URI so your app can tell sign-in completion apart from sign-out completion.
**When to clear the local session**: either right before redirecting to `end_session_endpoint`, or in your `post_logout_redirect_uri` handler. Both work; pick one and be consistent. Most apps clear it before the redirect so users see a logged-out UI even if the round-trip fails.
That's the full loop. Every framework guide that follows is essentially a way to delegate the work above to a library.
---
# Next.js / better-auth
[better-auth](https://www.better-auth.com) is the modern auth framework for the Next.js (and broader TypeScript) ecosystem. Its `genericOAuth` plugin lets you register Kenni as an OIDC provider with discovery, PKCE, and token storage handled for you.
This guide is tested against Next.js 16 and `better-auth` 1.x.
## Install
```bash
npm install better-auth jose
```
`better-auth` runs database-less by default — session and account state live in signed cookies. If you need persistence (e.g. to invalidate sessions across deploys), pass a `database:` option. For most "let users sign in with Kenni" integrations, you don't need one.
## Auth instance
Create the auth instance once and import it into your routes and middleware.
> **Warning.** Two non-obvious tweaks are required to get sign-in working against Kenni: a custom `getUserInfo` (so the `name` claim isn't dropped) and a `mapProfileToUser` (so better-auth's required-`email`/`name` checks pass). Both are explained below.
```ts
// lib/auth.ts
import { betterAuth } from 'better-auth';
import { genericOAuth } from 'better-auth/plugins';
import { nextCookies } from 'better-auth/next-js';
import { decodeJwt } from 'jose';
const issuer = `https://idp.kenni.is/`;
export const auth = betterAuth({
plugins: [
genericOAuth({
config: [
{
providerId: 'kenni',
discoveryUrl: `${issuer}/.well-known/openid-configuration`,
clientId: process.env.KENNI_CLIENT_ID!,
clientSecret: process.env.KENNI_CLIENT_SECRET!,
// `offline_access` requests a refresh token so better-auth can
// refresh the access token without bouncing the user back to Kenni.
scopes: ['openid', 'profile', 'national_id', 'offline_access'],
pkce: true,
// Better-auth's default user-info parser only trusts id_token claims
// when both `sub` AND `email` are present, then falls through to the
// userinfo endpoint. Kenni puts `name` in the id_token but doesn't
// include `email` (it's consent-gated), so the gate fails and the
// userinfo response — which doesn't carry `name` for most clients —
// wins. The result is a silently-empty `user.name`. Decoding the
// id_token directly fixes it.
getUserInfo: async (tokens) => {
if (!tokens.idToken) return null;
const claims = decodeJwt(tokens.idToken) as Record;
return {
...claims,
id: String(claims.sub ?? ''),
email: claims.email as string | undefined,
emailVerified: Boolean(claims.email_verified),
name: claims.name as string | undefined,
image: claims.picture as string | undefined,
};
},
// Better-auth requires `email` and `name` on every user. Kenni
// guarantees neither: `email` is consent-gated, and `name` may be
// empty for some test accounts and delegation flows. Without this
// map, sign-in throws `email_is_missing` / `name_is_missing`.
mapProfileToUser: (profile) => ({
email: profile.email ?? `${profile.sub}@no-reply.users.kenni.is`,
emailVerified: Boolean(profile.email_verified),
name:
profile.name ||
[profile.given_name, profile.family_name].filter(Boolean).join(' ') ||
'Kenni user',
}),
},
],
}),
// `nextCookies` must be the last plugin. Without it, sign-in via a server
// action silently fails to set the session cookie.
nextCookies(),
],
});
```
## Mount the handler
```ts
// app/api/auth/[...all]/route.ts
import { auth } from '@/lib/auth';
import { toNextJsHandler } from 'better-auth/next-js';
export const { GET, POST } = toNextJsHandler(auth);
```
## Auth client
`authClient.signIn.oauth2(...)` is only available when you register the `genericOAuthClient()` plugin on the client.
```ts
// lib/auth-client.ts
import { createAuthClient } from 'better-auth/react';
import { genericOAuthClient } from 'better-auth/client/plugins';
export const authClient = createAuthClient({
plugins: [genericOAuthClient()],
});
```
## Environment
```
KENNI_CLIENT_ID=@/web
KENNI_CLIENT_SECRET=
NEXT_PUBLIC_KENNI_CLIENT_ID=@/web
BETTER_AUTH_SECRET=
BETTER_AUTH_URL=http://localhost:3000
```
`BETTER_AUTH_URL` is the public origin better-auth derives the `redirect_uri` from. If it's wrong (e.g. `localhost:3000` set but the app is actually running on `localhost:3001`), sign-in fails with a `redirect_uri mismatch` and the cause is not obvious.
`NEXT_PUBLIC_KENNI_CLIENT_ID` is the same value, exposed to the browser for the sign-out snippet below. Next.js only inlines vars prefixed with `NEXT_PUBLIC_` into client bundles.
Register `http://localhost:3000/api/auth/oauth2/callback/kenni` as a redirect URI on your application in the [developer portal](https://developers.kenni.is). The path comes from the `genericOAuth` plugin mounting `/oauth2/callback/:providerId` under the `/api/auth/[...all]` handler. Adjust the host for production.
## Triggering sign-in
```tsx
'use client';
import { authClient } from '@/lib/auth-client';
export const SignInButton = () => (
);
```
`callbackURL` controls where the user lands after sign-in completes. Skip it and better-auth picks its own default, which is rarely what you want.
## Public clients
For SPA or Native applications, drop `clientSecret` and set `pkce: true` (it already is in the snippet above). PKCE is recommended for confidential clients too as defence in depth; for public clients PKCE alone replaces the missing `client_secret`.
## Reading the access and id tokens
Better-auth keeps the Kenni-issued tokens server-side. Retrieve them with `auth.api.getAccessToken`, which auto-refreshes the access token if it has expired:
```ts
// app/lib/kenni-tokens.ts
import { headers } from 'next/headers';
import { auth } from '@/lib/auth';
export async function getKenniTokens() {
const session = await auth.api.getSession({ headers: await headers() });
if (!session) return null;
return auth.api.getAccessToken({
body: { providerId: 'kenni', userId: session.user.id },
});
// -> { accessToken, accessTokenExpiresAt, scopes, idToken }
}
```
Use `accessToken` for outbound API calls and `idToken` for RP-initiated logout (below). See [API scopes](https://developers.kenni.is/docs/api-scopes) for what kind of access token Kenni issues based on your scope configuration.
## Sign out
`authClient.signOut()` clears the better-auth session but leaves the Kenni session untouched — users get silently re-authenticated on the next sign-in. After signing out locally, redirect the browser to Kenni's `end_session_endpoint` (RP-initiated logout) so Kenni also clears its session.
Clearing the local session _before_ the redirect means a failed RP-initiated logout still leaves the user signed out locally. Most apps prefer that over the alternative.
```tsx
'use client';
import { authClient } from '@/lib/auth-client';
const handleSignOut = async (idToken: string) => {
// Discover the end-session endpoint instead of hard-coding it.
const issuer = `https://idp.kenni.is/`;
const discovery = await fetch(`${issuer}/.well-known/openid-configuration`).then((r) => r.json());
await authClient.signOut();
const url = new URL(discovery.end_session_endpoint);
url.searchParams.set('id_token_hint', idToken);
url.searchParams.set('post_logout_redirect_uri', `${window.location.origin}/`);
url.searchParams.set('client_id', process.env.NEXT_PUBLIC_KENNI_CLIENT_ID!);
window.location.href = url.toString();
};
```
Pass `idToken` in from a server component that called `getKenniTokens()` above. Register your post-logout URL on the application's **Post logout redirect URIs** list in the developer portal. See the [No framework (curl) guide](https://developers.kenni.is/docs/guides/curl#sign-out) for the full reasoning.
## Per-call `prompt` (delegation, switch user)
`authClient.signIn.oauth2` doesn't accept a `prompt` parameter — better-auth reads it from static provider config only. To vary `prompt` per-click (e.g. a "Switch delegation" button), pass `authorizationUrlParams` as a function that reads from `additionalData`:
```ts
genericOAuth({
config: [
{
// ... discoveryUrl, clientId, etc.
authorizationUrlParams: (ctx) => {
const prompt = (ctx.body as { additionalData?: { prompt?: string } } | undefined)?.additionalData
?.prompt;
return prompt ? { prompt } : ({} as Record);
},
},
],
});
```
Then on the client:
```ts
authClient.signIn.oauth2({
providerId: 'kenni',
additionalData: { prompt: 'delegation' },
});
```
One provider, one redirect URI, no account-linking errors.
## Client credentials (M2M)
Better-auth doesn't help with the client-credentials grant — it's not user-bound. POST to the token endpoint directly:
```ts
const res = await fetch(`${issuer}/oidc/token`, {
method: 'POST',
headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
body: new URLSearchParams({
grant_type: 'client_credentials',
client_id: process.env.KENNI_CLIENT_ID!,
client_secret: process.env.KENNI_CLIENT_SECRET!,
scope: 'your_api:read',
}),
});
const { access_token } = await res.json();
```
You'll need a separate **Machine** application registered in the developer portal, with the relevant API scopes authorized. See the [No framework (curl) guide](https://developers.kenni.is/docs/guides/curl) for the full protocol view.
## Verifying access tokens
If your API runs as a separate service, validate Kenni-issued JWT access tokens locally against the JWKS from discovery — don't introspect on every request. See [API scopes](https://developers.kenni.is/docs/api-scopes) for when access tokens are JWTs vs. opaque references.
---
# React (SPA)
For a single-page React app, [`react-oidc-context`](https://github.com/authts/react-oidc-context) wraps the well-tested `oidc-client-ts` library and exposes a hook-based API. PKCE, silent refresh (with caveats — see below), and session storage are handled for you.
Use the **Web (SPA)** application type in the [developer portal](https://developers.kenni.is) — public client, no secret.
## Install
```bash
npm install react-oidc-context oidc-client-ts
```
## Provider
Wrap your app once at the root.
```tsx
// main.tsx
import { AuthProvider } from 'react-oidc-context';
import { WebStorageStateStore } from 'oidc-client-ts';
const oidcConfig = {
authority: import.meta.env.VITE_KENNI_AUTHORITY, // https://idp.kenni.is/
client_id: import.meta.env.VITE_KENNI_CLIENT_ID, // @/spa
redirect_uri: `${window.location.origin}/callback`,
post_logout_redirect_uri: window.location.origin,
response_type: 'code',
scope: 'openid profile national_id offline_access',
// Default is sessionStorage (clears on tab close). localStorage survives
// tab close and devtools refresh — pick whichever fits your app's session
// semantics. Both are fine for public clients.
userStore: new WebStorageStateStore({ store: window.localStorage }),
onSigninCallback: () => {
window.history.replaceState({}, document.title, window.location.pathname);
},
};
createRoot(document.getElementById('root')!).render(
);
```
This is a public client, so no `client_secret` — PKCE is the proof of possession, and `oidc-client-ts` enables it by default.
Vite only exposes env vars prefixed with `VITE_` to the client bundle. If you'd rather use unprefixed names, set `envPrefix: 'KENNI_'` in `vite.config.ts`. See [Vite's env-and-mode docs](https://vitejs.dev/guide/env-and-mode).
Register `http://localhost:5173/callback` (or whatever your dev origin is) as a redirect URI on your application. The library handles the code exchange when the user lands on `/callback`.
> **Warning.** **Pin your dev port.** Vite falls back to `5174`, `5175`, … if `5173` is busy, which silently shifts the runtime `redirect_uri` and produces a "redirect_uri mismatch" with no obvious cause. Either set `strictPort: true` in `vite.config.ts` (and register the one port), or read `redirect_uri` from an env var so the registered URI and runtime URI can't drift.
If you're using a router (React Router, TanStack Router, etc.), you don't need a `/callback` route component — the provider's `onSigninCallback` rewrites the URL via `history.replaceState` before any route renders. If your router is strict about unknown paths, add a placeholder route at `/callback` so it doesn't 404 during the brief code-exchange window.
## Using auth state
```tsx
import { useAuth } from 'react-oidc-context';
export const App = () => {
const auth = useAuth();
if (auth.isLoading) return
Loading…
;
if (auth.error) return
Error: {auth.error.message}
;
if (!auth.isAuthenticated) {
return ;
}
return (
<>
Hello, {auth.user?.profile.name}
);
};
```
`auth.user?.access_token` is the access token you'd send to your APIs.
> **Warning.** **Silent refresh requires explicit setup.** `oidc-client-ts` only renews the access token when one of these is configured:
>
> - `offline_access` is in `scope` AND Kenni issued a refresh token (the default config above does this — the refresh token sits in `localStorage`), or
> - `silent_redirect_uri` is set AND `automaticSilentRenew: true` enables the iframe-based silent-renew flow.
>
> If you drop `offline_access` (e.g. because storing a refresh token in `localStorage` is a trade-off you don't want) without configuring the iframe flow, the access token will expire mid-session and your API calls will start failing. Pick one of the two paths.
## Calling your API
```ts
const res = await fetch('https://api.example.com/orders', {
headers: { Authorization: `Bearer ${auth.user?.access_token}` },
});
```
If you authorized at least one custom API scope on this application, the access token is a JWT your API can validate locally. Otherwise it's an opaque token only Kenni can introspect — see [API scopes](https://developers.kenni.is/docs/api-scopes).
## Sign out
`auth.signoutRedirect()` redirects to Kenni's `end_session_endpoint` with `id_token_hint` and `post_logout_redirect_uri`, lets Kenni clear its session, and comes back to your `post_logout_redirect_uri`. The local user state is cleared automatically.
> **Warning.** **Pass `client_id` explicitly.** `oidc-client-ts` does not include `client_id` in the end-session URL by default, but Kenni's end-session endpoint requires it. Without it the user sees an error instead of the post-logout redirect.
```ts
auth.signoutRedirect({
extraQueryParams: { client_id: oidcConfig.client_id },
});
```
If you only call `auth.removeUser()` you'll clear the local session but the Kenni session stays live, and the next sign-in will silently re-authenticate. Always prefer `signoutRedirect()`. See the [No framework (curl) guide](https://developers.kenni.is/docs/guides/curl#sign-out) for the full reasoning.
Register your post-logout URL on the application's **Post logout redirect URIs** list in the [developer portal](https://developers.kenni.is). For `react-oidc-context` it defaults to `post_logout_redirect_uri` from your config (we set it to `window.location.origin` in the provider above).
## Verifying access tokens
If your API runs as a separate service, validate Kenni-issued JWT access tokens locally against the JWKS from discovery rather than introspecting on every request. See [API scopes](https://developers.kenni.is/docs/api-scopes) for the difference between JWT and opaque access tokens, and the [No framework (curl) guide](https://developers.kenni.is/docs/guides/curl) for the protocol view.
---
# Expo (React Native)
[`expo-auth-session`](https://docs.expo.dev/versions/latest/sdk/auth-session/) is the standard OAuth/OIDC client for Expo apps. It handles PKCE, deep-link redirects, and the in-app browser session.
Use the **Native** application type in the [developer portal](https://developers.kenni.is) — public client, no secret. Mobile apps cannot keep secrets safely.
> **Warning.** **This requires a development build (`expo run:ios` / `expo run:android`).** The AuthSession proxy was removed in SDK 48; Expo Go cannot route custom-scheme redirects back into your app, so the sign-in flow dead-ends in the browser. Don't waste an afternoon trying to make Expo Go work.
## Install
```bash
npx expo install expo-auth-session expo-crypto expo-web-browser expo-secure-store expo-constants
```
## Configuration
Drive everything from environment variables so the developer portal registration and the runtime values can't drift. Expo CLI auto-loads `.env` since SDK 49.
```bash
# .env
KENNI_ISSUER=https://idp.kenni.is/
KENNI_CLIENT_ID=@/native
KENNI_REDIRECT_URI=is.kenni.example://redirect
KENNI_POST_LOGOUT_REDIRECT_URI=is.kenni.example://post-logout
```
Use a reverse-DNS scheme (`is.kenni.example`) — `myapp` collides with every other tutorial app on the device. Register **both** `KENNI_REDIRECT_URI` (Redirect URIs) and `KENNI_POST_LOGOUT_REDIRECT_URI` (Post logout redirect URIs) in the developer portal — they're separate lists with separate lifecycles.
Expo's static `app.json` can't read env vars, so use a dynamic `app.config.ts`. Parse the URL scheme out of the redirect URI so there's a single source of truth — drift between `expo.scheme` and the redirect URI causes silent sign-in failures.
```ts
// app.config.ts
import type { ExpoConfig } from 'expo/config';
const required = (key: string): string => {
const value = process.env[key];
if (!value) throw new Error(`Missing env var: ${key}`);
return value;
};
const redirectUri = required('KENNI_REDIRECT_URI');
const scheme = new URL(redirectUri).protocol.replace(':', '');
const config: ExpoConfig = {
name: 'kenni-expo-example',
slug: 'kenni-expo-example',
scheme,
ios: { bundleIdentifier: 'is.kenni.example' },
android: { package: 'is.kenni.example' },
extra: {
issuer: required('KENNI_ISSUER'),
clientId: required('KENNI_CLIENT_ID'),
redirectUri,
postLogoutRedirectUri: required('KENNI_POST_LOGOUT_REDIRECT_URI'),
},
};
export default config;
```
Read the values at runtime through `expo-constants`:
```ts
// src/config.ts
import Constants from 'expo-constants';
const extra = Constants.expoConfig?.extra ?? {};
export const config = {
issuer: extra.issuer as string,
clientId: extra.clientId as string,
redirectUri: extra.redirectUri as string,
postLogoutRedirectUri: extra.postLogoutRedirectUri as string,
};
```
## Sign-in flow
Run the code exchange from the resolved value of `promptAsync()`, **not** from a render-time conditional. A render-time `if (response?.type === 'success') { exchangeCodeAsync(...) }` re-fires on every subsequent render and the second exchange returns `invalid_grant`.
```tsx
import { useEffect, useState } from 'react';
import { Button, Text, View } from 'react-native';
import * as AuthSession from 'expo-auth-session';
import * as WebBrowser from 'expo-web-browser';
import * as SecureStore from 'expo-secure-store';
import { config } from './config';
WebBrowser.maybeCompleteAuthSession();
const TOKENS_KEY = 'kenni.tokens.v1';
type Tokens = {
accessToken: string;
idToken: string;
refreshToken?: string;
expiresAt?: number;
};
const decodeIdToken = (idToken: string): Record => {
const [, payload] = idToken.split('.');
const padded = payload + '='.repeat((4 - (payload.length % 4)) % 4);
const base64 = padded.replace(/-/g, '+').replace(/_/g, '/');
return JSON.parse(globalThis.atob(base64));
};
export const SignIn = () => {
const discovery = AuthSession.useAutoDiscovery(config.issuer);
const [tokens, setTokens] = useState(null);
const [ready, setReady] = useState(false);
// Round-trip stored tokens on launch so a relaunch doesn't bounce the user
// back through Kenni when their session is still valid.
useEffect(() => {
SecureStore.getItemAsync(TOKENS_KEY)
.then((value) => value && setTokens(JSON.parse(value)))
.finally(() => setReady(true));
}, []);
const [request, , promptAsync] = AuthSession.useAuthRequest(
{
clientId: config.clientId,
redirectUri: config.redirectUri,
scopes: ['openid', 'profile', 'national_id', 'offline_access'],
usePKCE: true,
},
discovery
);
const signIn = async () => {
if (!discovery || !request) return;
const result = await promptAsync();
if (result.type !== 'success') return;
if (!request.codeVerifier) {
throw new Error('PKCE code_verifier missing — usePKCE must be true');
}
const exchange = await AuthSession.exchangeCodeAsync(
{
clientId: config.clientId,
code: result.params.code,
redirectUri: config.redirectUri,
extraParams: { code_verifier: request.codeVerifier },
},
discovery
);
const next: Tokens = {
accessToken: exchange.accessToken,
idToken: exchange.idToken!,
refreshToken: exchange.refreshToken,
expiresAt: exchange.expiresIn ? Date.now() + exchange.expiresIn * 1000 : undefined,
};
await SecureStore.setItemAsync(TOKENS_KEY, JSON.stringify(next));
setTokens(next);
};
if (!ready) return null;
const profile = tokens ? decodeIdToken(tokens.idToken) : null;
return (
{profile ? (
Welcome {String(profile.name ?? profile.sub)}
) : (
)}
);
};
```
`maybeCompleteAuthSession()` must run at module scope — it lets `expo-auth-session` resolve when the OS bounces the user back into the app. Inside a component it gets called too late.
`useAutoDiscovery` reads `/.well-known/openid-configuration` once and caches the endpoints. `usePKCE: true` is the default for public clients but it's worth being explicit, and the runtime check on `request.codeVerifier` keeps the type-narrowing honest.
## Refresh
```ts
const refreshed = await AuthSession.refreshAsync(
{
clientId: config.clientId,
refreshToken,
},
discovery
);
```
Persist `refreshed.accessToken` and `refreshed.refreshToken` back into `SecureStore`.
## Sign out
> **Warning.** **RP-initiated logout has rough UX on iOS that Apple doesn't let you fix.** `WebBrowser.openAuthSessionAsync` opens an `ASWebAuthenticationSession` which shows a hardcoded _"<App> wants to use 'kenni.is' to sign in"_ consent prompt — even on a sign-out flow. The wording is not configurable. Opening Safari directly (`Linking.openURL`) trades it for the OS-level _"Open this page in '<App>'?"_ confirmation when Kenni redirects back to the custom scheme. The only clean fix is [Universal Links](https://developer.apple.com/documentation/xcode/supporting-associated-domains): a real HTTPS domain you control + an `apple-app-site-association` file + the `applinks:` entitlement.
>
> **What real iOS apps ship**: skip RP-initiated logout entirely on iOS. Clear local tokens and force `prompt=login` on the next sign-in. Android Chrome Custom Tabs have neither prompt and the full flow is clean.
```ts
import { Platform } from 'react-native';
import * as AuthSession from 'expo-auth-session';
import * as WebBrowser from 'expo-web-browser';
import * as SecureStore from 'expo-secure-store';
const signOut = async (discovery: AuthSession.DiscoveryDocument, tokens: Tokens) => {
// Clear local state first — a failed RP-initiated logout still leaves you signed out locally.
await SecureStore.deleteItemAsync(TOKENS_KEY);
if (tokens.refreshToken) {
await AuthSession.revokeAsync({ token: tokens.refreshToken, clientId: config.clientId }, discovery).catch(
() => {}
);
}
if (Platform.OS === 'ios') {
// Skip RP-initiated logout. Force `prompt=login` on the next authorize request instead.
return;
}
if (!discovery.endSessionEndpoint) return;
const url = new URL(discovery.endSessionEndpoint);
url.searchParams.set('id_token_hint', tokens.idToken);
url.searchParams.set('post_logout_redirect_uri', config.postLogoutRedirectUri);
url.searchParams.set('client_id', config.clientId);
await WebBrowser.openAuthSessionAsync(url.toString(), config.postLogoutRedirectUri);
};
```
The second argument to `openAuthSessionAsync` is the URI the WebBrowser detects to close itself — it must equal `post_logout_redirect_uri`, and it must be a different value from your sign-in `redirectUri` so the OS deep-link layer can tell sign-in completion apart from sign-out completion.
Then on the next sign-in, force re-authentication on iOS so the local sign-out doesn't feel fake:
```ts
const [request, , promptAsync] = AuthSession.useAuthRequest(
{
clientId: config.clientId,
redirectUri: config.redirectUri,
scopes: ['openid', 'profile', 'national_id', 'offline_access'],
usePKCE: true,
extraParams: forceReauth ? { prompt: 'login' } : undefined,
},
discovery
);
```
Set `forceReauth = true` after `signOut`, clear it after a successful sign-in.
`revokeAsync` invalidates the refresh token server-side. Skipping it leaves a valid refresh token in `SecureStore` after sign-out — if cleared local state is your only defence and the device is later compromised, the token still works.
See the [No framework (curl) guide](https://developers.kenni.is/docs/guides/curl#sign-out) for the protocol-level reasoning.
---
# Flutter
[`flutter_appauth`](https://pub.dev/packages/flutter_appauth) wraps Google's AppAuth SDKs — the canonical OAuth client for native iOS and Android. PKCE, browser tabs, deep-link handling, and silent refresh are all handled by the underlying native code.
Use the **Native** application type in the [developer portal](https://developers.kenni.is) — public client, no secret. Mobile apps cannot keep secrets safely.
## Install
```yaml
# pubspec.yaml
dependencies:
flutter_appauth: ^12.0.0
flutter_secure_storage: ^10.1.0
```
These are the current major versions on pub.dev as of writing — `flutter_appauth` 12 needs Flutter 3.38+ / Dart 3.10+, iOS 13 minimum, and Android `minSdkVersion 24`. The platform bumps are non-optional; see below.
## Platform configuration
### iOS
`flutter_appauth` 12 and `flutter_secure_storage` 10 both require iOS 13. The Podfile shipped by `flutter create` targets iOS 12, which builds but fails at link time with cryptic "Unsupported deployment target" errors.
```ruby
# ios/Podfile
platform :ios, '13.0'
```
### Android
```gradle
// android/app/build.gradle
android {
defaultConfig {
minSdkVersion 24
manifestPlaceholders = [appAuthRedirectScheme: 'is.kenni.example']
}
}
```
The AppAuth Android plugin reads `manifestPlaceholders[appAuthRedirectScheme]` at manifest-merge time — it's how Android registers your custom URL scheme. Use a reverse-DNS form (`is.kenni.example`) — `myapp` collides with every other tutorial app on the device.
### iOS URL scheme
```xml
CFBundleURLTypesCFBundleURLSchemesis.kenni.example
```
Register **two** URIs in the developer portal — `is.kenni.example://callback` as a Redirect URI and `is.kenni.example://post-logout` as a Post logout redirect URI. They're separate lists with separate lifecycles.
## Configuration
The idiomatic Flutter pattern is `--dart-define-from-file` (stable since Flutter 3.7), with values surfaced via `String.fromEnvironment`. No runtime `.env` parser, no extra dependency.
```json
// dart_defines.json (gitignored)
{
"KENNI_ISSUER": "https://idp.kenni.is/",
"KENNI_CLIENT_ID": "@/native",
"KENNI_REDIRECT_URI": "is.kenni.example://callback",
"KENNI_POST_LOGOUT_REDIRECT_URI": "is.kenni.example://post-logout"
}
```
```dart
// lib/src/config.dart
class KenniConfig {
static const issuer = String.fromEnvironment('KENNI_ISSUER');
static const clientId = String.fromEnvironment('KENNI_CLIENT_ID');
static const redirectUrl = String.fromEnvironment('KENNI_REDIRECT_URI');
static const postLogoutRedirectUrl =
String.fromEnvironment('KENNI_POST_LOGOUT_REDIRECT_URI');
static String get discoveryUrl => '$issuer/.well-known/openid-configuration';
static void assertConfigured() {
if (issuer.isEmpty || clientId.isEmpty || redirectUrl.isEmpty || postLogoutRedirectUrl.isEmpty) {
throw StateError(
'Missing KENNI_* dart-defines. Run with --dart-define-from-file=dart_defines.json',
);
}
}
}
```
Run with:
```bash
flutter run --dart-define-from-file=dart_defines.json
```
## Sign-in flow
```dart
import 'dart:convert';
import 'package:flutter_appauth/flutter_appauth.dart';
import 'package:flutter_secure_storage/flutter_secure_storage.dart';
import 'src/config.dart';
final FlutterAppAuth _appAuth = const FlutterAppAuth();
final FlutterSecureStorage _storage = const FlutterSecureStorage();
Future signIn({bool forceReauth = false}) async {
try {
return await _appAuth.authorizeAndExchangeCode(
AuthorizationTokenRequest(
KenniConfig.clientId,
KenniConfig.redirectUrl,
discoveryUrl: KenniConfig.discoveryUrl,
scopes: const ['openid', 'profile', 'national_id', 'offline_access'],
promptValues: forceReauth ? const ['login'] : null,
),
);
} on FlutterAppAuthUserCancelledException {
// User dismissed the in-app browser — not an error to surface.
return null;
}
}
```
`const FlutterAppAuth()` is the right constructor — current versions are `const`-constructable, and the `prefer_const_constructors` lint (default-on with `flutter_lints`) flags the non-const form.
`authorizeAndExchangeCode` performs the authorization request, code exchange, and PKCE in a single call. The returned response contains `accessToken`, `idToken`, `refreshToken`, and `accessTokenExpirationDateTime`. `FlutterAppAuthUserCancelledException` fires when the user dismisses the in-app browser — catch it, don't let it crash to Crashlytics/Sentry as if it were a bug.
## Storing tokens
Persist tokens on sign-in and round-trip them on launch — without this, every relaunch bounces the user back through Kenni even when their Kenni session is still valid.
```dart
const _tokensKey = 'kenni.tokens.v1';
Future persist(AuthorizationTokenResponse res) async {
await _storage.write(
key: _tokensKey,
value: jsonEncode({
'accessToken': res.accessToken,
'idToken': res.idToken,
'refreshToken': res.refreshToken,
'expiresAt': res.accessTokenExpirationDateTime?.toIso8601String(),
}),
);
}
Future?> loadTokens() async {
final raw = await _storage.read(key: _tokensKey);
return raw == null ? null : jsonDecode(raw) as Map;
}
void main() async {
WidgetsFlutterBinding.ensureInitialized();
KenniConfig.assertConfigured();
final tokens = await loadTokens(); // pre-fill auth state before runApp
runApp(MyApp(initialTokens: tokens));
}
```
`flutter_secure_storage` uses Keychain on iOS and EncryptedSharedPreferences on Android. Don't store tokens in `SharedPreferences` directly.
## Showing the user's claims
Decode the `id_token` payload to display the user's name — the canonical "prove sign-in worked" UI.
```dart
Map decodeJwtPayload(String token) {
final parts = token.split('.');
final padded = base64Url.normalize(parts[1]);
return jsonDecode(utf8.decode(base64Url.decode(padded))) as Map;
}
// In a widget:
final claims = decodeJwtPayload(idToken);
Text('Welcome ${claims['name'] ?? claims['sub']}');
```
## Refresh
```dart
Future refresh(String refreshToken) {
return _appAuth.token(
TokenRequest(
KenniConfig.clientId,
KenniConfig.redirectUrl,
discoveryUrl: KenniConfig.discoveryUrl,
refreshToken: refreshToken,
grantType: 'refresh_token',
),
);
}
```
## Sign out
> **Warning.** **RP-initiated logout has rough UX on iOS that Apple doesn't let you fix.** `flutter_appauth.endSession()` uses `ASWebAuthenticationSession` under the hood, which shows a hardcoded _"<App> wants to use 'kenni.is' to sign in"_ consent prompt — even on a sign-out flow. The wording is not configurable. Opening Safari directly via `url_launcher` only trades it for the OS-level _"Open this page in '<App>'?"_ confirmation when Kenni redirects back to the custom scheme. The only clean fix is [Universal Links](https://developer.apple.com/documentation/xcode/supporting-associated-domains): a real HTTPS domain you control + an `apple-app-site-association` file + the `applinks:` entitlement.
>
> **What real iOS apps ship**: skip RP-initiated logout entirely on iOS. Clear local tokens and force `prompt=login` on the next sign-in via `AuthorizationTokenRequest.promptValues = ['login']`. Android Chrome Custom Tabs have neither prompt and the full flow is clean.
```dart
import 'dart:io' show Platform;
Future signOut({required String idToken, String? refreshToken}) async {
// Clear local state first — a failed RP-initiated logout still leaves you signed out locally.
await _storage.deleteAll();
if (Platform.isIOS) {
// Skip endSession on iOS. Set a flag so the next signIn passes promptValues: ['login'].
return;
}
try {
await _appAuth.endSession(
EndSessionRequest(
idTokenHint: idToken,
postLogoutRedirectUrl: KenniConfig.postLogoutRedirectUrl,
discoveryUrl: KenniConfig.discoveryUrl,
),
);
} on FlutterAppAuthUserCancelledException {
// Already cleared locally, the user dismissing the browser is fine.
}
}
```
`postLogoutRedirectUrl` must be a different URI from your sign-in `redirectUrl` so the OS deep-link layer can tell sign-in completion apart from sign-out completion — register both separately in the developer portal.
See the [No framework (curl) guide](https://developers.kenni.is/docs/guides/curl#sign-out) for the protocol-level reasoning.
---
# Node.js / Express
For a server-side Node app outside Next.js, [`openid-client`](https://github.com/panva/node-openid-client) is the reference OIDC library — the same one Auth.js, NextAuth, and better-auth wrap internally.
## Install
```bash
npm install openid-client express express-session jose
```
## Discover and configure
Discovery happens once at startup and gives you a `Configuration` object you'll pass to every subsequent call.
```ts
import * as openid from 'openid-client';
const issuer = new URL('https://idp.kenni.is/');
const config = await openid.discovery(issuer, process.env.KENNI_CLIENT_ID!, process.env.KENNI_CLIENT_SECRET!);
```
> **Warning.** `openid-client` v6 refuses non-HTTPS issuers by default — discovery against `http://localhost:...` throws `OAUTH_HTTP_REQUEST_FORBIDDEN`. For local-IdP development, opt in via the `execute` option (HTTPS-only is the right production default; this is a dev-only carve-out).
```ts
const config = await openid.discovery(issuer, clientId, secret, undefined, {
execute: [openid.allowInsecureRequests],
});
```
Note that `execute` is the fifth argument to `discovery` (after a usually-undefined client-authentication argument).
## Login route
Generate a PKCE verifier and a state, store both on the session, then redirect to the authorization endpoint. The handler must be `async` because `calculatePKCECodeChallenge` returns a `Promise`.
```ts
app.get('/login', async (req, res) => {
const codeVerifier = openid.randomPKCECodeVerifier();
const codeChallenge = await openid.calculatePKCECodeChallenge(codeVerifier);
const state = openid.randomState();
req.session.codeVerifier = codeVerifier;
req.session.state = state;
const url = openid.buildAuthorizationUrl(config, {
redirect_uri: 'http://localhost:3000/callback',
scope: 'openid profile national_id offline_access',
code_challenge: codeChallenge,
code_challenge_method: 'S256',
state,
});
res.redirect(url.href);
});
```
> **Warning.** Forgetting `await` on `calculatePKCECodeChallenge` is the most common mistake — `codeChallenge` becomes a `Promise` stringified into the URL as `[object Promise]`, and the IdP rejects the request with no useful hint.
## Callback route
```ts
app.get('/callback', async (req, res) => {
const tokens = await openid.authorizationCodeGrant(config, new URL(req.url, 'http://localhost:3000'), {
pkceCodeVerifier: req.session.codeVerifier!,
expectedState: req.session.state!,
});
req.session.tokens = {
access_token: tokens.access_token,
refresh_token: tokens.refresh_token,
id_token: tokens.id_token,
};
const claims = (tokens.claims() ?? {}) as Record;
req.session.user = { sub: claims.sub, name: claims.name };
res.redirect('/');
});
```
Register `http://localhost:3000/callback` as a redirect URI on your application in the [developer portal](https://developers.kenni.is).
## Refresh
```ts
const refreshed = await openid.refreshTokenGrant(config, req.session.tokens.refresh_token);
req.session.tokens.access_token = refreshed.access_token;
req.session.tokens.refresh_token = refreshed.refresh_token ?? req.session.tokens.refresh_token;
```
## Public clients
For a public Node client (rare — usually you'd use the SPA or Native type for public flows), pass `openid.None()` as the fourth argument to `discovery()`:
```ts
const config = await openid.discovery(issuer, clientId, undefined, openid.None());
```
PKCE is then the only proof on the token request.
## Sign out
`req.session.destroy()` clears your session but leaves the Kenni session alive — the next sign-in silently re-authenticates. Use `openid-client`'s `buildEndSessionUrl` to redirect through Kenni's `end_session_endpoint`:
```ts
app.get('/logout', (req, res) => {
const idToken = req.session.tokens?.id_token;
const url = openid.buildEndSessionUrl(config, {
id_token_hint: idToken,
post_logout_redirect_uri: 'http://localhost:3000/logged-out',
});
req.session.destroy(() => res.redirect(url.href));
});
```
`buildEndSessionUrl` reads `client_id` from the `Configuration`, so you only need to pass `id_token_hint` and `post_logout_redirect_uri`. `end_session_endpoint` is OIDC-spec-optional; Kenni always advertises it, but if you're targeting other IdPs guard against the empty case.
Register `http://localhost:3000/logged-out` on the application's **Post logout redirect URIs** list in the [developer portal](https://developers.kenni.is). See the [No framework (curl) guide](https://developers.kenni.is/docs/guides/curl#sign-out) for the full reasoning.
## Verifying access tokens
The auth flow above gets a user signed in. The other half of the spec is the API server that _receives_ a Kenni access token on an incoming request and has to validate it.
`openid-client` v6 is deliberately auth-flow-only — it doesn't expose a JWT-verification helper for arbitrary tokens. Pair it with [`jose`](https://github.com/panva/jose) for the resource-server side. `config.serverMetadata()` reads any field from the cached discovery doc without re-fetching:
```ts
import * as jose from 'jose';
const metadata = config.serverMetadata();
const jwks = jose.createRemoteJWKSet(new URL(metadata.jwks_uri!));
async function verifyAccessToken(raw: string) {
const { payload } = await jose.jwtVerify(raw, jwks, {
issuer: metadata.issuer,
audience: process.env.KENNI_API_AUDIENCE!, // e.g. "-api"
});
const scopes = String(payload.scope ?? '').split(' ');
if (!scopes.includes(process.env.KENNI_API_SCOPE!)) {
throw new Error('insufficient scope');
}
return payload;
}
app.get('/api/protected', async (req, res) => {
const auth = req.header('authorization') ?? '';
const raw = auth.startsWith('Bearer ') ? auth.slice(7) : '';
try {
const claims = await verifyAccessToken(raw);
res.json({ sub: claims.sub });
} catch {
res.status(401).json({ error: 'invalid_token' });
}
});
```
`createRemoteJWKSet` caches keys and handles rotation transparently — reuse the same instance across requests. Access tokens are JWTs only when you request a custom API scope; see [API scopes](https://developers.kenni.is/docs/api-scopes) for the opaque-vs-JWT distinction.
## Client credentials (M2M)
For machine-to-machine calls (no user, no browser), use the client-credentials grant. `openid-client` v6 ships a one-call helper:
```ts
const tokens = await openid.clientCredentialsGrant(config, {
scope: process.env.KENNI_API_SCOPE!,
});
// tokens.access_token is a JWT with `aud = `, ready to send to your API.
```
The same `verifyAccessToken` from the section above validates these tokens.
---
# Java / Spring Boot
Spring Security's OAuth 2.0 Client support handles Kenni without any custom code — point its `provider` config at your discovery URL and it does the rest. A few Kenni-specific defaults need wiring (PKCE on confidential clients, RFC 9068 access tokens, audience validation), all covered below.
## Dependencies
```xml
org.springframework.bootspring-boot-starter-oauth2-clientorg.springframework.bootspring-boot-starter-oauth2-resource-serverorg.springframework.bootspring-boot-starter-security
```
## `application.yml`
```yaml
spring:
security:
oauth2:
client:
provider:
kenni:
issuer-uri: ${KENNI_ISSUER:}
registration:
kenni:
provider: kenni
client-id: ${KENNI_CLIENT_ID:}
client-secret: ${KENNI_CLIENT_SECRET:}
authorization-grant-type: authorization_code
redirect-uri: '{baseUrl}/login/oauth2/code/{registrationId}'
scope:
- openid
- profile
- national_id
- offline_access
```
Setting `issuer-uri` lets Spring discover endpoints, JWKS, and supported features automatically.
`{baseUrl}` is a Spring URL template — it expands to `http://:` at sign-in time. Register `https:///login/oauth2/code/kenni` as a redirect URI on your application in the [developer portal](https://developers.kenni.is). Changing the `kenni` registration ID requires re-registering a different redirect URI.
> **Note.** Default `${KENNI_*}` placeholders to empty (`${KENNI_ISSUER:}`) and validate at startup. Unresolved `${KENNI_ISSUER}` strings get treated as URI templates by Spring's `UriComponentsBuilder` and surface as confusing `IllegalArgumentException: Not enough variable values available` errors elsewhere.
### When the API scope is conditional
Apps that conditionally request a custom API scope can't express that in YAML — `scope:` is a fixed list. Drop `spring.security.oauth2.client.*` from YAML and build a `ClientRegistrationRepository` `@Bean` programmatically:
```java
@Bean
ClientRegistrationRepository clientRegistrations(KenniProperties kenni) {
var scopes = new LinkedHashSet<>(List.of("openid", "profile", "national_id", "offline_access"));
if (kenni.apiEnabled()) scopes.add(kenni.apiScope());
var registration = ClientRegistrations.fromIssuerLocation(kenni.issuer())
.registrationId("kenni")
.clientId(kenni.clientId())
.clientSecret(kenni.clientSecret())
.authorizationGrantType(AuthorizationGrantType.AUTHORIZATION_CODE)
.redirectUri("{baseUrl}/login/oauth2/code/{registrationId}")
.scope(scopes)
.build();
return new InMemoryClientRegistrationRepository(registration);
}
```
The Spring Boot auto-config bean is `@ConditionalOnMissingBean`, so this suppresses the YAML-driven setup. Without it, an empty `${KENNI_API_SCOPE}` either gets appended literally or is silently dropped — and `/api/protected-resource` returns 401 forever even after a successful sign-in.
## Wire PKCE for confidential clients
> **Warning.** Spring Security 6 auto-enables PKCE only for **public** clients (`client-authentication-method: none`). Confidential clients (`client_secret_basic` / `client_secret_post`) must wire it in explicitly. **Kenni requires PKCE** — without this, the auth flow fails on token exchange and Spring redirects to its default `/login?error` page with the misleading message "Invalid credentials".
```java
import org.springframework.security.oauth2.client.web.DefaultOAuth2AuthorizationRequestResolver;
import org.springframework.security.oauth2.client.web.OAuth2AuthorizationRequestResolver;
import org.springframework.security.oauth2.client.registration.ClientRegistrationRepository;
import org.springframework.security.oauth2.client.web.OAuth2AuthorizationRequestCustomizers;
private static OAuth2AuthorizationRequestResolver pkceAwareResolver(
ClientRegistrationRepository repo) {
var resolver = new DefaultOAuth2AuthorizationRequestResolver(repo, "/oauth2/authorization");
resolver.setAuthorizationRequestCustomizer(
OAuth2AuthorizationRequestCustomizers.withPkce());
return resolver;
}
```
…then plug it into `oauth2Login` (see the security configuration below).
## Security configuration
Mix UI (cookie-session OIDC) and API (bearer JWT) endpoints with two `SecurityFilterChain` beans, each scoped by `securityMatcher` and ordered:
```java
@Configuration
@EnableWebSecurity
public class SecurityConfig {
@Bean
@Order(1)
SecurityFilterChain apiChain(HttpSecurity http, JwtDecoder jwtDecoder) throws Exception {
return http
.securityMatcher("/api/**")
.authorizeHttpRequests(auth -> auth
.anyRequest().hasAuthority("SCOPE_" + System.getenv("KENNI_API_SCOPE")))
.oauth2ResourceServer(rs -> rs.jwt(jwt -> jwt.decoder(jwtDecoder)))
.csrf(csrf -> csrf.disable())
.build();
}
@Bean
@Order(2)
SecurityFilterChain uiChain(HttpSecurity http,
ClientRegistrationRepository clients) throws Exception {
var logoutSuccess = new OidcClientInitiatedLogoutSuccessHandler(clients);
logoutSuccess.setPostLogoutRedirectUri("{baseUrl}/");
return http
.authorizeHttpRequests(auth -> auth.anyRequest().authenticated())
.oauth2Login(o -> o.authorizationEndpoint(a ->
a.authorizationRequestResolver(pkceAwareResolver(clients))))
.logout(logout -> logout.logoutSuccessHandler(logoutSuccess))
.build();
}
}
```
> **Note.** Spring's default `JwtAuthenticationConverter` maps the `scope` claim to authorities prefixed with `SCOPE_`. Use `.hasAuthority("SCOPE_")` — not `.hasRole(...)` and not `.hasAuthority("")`.
## Verifying access tokens (JwtDecoder)
Two Kenni-specific defaults need overriding on the resource-server `JwtDecoder`:
1. **RFC 9068 token type.** Kenni issues access tokens with `"typ": "at+jwt"` per [RFC 9068](https://datatracker.ietf.org/doc/html/rfc9068). Spring's default `NimbusJwtDecoder` accepts only `"typ": "JWT"` (or absent) and rejects everything else with `WWW-Authenticate: Bearer error="invalid_token", error_description="JOSE header typ (type) at+jwt not allowed"`.
2. **Audience validation.** `issuer-uri` alone validates issuer + signature + expiry but **not** audience. Without audience validation, any Kenni token from the same tenant — including id_tokens or access tokens minted for other APIs — will pass.
```java
@Bean
JwtDecoder jwtDecoder(@Value("${KENNI_ISSUER}") String issuer,
@Value("${KENNI_API_AUDIENCE}") String audience) {
var decoder = NimbusJwtDecoder.withIssuerLocation(issuer)
.jwtProcessorCustomizer(processor -> processor.setJWSTypeVerifier(
new DefaultJOSEObjectTypeVerifier<>(
JOSEObjectType.JWT,
new JOSEObjectType("at+jwt"))))
.build();
var withIssuer = JwtValidators.createDefaultWithIssuer(issuer);
var withAudience = new JwtClaimValidator>(
JwtClaimNames.AUD, aud -> aud != null && aud.contains(audience));
decoder.setJwtValidator(new DelegatingOAuth2TokenValidator<>(withIssuer, withAudience));
return decoder;
}
```
On Spring Boot 3.4+ you can replace the `JwtClaimValidator` block with the `audiences:` property:
```yaml
spring:
security:
oauth2:
resourceserver:
jwt:
issuer-uri: ${KENNI_ISSUER}
audiences:
- ${KENNI_API_AUDIENCE}
```
…but you still need the `jwtProcessorCustomizer` for `at+jwt`, so a custom `@Bean` is usually simpler.
## Reading user claims
Inject `@AuthenticationPrincipal OidcUser principal` into your controller methods. `principal.getClaims()` returns everything from the ID token; `principal.getIdToken().getTokenValue()` returns the raw JWT.
## Calling APIs with the access token
`@RegisteredOAuth2AuthorizedClient("kenni")` exposes the user's authorized client, including the access token:
```java
@GetMapping("/api/me")
public Map me(
@RegisteredOAuth2AuthorizedClient("kenni") OAuth2AuthorizedClient client) {
String accessToken = client.getAccessToken().getTokenValue();
// Forward the token to a downstream service…
return Map.of("token", accessToken);
}
```
## Client credentials (M2M)
For machine-to-machine calls, hit the token endpoint directly with HTTP Basic auth:
```java
@Bean
RestClient kenniTokenClient(@Value("${KENNI_ISSUER}") String issuer) {
return RestClient.builder().baseUrl(issuer).build();
}
public String fetchClientCredentialsToken(RestClient client,
String clientId, String clientSecret,
String scope) {
var basic = Base64.getEncoder()
.encodeToString((clientId + ":" + clientSecret).getBytes(StandardCharsets.UTF_8));
Map body = client.post()
.uri("/oidc/token")
.header(HttpHeaders.AUTHORIZATION, "Basic " + basic)
.contentType(MediaType.APPLICATION_FORM_URLENCODED)
.body("grant_type=client_credentials&scope=" + URLEncoder.encode(scope, UTF_8))
.retrieve()
.body(new ParameterizedTypeReference<>() {});
return (String) body.get("access_token");
}
```
For credentials with special characters, the form-urlencoded Basic auth from [RFC 6749 §2.3.1](https://datatracker.ietf.org/doc/html/rfc6749#section-2.3.1) requires `base64(form_urlencode(id) + ":" + form_urlencode(secret))`.
## Sign out
`OidcClientInitiatedLogoutSuccessHandler` (wired in the UI chain above) redirects logout through Kenni's `end_session_endpoint`. It requires the servlet stack — **not** WebFlux. Spring's default logout responds to `POST /logout`; a `GET /logout` link returns 404.
Register the resolved post-logout URL (e.g. `https:///`) on the application's **Post logout redirect URIs** list in the [developer portal](https://developers.kenni.is). See the [No framework (curl) guide](https://developers.kenni.is/docs/guides/curl#sign-out) for the full reasoning.
## Troubleshooting
- **"Invalid credentials" on `/login?error`** — Spring's default error page hides the cause. Set `logging.level.org.springframework.security: DEBUG` (or `TRACE`) to see the actual reason. The most common culprit on a fresh Kenni integration is missing PKCE.
- **`HTTP 400 — Request header is too large`** — Tomcat's default 8KB header limit overflows after a couple of failed sign-in attempts (stale `OAUTH2_AUTHORIZATION_REQUEST` cookies pile up). Bump it: `server.max-http-request-header-size: 16KB`.
- **Empty 401 / 403 bodies** — Spring's resource-server returns the actual reason in the `WWW-Authenticate` header (`error="insufficient_scope"`, `error="invalid_token"`). JS proxies should fall back to that header when the upstream body is empty.
---
# C# / .NET MVC
ASP.NET Core's built-in `OpenIdConnect` handler integrates Kenni without any additional packages beyond what's in the framework. Authority discovery, PKCE, and token refresh are all handled for you.
## Packages
Both packages ship with .NET 8+:
```
Microsoft.AspNetCore.Authentication.Cookies
Microsoft.AspNetCore.Authentication.OpenIdConnect
```
If you also want to verify access tokens on a protected API, add:
```
Microsoft.AspNetCore.Authentication.JwtBearer
```
## `Program.cs`
> **Warning.** ASP.NET's default `JwtSecurityTokenHandler` rewrites OIDC claim names (`sub` → `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier`, `name` → `…/claims/name`, etc.) before the user's claims principal is built. So `User.FindFirst("sub")` returns `null` in handlers even though `sub` is right there in the token. Disable the remap globally and on every JWT-consuming handler.
```csharp
using System.IdentityModel.Tokens.Jwt;
using Microsoft.AspNetCore.Authentication.Cookies;
using Microsoft.AspNetCore.Authentication.JwtBearer;
using Microsoft.AspNetCore.Authentication.OpenIdConnect;
// Disable the legacy SOAP claim-name remap globally.
JwtSecurityTokenHandler.DefaultMapInboundClaims = false;
var builder = WebApplication.CreateBuilder(args);
var config = builder.Configuration;
builder.Services
.AddAuthentication(options =>
{
options.DefaultScheme = CookieAuthenticationDefaults.AuthenticationScheme;
options.DefaultChallengeScheme = OpenIdConnectDefaults.AuthenticationScheme;
})
.AddCookie()
.AddOpenIdConnect(options =>
{
options.Authority = config["KENNI_ISSUER"]; // https://idp.kenni.is/
options.ClientId = config["KENNI_CLIENT_ID"]; // @/web
options.ClientSecret = config["KENNI_CLIENT_SECRET"];
options.ResponseType = "code";
options.UsePkce = true;
options.SaveTokens = true;
// Kenni's id_token already carries the claims we need; skip the extra round-trip.
options.GetClaimsFromUserInfoEndpoint = false;
options.MapInboundClaims = false;
options.Scope.Clear();
options.Scope.Add("openid");
options.Scope.Add("profile");
options.Scope.Add("national_id");
options.Scope.Add("offline_access");
// Optional: add a custom API scope if your application has one.
// options.Scope.Add(config["KENNI_API_SCOPE"]);
});
builder.Services.AddAuthorization();
builder.Services.AddControllersWithViews();
var app = builder.Build();
app.UseAuthentication();
app.UseAuthorization();
app.MapDefaultControllerRoute();
app.Run();
```
`Authority` is your team's issuer URL. The handler fetches the discovery document automatically and uses it to configure every other endpoint.
`UsePkce = true` is set explicitly — defence in depth even for confidential clients.
> **Note.** Read configuration from environment variables, user secrets, or `appsettings.json`. Don't paste your `client_secret` into source — that's the kind of mistake that ends up in version control.
## Redirect URI registration
The OIDC handler's default callback path is `/signin-oidc`. Combined with a local port (the rest of this guide assumes `5000`), the redirect URI to register in the [developer portal](https://developers.kenni.is) is:
```
http://localhost:5000/signin-oidc
```
The default post-logout callback path is `/signout-callback-oidc`. Pin your dev server to a single HTTP URL (edit `Properties/launchSettings.json`) so you only register one redirect URI. The defaults work over plain HTTP for local dev — don't add `CookieSecurePolicy.Always` or `SameSiteMode.None` unless you've already wired up `dotnet dev-certs`.
## Reading claims
With `MapInboundClaims = false`, claims keep their OIDC names:
```csharp
var sub = User.FindFirst("sub")?.Value;
var nationalId = User.FindFirst("national_id")?.Value;
var name = User.Identity?.Name;
```
## Reading the access token
`SaveTokens = true` stores the tokens against the cookie. Retrieve them via `HttpContext.GetTokenAsync`:
```csharp
using Microsoft.AspNetCore.Authentication;
var accessToken = await HttpContext.GetTokenAsync("access_token");
var idToken = await HttpContext.GetTokenAsync("id_token");
var refreshToken = await HttpContext.GetTokenAsync("refresh_token");
```
## Verifying access tokens on a protected API
If your application also exposes an API protected by a custom scope, validate the bearer JWT and enforce the scope. Issuer / audience / expiry / signature are not enough — the resource server also needs to check that the token was issued for _its_ scope.
```csharp
builder.Services
.AddAuthentication() // already added above
.AddJwtBearer(options =>
{
options.Authority = config["KENNI_ISSUER"];
options.Audience = config["KENNI_CLIENT_ID"]; // or your configured API audience
options.MapInboundClaims = false;
options.TokenValidationParameters.ValidateIssuer = true;
options.TokenValidationParameters.ValidateAudience = true;
options.TokenValidationParameters.ValidateLifetime = true;
});
builder.Services.AddAuthorization(options =>
{
options.AddPolicy("ApiScope", policy =>
{
policy.RequireAuthenticatedUser();
policy.AuthenticationSchemes = new[] { JwtBearerDefaults.AuthenticationScheme };
policy.RequireAssertion(ctx =>
{
var scope = ctx.User.FindFirst("scope")?.Value ?? "";
return scope.Split(' ').Contains(config["KENNI_API_SCOPE"]);
});
});
});
```
Then on the protected controller:
```csharp
[Authorize(Policy = "ApiScope", AuthenticationSchemes = JwtBearerDefaults.AuthenticationScheme)]
public IActionResult ProtectedResource() => Ok(new { ok = true });
```
## Public clients
For SPA or Native clients, drop `ClientSecret` and let PKCE carry the token request:
```csharp
options.ClientSecret = null;
options.UsePkce = true;
```
## Sign out
Calling `SignOutAsync` on the cookie scheme alone clears the local session but leaves the Kenni session alive — the next sign-in silently re-authenticates. Sign out of both schemes so the OpenID Connect handler also redirects through Kenni's `end_session_endpoint`:
```csharp
[Authorize]
public IActionResult Logout()
{
return SignOut(
new AuthenticationProperties { RedirectUri = "/" },
CookieAuthenticationDefaults.AuthenticationScheme,
OpenIdConnectDefaults.AuthenticationScheme);
}
```
The handler reads `end_session_endpoint` from discovery and sends `id_token_hint` and `post_logout_redirect_uri` automatically (because `SaveTokens = true` made the `id_token` available). Register the resolved post-logout URL (e.g. `http://localhost:5000/signout-callback-oidc`) on the application's **Post logout redirect URIs** list in the [developer portal](https://developers.kenni.is). See the [No framework (curl) guide](https://developers.kenni.is/docs/guides/curl#sign-out) for the full reasoning.
---
# Go
The de facto Go OIDC stack is [`golang.org/x/oauth2`](https://pkg.go.dev/golang.org/x/oauth2) for the OAuth flow plus [`github.com/coreos/go-oidc/v3`](https://github.com/coreos/go-oidc) for ID token verification and JWKS handling.
`go-oidc/v3` v3.18 (current at the time of writing) requires Go 1.25 — with the default `GOTOOLCHAIN=auto` (Go 1.21+) the newer toolchain auto-downloads. Readers on `GOTOOLCHAIN=local` and an older Go will see a confusing `go.mod requires go >= 1.25` error.
## Install
```bash
go get golang.org/x/oauth2
go get github.com/coreos/go-oidc/v3/oidc
```
## Discover and configure
Discovery is a network call that can fail, so do it from `main` (or a `setup(ctx)` helper) rather than `init()` — that way a transient flake at boot returns a real error instead of panicking before logging is configured.
```go
package main
import (
"context"
"encoding/json"
"net/http"
"net/url"
"os"
"github.com/coreos/go-oidc/v3/oidc"
"golang.org/x/oauth2"
)
var (
provider *oidc.Provider
oauth2Config oauth2.Config
verifier *oidc.IDTokenVerifier
discovery struct {
EndSessionEndpoint string `json:"end_session_endpoint"`
TokenEndpoint string `json:"token_endpoint"`
JWKSURI string `json:"jwks_uri"`
}
)
func setupKenni(ctx context.Context) error {
p, err := oidc.NewProvider(ctx, "https://idp.kenni.is/")
if err != nil {
return err
}
provider = p
clientID := os.Getenv("KENNI_CLIENT_ID")
oauth2Config = oauth2.Config{
ClientID: clientID,
ClientSecret: os.Getenv("KENNI_CLIENT_SECRET"),
RedirectURL: "http://localhost:8080/callback",
Endpoint: provider.Endpoint(),
Scopes: []string{oidc.ScopeOpenID, "profile", "national_id", oidc.ScopeOfflineAccess},
}
verifier = provider.Verifier(&oidc.Config{ClientID: clientID})
// provider.Endpoint() only exposes auth_endpoint / token_endpoint.
// Use provider.Claims to read other discovery fields.
return provider.Claims(&discovery)
}
```
## Login handler
PKCE is required for public clients and recommended for confidential ones too — it's a one-line addition that costs nothing and defends against authorization-code interception. Generate the verifier alongside `state` and `nonce`, and persist all three to a short-lived cookie or session.
```go
func handleLogin(w http.ResponseWriter, r *http.Request) {
state := randomString(32)
nonce := randomString(32)
pkceVerifier := oauth2.GenerateVerifier()
setCookie(w, "state", state)
setCookie(w, "nonce", nonce)
setCookie(w, "pkce", pkceVerifier)
url := oauth2Config.AuthCodeURL(
state,
oidc.Nonce(nonce),
oauth2.S256ChallengeOption(pkceVerifier),
)
http.Redirect(w, r, url, http.StatusFound)
}
```
Refresh tokens are requested via the `offline_access` scope (already in `setupKenni`) — no `oauth2.AccessTypeOffline` needed.
## Callback handler
Handle the `error` / `error_description` query params first — Kenni redirects with these on user cancellation, and skipping the check produces a confusing "missing code" error from `Exchange` instead of the real reason. Verify `state`, exchange the code with the stored PKCE verifier, then verify the ID token's signature _and_ its `nonce` claim.
```go
func handleCallback(w http.ResponseWriter, r *http.Request) {
if e := r.URL.Query().Get("error"); e != "" {
http.Error(w, e+": "+r.URL.Query().Get("error_description"), http.StatusBadRequest)
return
}
if r.URL.Query().Get("state") != cookieValue(r, "state") {
http.Error(w, "state mismatch", http.StatusBadRequest)
return
}
pkceVerifier := cookieValue(r, "pkce")
oauth2Token, err := oauth2Config.Exchange(
r.Context(),
r.URL.Query().Get("code"),
oauth2.VerifierOption(pkceVerifier),
)
if err != nil {
http.Error(w, err.Error(), http.StatusInternalServerError)
return
}
rawIDToken, ok := oauth2Token.Extra("id_token").(string)
if !ok {
http.Error(w, "no id_token", http.StatusInternalServerError)
return
}
idToken, err := verifier.Verify(r.Context(), rawIDToken)
if err != nil {
http.Error(w, err.Error(), http.StatusInternalServerError)
return
}
if idToken.Nonce != cookieValue(r, "nonce") {
http.Error(w, "nonce mismatch", http.StatusBadRequest)
return
}
var claims struct {
Sub string `json:"sub"`
Name string `json:"name"`
NationalID string `json:"national_id"`
}
if err := idToken.Claims(&claims); err != nil {
http.Error(w, err.Error(), http.StatusInternalServerError)
return
}
// Persist oauth2Token + claims on your session.
}
```
Register `http://localhost:8080/callback` as a redirect URI on your application in the [developer portal](https://developers.kenni.is).
> **Note.** `net/http` ships no session library. For storing `oauth2Token` and claims server-side, [`gorilla/sessions`](https://github.com/gorilla/sessions) and [`alexedwards/scs`](https://github.com/alexedwards/scs) are both solid; for demos, an opaque-cookie-keyed in-memory `map` is enough. The cookie-helper stubs (`randomString`, `setCookie`, `cookieValue`, `clearSession`) used in this guide are minimal — for the state/nonce/pkce cookies, set `HttpOnly: true`, `SameSite: http.SameSiteLaxMode`, `MaxAge: 600`, and `Secure: r.TLS != nil` so they work on `http://localhost` and on `https://` prod alike.
## Refresh
`oauth2.Config.TokenSource(ctx, oauth2Token)` returns a `TokenSource` that auto-refreshes using the refresh token. Wrap it in `oauth2.NewClient(ctx, tokenSource)` and use the returned `*http.Client` to call your APIs:
```go
client := oauth2.NewClient(ctx, oauth2Config.TokenSource(ctx, oauth2Token))
resp, err := client.Get("https://my-api.example.com/widgets")
```
`Authorization: Bearer ` is added automatically and tokens rotate transparently. If you need a custom HTTP client (proxy, retries, mTLS) for both discovery and JWKS fetches, pass it via `oidc.ClientContext(ctx, httpClient)` before the `NewProvider` / `Verify` calls.
## Sign out
Clearing the user's session cookie kills your tokens but leaves the Kenni session alive — the next sign-in silently re-authenticates. Neither `golang.org/x/oauth2` nor `coreos/go-oidc` ship a logout helper, so build the redirect by hand from the discovery doc you cached in `setupKenni`:
```go
func handleLogout(w http.ResponseWriter, r *http.Request) {
idToken := /* the id_token from the user's session */
clearSession(w) // clear local session first — a failed end-session redirect still leaves us logged out locally
u, _ := url.Parse(discovery.EndSessionEndpoint)
q := u.Query()
q.Set("id_token_hint", idToken)
q.Set("post_logout_redirect_uri", "http://localhost:8080/")
q.Set("client_id", oauth2Config.ClientID)
u.RawQuery = q.Encode()
http.Redirect(w, r, u.String(), http.StatusFound)
}
```
Register `http://localhost:8080/` on the application's **Post logout redirect URIs** list in the [developer portal](https://developers.kenni.is). See the [No framework (curl) guide](https://developers.kenni.is/docs/guides/curl#sign-out) for the full reasoning.
## Verifying access tokens
The auth flow above gets a user signed in. The other half of the spec is the API server that _receives_ a Kenni access token on an incoming request and has to validate it.
The trick is non-obvious: `provider.Verifier` is named "ID token verifier", but it works on any JWT — it just checks `iss`, `aud`, signature, and expiry, which is the same shape an access token has. Reuse the same `Provider`, but pass the **API audience** as `ClientID`:
```go
var apiVerifier *oidc.IDTokenVerifier
func setupAPIVerifier() {
apiAudience := os.Getenv("KENNI_API_AUDIENCE") // e.g. "-api"
apiVerifier = provider.Verifier(&oidc.Config{ClientID: apiAudience})
}
func protectedHandler(w http.ResponseWriter, r *http.Request) {
auth := r.Header.Get("Authorization")
if !strings.HasPrefix(auth, "Bearer ") {
http.Error(w, "missing bearer", http.StatusUnauthorized)
return
}
raw := strings.TrimPrefix(auth, "Bearer ")
idToken, err := apiVerifier.Verify(r.Context(), raw)
if err != nil {
http.Error(w, "invalid_token", http.StatusUnauthorized)
return
}
var claims struct {
Sub string `json:"sub"`
Scope string `json:"scope"`
}
if err := idToken.Claims(&claims); err != nil {
http.Error(w, err.Error(), http.StatusInternalServerError)
return
}
required := os.Getenv("KENNI_API_SCOPE")
if !slices.Contains(strings.Fields(claims.Scope), required) {
http.Error(w, "insufficient_scope", http.StatusForbidden)
return
}
// ...handle the authenticated request.
}
```
The `apiVerifier` instance handles JWKS fetching and key rotation transparently — reuse a single instance across all incoming requests. Access tokens are JWTs only when you request a custom API scope; see [API scopes](https://developers.kenni.is/docs/api-scopes) for the opaque-vs-JWT distinction.
## Client credentials (M2M)
For machine-to-machine calls (no user, no browser), use the client-credentials grant. There's no helper in `go-oidc` or `oauth2` for it against a discovered endpoint — `http.PostForm` with HTTP Basic auth is the shortest path:
```go
func clientCredentialsToken(ctx context.Context, scope string) (string, error) {
form := url.Values{}
form.Set("grant_type", "client_credentials")
form.Set("scope", scope)
req, err := http.NewRequestWithContext(ctx, "POST", discovery.TokenEndpoint, strings.NewReader(form.Encode()))
if err != nil {
return "", err
}
req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
req.SetBasicAuth(
url.QueryEscape(os.Getenv("KENNI_CLIENT_ID")),
url.QueryEscape(os.Getenv("KENNI_CLIENT_SECRET")),
)
resp, err := http.DefaultClient.Do(req)
if err != nil {
return "", err
}
defer resp.Body.Close()
if resp.StatusCode != http.StatusOK {
body, _ := io.ReadAll(resp.Body)
return "", fmt.Errorf("token endpoint: %s: %s", resp.Status, body)
}
var out struct {
AccessToken string `json:"access_token"`
}
if err := json.NewDecoder(resp.Body).Decode(&out); err != nil {
return "", err
}
return out.AccessToken, nil
}
```
Per RFC 6749 §2.3.1, `client_id` and `client_secret` are form-urlencoded _before_ being joined for HTTP Basic — the `url.QueryEscape` calls above handle special characters in either credential. The returned access token is a JWT with `aud = `; verify it with the same `apiVerifier` shown above.
---
# Python
[Authlib](https://docs.authlib.org/) is the de facto OIDC client library for Python — works with Flask, FastAPI, Django, and standalone scripts. The example below uses Flask, but the moving parts are the same in any framework.
For Django specifically, [`mozilla-django-oidc`](https://github.com/mozilla/mozilla-django-oidc) is more idiomatic and integrates with `django.contrib.auth` directly.
## Install
```bash
python3 -m venv .venv
.venv/bin/pip install authlib flask requests
```
Use `.venv/bin/python app.py` (and `.venv/bin/pip ...`) rather than `source .venv/bin/activate` + bare `python` — that way shell aliases or pyenv shims can't silently route to a different interpreter.
> **Note.** On macOS, port 5000 is taken by AirPlay Receiver (System Settings → General → AirDrop & Handoff). The rest of this guide assumes port 5001 to avoid the collision. Either turn AirPlay Receiver off, or run with `flask run --port 5001` and register `http://localhost:5001/callback`.
## Register the provider
```python
import os
from authlib.integrations.flask_client import OAuth
from flask import Flask, redirect, session, url_for
app = Flask(__name__)
# 32+ random chars, stable across restarts (otherwise existing sessions get invalidated).
app.secret_key = os.environ["FLASK_SECRET"]
oauth = OAuth(app)
oauth.register(
name="kenni",
client_id=os.environ["KENNI_CLIENT_ID"],
client_secret=os.environ["KENNI_CLIENT_SECRET"],
server_metadata_url="https://idp.kenni.is//.well-known/openid-configuration",
client_kwargs={
"scope": "openid profile national_id offline_access",
"code_challenge_method": "S256",
},
)
```
`server_metadata_url` triggers discovery — Authlib reads the issuer's well-known document and configures every endpoint. `code_challenge_method=S256` enables PKCE for both public and confidential clients (defence in depth).
## Login route
```python
@app.route("/login")
def login():
return oauth.kenni.authorize_redirect(url_for("callback", _external=True))
```
`_external=True` is required — Authlib needs an absolute redirect URI.
## Callback route
```python
@app.route("/callback")
def callback():
token = oauth.kenni.authorize_access_token()
session["userinfo"] = dict(token.get("userinfo") or {})
session["id_token"] = token["id_token"]
session["access_token"] = token["access_token"]
session["refresh_token"] = token.get("refresh_token")
return redirect("/")
```
`token["userinfo"]` is parsed from the verified ID token. `authorize_access_token()` validates the signature, `iss`, `aud`, and `nonce` for you. Casting to a plain `dict` keeps the value portable across session backends.
Saving `id_token` here makes it available later for RP-initiated logout. Register `http://localhost:5001/callback` as a redirect URI on your application in the [developer portal](https://developers.kenni.is). To derive it dynamically, use `url_for("callback", _external=True)`.
> **Warning.** Flask's default session is a signed-but-not-encrypted cookie capped at ~4KB. `id_token + access_token + refresh_token + userinfo` is in the 2–3KB range — close enough that any extra payload tips you over. Switch to server-side sessions (e.g. [`flask-session`](https://flask-session.readthedocs.io/) backed by Redis or filesystem) for anything beyond a demo. Storing tokens in an unencrypted cookie also means anyone with the cookie reads the tokens.
## Calling your API
```python
import requests
res = requests.get(
"https://api.example.com/orders",
headers={"Authorization": f"Bearer {session['access_token']}"},
)
```
## Verifying access tokens
When _your_ Python service receives a Kenni access token (because you requested a custom API scope), validate it locally against the JWKS from discovery — issuer, audience, expiry, signature, plus the scope check:
```python
import requests
from authlib.jose import JsonWebKey, jwt
ISSUER = "https://idp.kenni.is/"
API_AUDIENCE = ""
API_SCOPE = ""
# Cache this — don't refetch the JWKS per request.
metadata = oauth.kenni.load_server_metadata()
keyset = JsonWebKey.import_key_set(requests.get(metadata["jwks_uri"]).json())
def verify_bearer(raw_bearer: str) -> dict:
claims = jwt.decode(
raw_bearer,
keyset,
claims_options={
"iss": {"essential": True, "value": ISSUER},
"aud": {"essential": True, "value": API_AUDIENCE},
"exp": {"essential": True},
},
)
claims.validate()
if API_SCOPE not in claims.get("scope", "").split():
raise PermissionError("missing required scope")
return claims
```
> **Note.** `authlib.jose` emits an `AuthlibDeprecationWarning` recommending [`joserfc`](https://jose.authlib.org/) instead. The API stays compatible until Authlib 2.0; pin Authlib if the warning is noisy, or migrate to `joserfc` for new code.
## Client credentials (M2M)
For machine-to-machine calls, hit the token endpoint directly:
```python
import requests
metadata = oauth.kenni.load_server_metadata()
res = requests.post(
metadata["token_endpoint"],
data={"grant_type": "client_credentials", "scope": API_SCOPE},
auth=(os.environ["KENNI_CLIENT_ID"], os.environ["KENNI_CLIENT_SECRET"]),
)
access_token = res.json()["access_token"]
```
For credentials with special characters, the form-urlencoded Basic auth from [RFC 6749 §2.3.1](https://datatracker.ietf.org/doc/html/rfc6749#section-2.3.1) requires `base64(quote(id) + ":" + quote(secret))` rather than `requests`' default `auth=` tuple. Build the `Authorization: Basic …` header by hand if you suspect special characters in your secret.
## Refresh
```python
new_token = oauth.kenni.fetch_access_token(
grant_type="refresh_token",
refresh_token=session["refresh_token"],
)
session["access_token"] = new_token["access_token"]
session["refresh_token"] = new_token.get("refresh_token", session["refresh_token"])
```
`fetch_access_token` does _not_ mutate the session — write the new token back yourself.
## FastAPI / Starlette
Authlib has a Starlette integration that drops straight into FastAPI:
```python
from authlib.integrations.starlette_client import OAuth
from fastapi import FastAPI, Request
from starlette.responses import RedirectResponse
app = FastAPI()
oauth = OAuth()
oauth.register(name="kenni", server_metadata_url="...", client_kwargs={...})
@app.get("/login")
async def login(request: Request):
return await oauth.kenni.authorize_redirect(request, request.url_for("callback"))
@app.get("/callback")
async def callback(request: Request):
token = await oauth.kenni.authorize_access_token(request)
request.session["userinfo"] = dict(token.get("userinfo") or {})
request.session["id_token"] = token["id_token"]
return RedirectResponse("/")
```
The route bodies are otherwise identical — just `async`, with `request.session` instead of Flask's global `session`, and `RedirectResponse` instead of `redirect()`.
## Public clients
For SPA or Native flows, omit `client_secret`. Authlib uses PKCE (already enabled via `code_challenge_method`) as the proof on the token request. PKCE is also recommended for confidential clients — defence in depth against authorization-code interception.
## Sign out
`session.clear()` kills your tokens but leaves the Kenni session alive — the next sign-in silently re-authenticates. Read `end_session_endpoint` from the cached discovery metadata and redirect through it. The `id_token` was saved in the callback above.
```python
from urllib.parse import urlencode
@app.route("/logout")
def logout():
id_token = session.get("id_token")
metadata = oauth.kenni.load_server_metadata()
end_session = metadata["end_session_endpoint"]
session.clear()
params = urlencode({
"id_token_hint": id_token,
"post_logout_redirect_uri": url_for("index", _external=True),
"client_id": os.environ["KENNI_CLIENT_ID"],
})
return redirect(f"{end_session}?{params}")
```
Register the resolved post-logout URL on the application's **Post logout redirect URIs** list in the [developer portal](https://developers.kenni.is). See the [No framework (curl) guide](https://developers.kenni.is/docs/guides/curl#sign-out) for the full reasoning.
`oauth.kenni.load_server_metadata()` returns the cached discovery doc — use it to read any field (`token_endpoint`, `jwks_uri`, `end_session_endpoint`, etc.) without a re-fetch.
---
# Other frameworks
Kenni implements OpenID Connect to spec, so any conformant client library can talk to it. The integration is the same in every language: discover the endpoints, configure your client with your credentials, request the scopes you need.
## What every library needs
Three values, plus a redirect URI registered on your application in the [developer portal](https://developers.kenni.is):
- **Issuer URL** — `https://idp.kenni.is/`. Most libraries take this and discover everything else from `/.well-known/openid-configuration`.
- **Client ID** — shown on the application's Overview tab, e.g. `@/web`.
- **Client secret** — only for confidential clients (Web, M2M). Public clients (SPA, Native, Device) authenticate via PKCE.
## Library suggestions
| Language | Library | Notes |
| -------- | --------------------------------------------------------------------------------- | ---------------------------------------- |
| Ruby | [`omniauth_openid_connect`](https://github.com/omniauth/omniauth_openid_connect) | Plug into Rails via Omniauth. |
| PHP | [`jumbojett/openid-connect-php`](https://github.com/jumbojett/OpenID-Connect-PHP) | Single-file dependency, easy to drop in. |
| Rust | [`openidconnect`](https://crates.io/crates/openidconnect) | Async, JWT validation, PKCE. |
| Elixir | [`oidcc`](https://github.com/erlef/oidcc) | OpenID Foundation–certified. |
If your language has a dedicated guide in this section, prefer that. Otherwise, anything compliant with [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html) and PKCE will work.
## Things to get right
- **PKCE is required for public clients.** SPA, Native, and Device application types must use PKCE on the authorization request and code exchange. Most modern libraries do this by default.
- **Validate the ID token.** Verify the signature against the JWKS from discovery, the `iss` against your issuer, the `aud` against your client ID, and the `nonce` if you sent one.
- **Honour `state`.** Always send a random `state` and reject the callback if the value doesn't match.
## When in doubt
The [No framework (curl)](https://developers.kenni.is/docs/guides/curl) guide shows the wire-level requests every library is wrapping. If your library is misbehaving, run the equivalent `curl` command and compare — that usually pinpoints which parameter is wrong.
---
# 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](https://developers.kenni.is/docs/api-scopes); the per-scope reference table lives on [Standard scopes](https://developers.kenni.is/docs/api-scopes/standard).
## 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](https://idp.kenni.is//oidc/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](https://developers.kenni.is/docs/features/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:
```jsonc
// ID token for an employee acting as their company
{
"sub": "",
"national_id": "",
"company_name": "Example ehf.",
"actor": {
"sub": "",
"national_id": "",
"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.
## Auto-consent vs. requires-consent
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](https://developers.kenni.is/docs/features/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.
---
# Prompts
The OIDC `prompt` parameter controls which interactions Kenni shows the user before completing the authorization request. The same application can drive completely different sign-in flows — fresh login, delegation picker, custom-delegation admin, passkey enrollment — by varying `prompt` per request.
Pass it as a space-separated list on the authorization endpoint:
```
GET /oidc/auth?prompt=login%20delegation&scope=openid%20display_name&...
```
Kenni evaluates the prompts in policy order (regardless of how you ordered them in the query string), shows each screen as it becomes due, and finishes by redirecting to your `redirect_uri` once every prompt has been resolved.
## Standard prompts
These come from the [OIDC spec](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest).
| Prompt | Effect |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `none` | Never show UI. If a valid session exists the request completes silently; otherwise it fails with `login_required`. Use this to probe for an active SSO session without disturbing the user. |
| `login` | Force a fresh authentication even when [SSO](https://developers.kenni.is/docs/features/single-sign-on) would otherwise let the user through silently. Useful right after a local logout to make "Sign out" feel real. |
| `consent` | Re-display the [consent](https://developers.kenni.is/docs/features/consent) screen for the requested scopes, even if the user has already granted them on a previous visit. Useful when you need an explicit re-confirmation. |
`select_account` is not supported — Kenni only ever has one signed-in account per browser.
## Kenni-specific prompts
Three prompts are Kenni extensions. They're **requestable**: they only run when explicitly named on the request, so an application can choose between "sign in as self" and "sign in as a company" by toggling `prompt=delegation`.
### `delegation`
Shows the delegation picker. The user picks the company or custom delegation they want to act for, and the resulting token has the delegation as the subject with the actor's identity nested under `actor.*`.
```
GET /oidc/auth?prompt=delegation&scope=openid%20company_name&...
```
Both [company delegations](https://developers.kenni.is/docs/features/company-delegations) and [custom delegations](https://developers.kenni.is/docs/features/custom-delegations) appear in the picker — Kenni filters to the types the application has allowed.
> **Note.** Requires [company delegations](https://developers.kenni.is/docs/features/company-delegations) or [custom delegations](https://developers.kenni.is/docs/features/custom-delegations) to be enabled on your team's plan. Without either, the request fails.
### `delegation_admin`
Shows the custom-delegation admin screen — Kenni's "manage delegates" UI for the application's [custom delegation types](https://developers.kenni.is/docs/features/custom-delegations). The user adds or removes other people as delegates of the types your team defined.
```
GET /oidc/auth?prompt=delegation_admin&...
```
Typically wired to a "Manage access" button in your application's settings.
> **Note.** Requires [custom delegations](https://developers.kenni.is/docs/features/custom-delegations) to be enabled on your team's plan.
### `credential`
Opens Kenni's passkey-management screen for the signed-in user. From here the user can enroll a new passkey and view or delete existing ones — every passkey across every device they've registered against Kenni, in one place.
```
GET /oidc/auth?prompt=credential&...
```
Most applications never need to set this explicitly — Kenni offers passkey enrollment automatically after a successful login unless [skipping passkeys](https://developers.kenni.is/docs/features/skipping-passkeys) is enabled. The cases where `prompt=credential` is useful:
- **Self-service passkey management.** A "Manage your passkeys" link in your application's settings sends the user to Kenni to add a new device or remove an old one. Cleaner than building your own UI on top of the API.
- **Removing a credential the user no longer recognises.** If a user reports a lost device, a phone they no longer own, or a passkey they don't remember enrolling, point them at this screen so they can delete it themselves. Kenni revokes the credential immediately.
- **Testing your integration.** During development, deleting your test user's passkeys is the fastest way to drive the enrollment flow again on the next sign-in.
## Chaining prompts
`prompt` accepts multiple values. Kenni runs each prompt in policy order and only redirects back to your application once every screen has been resolved. The order is fixed — listing them in a different order in the query string doesn't change the order they appear in the UI.
| Combination | What the user sees |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `login delegation` | Authenticate, then pick a delegation. Skips SSO even if a session exists. |
| `login delegation delegation_admin` | Authenticate, pick a delegation, then land on the delegation admin screen for the resulting subject. |
| `delegation consent` | Pick a delegation, then re-confirm consent for the delegated scopes. |
| `delegation delegation_admin` | Pick a delegation, then manage delegates for the chosen subject — common pattern for "act as company, then admin". |
| `none` | Silent. Either completes immediately or fails with `login_required` / `consent_required` / `interaction_required`. |
Chaining is the right tool when one user action needs more than one screen — e.g. an admin who taps "Manage company access" should authenticate, pick the company, and land on the delegation admin in one continuous flow.
The [test app](https://github.com/kenni-is/kenni/tree/main/apps/test) ships a UI that lets you fire any of these combinations against a configured client. It's the fastest way to see how the chained flows feel.
## Per-call prompt in framework guides
Several frameworks make it tricky to vary `prompt` per click — the parameter has to be passed through the library to the authorization request:
- **[Next.js / better-auth](https://developers.kenni.is/docs/guides/better-auth)** — pass `additionalData: { prompt: "delegation" }` on `signIn.oauth2`, and read it back in `authorizationUrlParams`.
- **[Expo](https://developers.kenni.is/docs/guides/expo)** — `extraParams: { prompt: "login" }` on `useAuthRequest`.
- **[Flutter](https://developers.kenni.is/docs/guides/flutter)** — `promptValues: ['login']` on `AuthorizationTokenRequest`.
- **[Spring Boot](https://developers.kenni.is/docs/guides/spring-boot)** — pass `prompt` via `OAuth2AuthorizationRequestCustomizers`.
Where the library doesn't have an obvious slot for it, the simplest answer is to register the same client a second time with a different `providerId` and a static `prompt` configured — but the per-call pattern above is cleaner where it's available.
---
# Test users
Test users are team-scoped accounts that sign in with a national ID and a password instead of a real electronic ID. They make it possible to demo your application, run automated tests, and submit it for app store review without provisioning a real Audkenni identity for every reviewer.
> **Note.** Test users are a paid feature on a higher plan tier. [Get in touch](mailto:hello@kenni.is) and we'll talk you through pricing and enable it for your team.
## When to use them
- **App store review.** Apple and Google reviewers need credentials that work outside Iceland. A test user gets them through the login.
- **Foreign contractors and stakeholders** who don't hold an Icelandic electronic ID but need to use your application.
- **End-to-end tests** that need predictable, repeatable identities and full control over name, email, and delegation context.
Test users are not real Audkenni identities — the resulting tokens carry the test user's national ID and profile, but the `audkenni_*` claims describe the test user, not a vetted citizen.
## Plan and application setup
Test users are gated at two levels:
1. **Plan tier.** Your team's plan must support test users. If it doesn't, the **Test users** tab in team settings shows an upgrade prompt instead of the user list.
2. **Per application.** Each application that should accept test-user logins must have **Test user access** enabled in its application settings. An application without it rejects every test-user session.
The two-level gate is intentional: you can have test users on the team without exposing them on a production-facing application.
> **Warning.** A test-user [SSO](https://developers.kenni.is/docs/features/single-sign-on) session never carries over to an application that doesn't have test user access enabled — Kenni forces a fresh login. This prevents test identities from leaking into production clients.
## Creating a test user
Open **Settings → Test users** in the [developer portal](https://developers.kenni.is) and click **Add user**. Each test user needs:
- **Name** — the value released by the `audkenni_name` and `name` scopes.
- **Password** — required at sign-in; only shown to the user who creates the test user. Cannot be recovered, only reset.
- **National ID** — does not need to match a real kennitala. Kenni prepends `00` automatically so test national IDs cannot collide with real ones.
- **Email** (optional) — released as `email`, automatically marked as verified.
- **Phone number** (optional) — released as `phone_number`.
- **Mock companies** — any of Kenni's built-in test companies the user can delegate to. Useful for exercising the [Company delegations](https://developers.kenni.is/docs/features/company-delegations) flow without real registry data.
Test users are visible to everyone on the team and can be edited or deleted at any time.
## Signing in as a test user
On the Kenni login screen, choose **Auðkenni app** as the authentication method and enter the test user's national ID, including the leading `00`. Click **Continue**, then enter the password on the next screen. From there the flow proceeds exactly like a real Audkenni login — including delegation prompts, consent prompts, and any other interactions the application has configured.
---
# Single sign-on
Single sign-on (SSO) lets a user authenticate once and then sign into every other application on your team without re-entering credentials. Kenni keeps a session at the IdP, and any subsequent authorization request that arrives while the session is alive completes silently.
SSO is a team-wide setting — when enabled, it applies to every application owned by the team.
> **Note.** SSO is a paid feature on a higher plan tier. [Get in touch](mailto:hello@kenni.is) and we'll talk you through pricing and enable it for your team.
## Plan and team setup
SSO is gated by your plan tier. If your team's plan supports it, configure SSO from **Settings → Team settings** in the [developer portal](https://developers.kenni.is):
- **Enable SSO** — turns the feature on for the team.
- **Session TTL (seconds)** — how long the IdP session stays valid before the user is asked to authenticate again. Minimum 60 seconds, maximum 30 days. Default 30 days.
The TTL counts from the last authentication, not the last activity. Each fresh login resets the clock.
## How it behaves
With SSO enabled, an authorization request that arrives while a Kenni session is active skips the credential prompt entirely. The user lands directly on:
- the consent screen, if [consent](https://developers.kenni.is/docs/features/consent) is enabled and there are unconsented scopes,
- the delegation picker, if `prompt=delegation` is on the request,
- the delegation admin, if `prompt=delegation_admin` is on the request,
- otherwise, your `redirect_uri` with a fresh authorization code.
Without SSO, every authorization request requires a fresh authentication, even if the user just signed in to a sibling application a minute ago.
> **Note.** The user only sees one Kenni session per browser. Signing in to one team-owned application is enough to skip the credential prompt on every other team-owned application that accepts the same session.
## Ending the session
Closing the application or clearing its cookies does **not** end the Kenni session. To sign the user out everywhere on the team, your application must perform an [RP-initiated logout](https://openid.net/specs/openid-connect-rpinitiated-1_0.html) by redirecting to the IdP's `end_session_endpoint` (available from the discovery document).
A typical logout flow:
1. Application clears its own session.
2. Application redirects to `https://idp.kenni.is//oidc/session/end?id_token_hint=&post_logout_redirect_uri=`.
3. Kenni clears the IdP session and redirects back.
If you skip step 2, the user remains signed into Kenni and the next authorization request completes silently — usually not what the user expects after clicking "Sign out".
## Test users and SSO
A [test-user](https://developers.kenni.is/docs/features/test-users) session never carries over via SSO to an application that doesn't have **Test user access** enabled. Kenni detects the mismatch and forces a fresh login on the receiving application, even if the test-user session is otherwise valid. This prevents test identities from leaking into production clients while keeping SSO useful inside development teams.
---
# Company delegations
A company delegation lets an authenticated person sign into your application as a legal entity they have authority over. The user authenticates as themselves, picks the company they want to act for, and your application receives a token whose subject is the company — with the actor's identity nested under `actor.*`.
The list of who can act for which company is sourced from the Icelandic company registry. Kenni surfaces these relationships during login; your application doesn't have to model them.
> **Note.** Company delegations are a paid feature on a higher plan tier. [Get in touch](mailto:hello@kenni.is) and we'll talk you through pricing and enable it for your team.
## Plan setup
Company delegations are gated by your plan tier. When supported, the **Delegations** tab on each application in the [developer portal](https://developers.kenni.is) lets you configure which delegation types are accepted.
## Delegation types
The company registry tracks several kinds of authority a person can hold over a company. Kenni exposes them as named delegation types:
| Common types | |
| -------------- | ----------------------- |
| `c:procurator` | Procurator |
| `c:ceo` | Chief Executive Officer |
| `c:board` | Board member |
| `c:auditor` | Auditor |
| Uncommon types | |
| ------------------ | -------------- |
| `c:owner` | Owner |
| `c:founder` | Founder |
| `c:agent` | Agent |
| `c:branch-manager` | Branch manager |
| `c:vice-board` | Vice board |
Pick the types your application is willing to accept on the application's **Delegations** tab. A user who only holds excluded types won't see the company in the delegation picker.
The uncommon types are kept behind a collapsible because the company registry rarely populates them — most users will only ever appear as procurators, CEOs, or board members.
## Self-delegation
The same tab has a **Support self-delegation** toggle. When on, the delegation picker offers "Sign in as yourself" alongside the list of companies. When off, the user must choose a company to proceed — useful for back-office tools that are only meant for company use.
If the user holds no company delegations and self-delegation is off, the authorization request fails with `access_denied`.
## Triggering the delegation prompt
The delegation picker is **requestable** — it only appears when the authorization request includes `prompt=delegation`:
```
GET /oidc/auth?prompt=delegation&scope=openid%20company_name&...
```
Without the prompt, the user signs in as themselves and the delegation picker is skipped entirely. This means the same application can support both self-login and company-delegated login depending on the request — typically a "Sign in as company" button that adds `prompt=delegation` to the request.
## Claims released for a delegated session
In a delegated session, two identities are present:
- **The subject** (root claims) — the company. Kenni releases the `company_*` scopes here: `company_name` from the registry (auto-consent), and `company_display_name`, `company_email`, `company_phone_number`, `company_logo` from the team's profile (require [consent](https://developers.kenni.is/docs/features/consent)).
- **The actor** (`actor.*` claims) — the person signed in. Released by the `actor_*` scope family: `actor_audkenni_name`, `actor_audkenni_phone_number`, `actor_national_id` (auto-consent), and `actor_display_name`, `actor_picture`, `actor_phone_number`, `actor_email` (require consent).
The full claim shape is documented on [Scopes and claims](https://developers.kenni.is/docs/features/scopes-and-claims). The per-scope reference table is on [Standard scopes](https://developers.kenni.is/docs/api-scopes/standard).
A `delegation_type` claim is always included in a delegated session — an array listing the delegation types the actor holds for this subject. Useful for authorization decisions on your side: e.g. only accept `c:procurator` or `c:ceo` for high-impact actions.
---
# Custom delegations
Where [company delegations](https://developers.kenni.is/docs/features/company-delegations) come from the national company registry, **custom delegations** are types your team defines for itself. They let users grant other users application-specific authority — "Finance Portal Access", "Server Admin", "School Guardian" — without those relationships needing to exist anywhere outside Kenni.
A custom delegation is a Kenni-managed grant from one person to another (or to themselves), scoped to your team. The grant can be created either inside your application (via the delegation admin prompt) or out-of-band by an administrator, and it stays valid until it expires or is revoked.
> **Note.** Custom delegations are a paid feature on a higher plan tier. [Get in touch](mailto:hello@kenni.is) and we'll talk you through pricing and enable it for your team.
## Plan setup
Custom delegations are gated by your plan tier. When supported, the **Delegations** page in the [developer portal](https://developers.kenni.is) is where you define types and inspect existing grants.
## Defining a delegation type
A custom delegation type is just a named slot. Open **Delegations** and click **New delegation type**. Each type has:
- **Name** — alphanumerics, underscores, and dashes. Kenni prefixes the type with your team domain at runtime, so `finance-portal` becomes `@my-app.is:finance-portal` in the token.
- **Title (English / Icelandic)** — what the user sees in the delegation picker and on the delegation admin screen.
- **Description (English / Icelandic)** — explanation of what the type grants. Shown on the same screens.
- **Access control** — optional rules for who can grant the type to others (see below).
A new type is inert until at least one application is authorized to use it. Open the application's **Delegations** tab and tick the type to add it to **Allowed custom delegation types**.
## Granting a delegation
There are two ways an end user becomes a delegate:
1. **Through the developer portal.** A team administrator opens the type, picks delegate users, and saves. The grant takes effect immediately.
2. **Through your application.** Your application sends an authorization request with `prompt=delegation_admin`. Kenni shows the user a "manage delegates" UI where they can add or remove delegations themselves.
The second path is the typical pattern for self-service delegation: an admin signs in, hits a "Manage access" button in your UI, and Kenni handles the entire grant flow.
## Signing in as a delegate
Once a delegation exists, the delegate can authenticate against any application that has the type allowed. Add `prompt=delegation` to the authorization request:
```
GET /oidc/auth?prompt=delegation&scope=openid%20display_name&...
```
Kenni shows the delegation picker. The user picks the delegating account, and your application receives a token whose subject is the delegating account, with the actor's identity nested under `actor.*`. The `delegation_type` claim lists the custom types the actor holds for this subject (e.g. `["@my-app.is:finance-portal"]`).
The same `prompt=delegation` request handles both [company delegations](https://developers.kenni.is/docs/features/company-delegations) and custom delegations — the picker shows whatever's available to the user across both.
## Access control
Each type has two access-control fields that decide who can grant it:
- **Allow personal granting** (default on) — when on, any user managing their own delegations can grant the type. Turn it off if the type should only flow through sub-delegation chains.
- **Required delegation types** (default empty) — when populated, the type is grantable through sub-delegation only when the actor holds at least one of the listed types. The relationship is **OR**: any one match unlocks granting.
The two fields combine to model real authority chains. Example:
> "Finance Portal Access" should only be granted by a procurator or CEO of the company.
- Personal granting: **off**.
- Required delegation types: `c:procurator`, `c:ceo`.
A regular employee opening the delegation admin sees no grantable types and gets `access_denied`. A procurator opening the same screen, while signed in on behalf of the company, can grant "Finance Portal Access" to others.
Including a custom type in its own required list is also valid — it means "holders of this type can grant it to sub-delegates", which is how multi-level chains are built.
## Expiry and revocation
Each individual grant has an expiry date (default: one year from creation). Grants can be revoked at any time from the delegation admin or the developer portal. Revoking is immediate — the next authorization request from the affected actor will no longer offer the delegation.
---
# Consent
Some identity scopes — `display_name`, `email`, the editable `phone_number`, the user's `picture` — release information the user has chosen to share with Kenni. Before your application can receive those claims, the user has to agree to share them with you specifically. The consent screen is where that agreement happens.
Auto-consent scopes (`openid`, `national_id`, `audkenni_name`, …) skip the consent screen entirely; their claims release the moment the user authenticates. The full split is on [Scopes and claims](https://developers.kenni.is/docs/features/scopes-and-claims).
> **Note.** Consent is a paid feature on a higher plan tier. [Get in touch](mailto:hello@kenni.is) and we'll talk you through pricing and enable it for your team.
## Plan and application setup
Consent is gated at two levels:
1. **Plan tier.** Your team's plan must support consent. If it doesn't, the **Consent** tab on each application is hidden and the API rejects attempts to enable it.
2. **Per application.** Each application that needs consent has to opt in. Open the application's **Consent** tab in the [developer portal](https://developers.kenni.is) and tick **Enable consent**.
When consent is off on an application, requesting a non-auto-consent scope is a silent no-op — the request still succeeds, but the claim is not released and the user is never prompted.
## Required scopes
The same **Consent** tab has a **Required scopes** list. Tick the scopes whose absence should block sign-in entirely:
- A user who agrees to all required scopes proceeds normally.
- A user who declines a required scope is bounced back to your application with `access_denied` instead of completing the flow.
Use this for scopes your application genuinely cannot work without (e.g. `email` for an app that only uses email as the account identifier). Leave it empty for scopes that are nice-to-have — the user will still see them on the consent screen and can choose to share them, but declining won't break the flow.
## What the user sees
On first sign-in to an application with consent enabled, Kenni shows a screen listing every non-auto-consent scope the application is requesting, with the human-readable description for each. The user can:
- Approve everything (the default action).
- Decline individual optional scopes — those claims are not released, but the flow continues.
- Decline a required scope — the flow aborts with `access_denied`.
Kenni remembers the decision per application. The next time the user signs in to the same application, the consent screen is skipped unless your application requests a scope they haven't seen before. If you start asking for a new scope, every previously-consented user gets re-prompted only for the new one.
## Subject-type filtering
The consent screen is aware of who the user is signing in as. A request that includes both `email` (individual) and `company_email` (company) only shows the relevant scope:
- For an individual sign-in: only `email` appears.
- For a company-delegated sign-in: only `company_email` appears.
The same scope list can therefore be reused for both flows without your application having to special-case.
## Delegated sessions and consent
Consent in a delegated session is given **as the delegate**. The actor sees the consent screen for the scopes being released about themselves (the `actor_*` family) and about the subject they're acting for (`company_*`, the subject's identity scopes, …). Kenni records the consent against the actor's account so the next time they sign in for the same subject the screen is skipped.
If a different actor signs in for the same subject, they go through consent themselves — one user's consent doesn't grant on behalf of another.
---
# Skipping passkeys
After a successful first authentication, Kenni asks the user whether they'd like to register a passkey for faster future sign-ins. The prompt is great for consumer applications where the same user signs in repeatedly from the same device — but it's noise for kiosk-style flows, app store reviewers, one-off enrollments, and back-office tools where every session uses a fresh credential anyway.
The **Skip passkey prompt** setting hides that screen for a specific application.
> **Note.** Skipping passkeys is a paid feature on a higher plan tier. [Get in touch](mailto:hello@kenni.is) and we'll talk you through pricing and enable it for your team.
## Plan and application setup
Skipping the passkey prompt is gated at two levels:
1. **Plan tier.** Your team's plan must support the feature. If it doesn't, the toggle isn't shown.
2. **Per application.** Each application opts in independently. Open the application's Settings tab in the [developer portal](https://developers.kenni.is) and tick **Skip passkey prompt**.
When enabled, every user signing into that application skips the passkey registration step and lands directly on the consent screen (if applicable) or your `redirect_uri`.
## What it changes
- **No registration prompt.** The "Register a passkey?" screen is suppressed for this application.
- **Existing passkeys still work.** Users who already have a passkey can continue to use it on the credential prompt — this setting only controls the _registration_ prompt, not the use of passkeys for authentication.
- **Other applications are unaffected.** A user who signs into an application with skipping enabled, then later signs into a different application without it, sees the registration prompt on that second application.
## Always-skipped: delegated authorizations
Independently of this setting, Kenni never asks for a passkey during a delegated sign-in (`prompt=delegation` or a session that resolved into a delegation). The actor in a delegation isn't the account the passkey would belong to, and registering one for the subject would let the actor return later and sign in as the subject without authorization. The passkey prompt is therefore skipped for every delegated flow regardless of how this setting is configured.
## When to enable it
- **Demo and review applications.** App store reviewers and demo users don't benefit from a passkey they'll never reuse.
- **Single-use kiosks** where the device isn't tied to one identity.
- **Back-office or admin tools** where users sign in rarely and the noise of being prompted every time isn't worth it.
For consumer-facing applications, leave it off — the passkey prompt is the fastest route to a low-friction return user.
---
# Device code flow
The Device Authorization Grant ([RFC 8628](https://datatracker.ietf.org/doc/html/rfc8628)) lets a device that can't easily host a browser — a smart TV, a CLI, a printer's setup screen — sign a user in via a second device. The constrained device displays a short code and a verification URL; the user opens that URL on their phone or laptop, signs in to Kenni, and the device polls the token endpoint until Kenni hands it tokens.
> **Note.** The device flow is a paid feature on a higher plan tier. [Get in touch](mailto:hello@kenni.is) and we'll talk you through pricing and enable it for your team.
## Setup
Create a **Device** application in the [developer portal](https://developers.kenni.is). Device applications:
- have no `client_secret` (they can't keep one),
- don't use redirect URIs — verification happens on a separate device,
- only support the `urn:ietf:params:oauth:grant-type:device_code` and `refresh_token` grants.
The application's Overview tab lists the device-authorization endpoint and the activation URL the user will visit.
## Endpoints
Two endpoints in addition to the standard token endpoint:
- **Device authorization** — `https://idp.kenni.is//oidc/device/auth`. The constrained device POSTs here to start the flow.
- **Activation page** — `https://idp.kenni.is/activate`. The user opens this on a second device and enters the `user_code`.
Both are advertised in the discovery document under `device_authorization_endpoint` and `device_verification_uri`.
## Flow
```mermaid
sequenceDiagram
participant Device as Device (TV, CLI, kiosk)
participant Kenni
participant Phone as User's phone
Device->>Kenni: 1. POST /oidc/device/auth
Kenni-->>Device: user_code, device_code, verification_uri, interval
Note over Device: 2. Display user_code + verification_uri
Phone->>Kenni: 3. Visit verification_uri, enter user_code, sign in
loop Every `interval` seconds
Device->>Kenni: 4. POST /oidc/token (grant_type=device_code)
Kenni-->>Device: authorization_pending (or slow_down, expired_token, ...)
end
Kenni-->>Device: 5. access_token, id_token, refresh_token
```
## 1. Start the flow
The device POSTs to `device_authorization_endpoint` with its `client_id` and the requested `scope`:
```bash
curl -s -X POST https://idp.kenni.is//oidc/device/auth \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'client_id=@/device' \
-d 'scope=openid offline_access' \
-d 'ui_locales=en'
```
Response:
```json
{
"device_code": "xN7pJ...long-opaque-string",
"user_code": "ABCD-EFGH",
"verification_uri": "https://idp.kenni.is/activate",
"verification_uri_complete": "https://idp.kenni.is/activate?user_code=ABCD-EFGH",
"expires_in": 600,
"interval": 5
}
```
- `user_code` — the short code the user types on the activation page.
- `device_code` — the opaque token the device polls with. Treat as a secret while the flow is active.
- `verification_uri_complete` — the URL with the code prefilled. Render it as a QR code if you can; the user scans it instead of typing.
- `expires_in` — total flow lifetime in seconds. Defaults to 10 minutes.
- `interval` — minimum poll cadence in seconds.
## 2. Show the user where to go
Display `user_code` and `verification_uri` (or a QR code linking to `verification_uri_complete`). The user opens it on a phone or laptop and signs in to Kenni — the same login UI as a normal authorization request, including any [delegation](https://developers.kenni.is/docs/features/company-delegations) or [consent](https://developers.kenni.is/docs/features/consent) screens that apply.
## 3. Poll for the token
While the user is finishing on the second device, the constrained device polls the token endpoint at `interval` seconds:
```bash
curl -s -X POST https://idp.kenni.is//oidc/token \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=urn:ietf:params:oauth:grant-type:device_code' \
-d 'device_code=xN7pJ...' \
-d 'client_id=@/device'
```
Polling responses follow [RFC 8628 §3.5](https://datatracker.ietf.org/doc/html/rfc8628#section-3.5):
| HTTP status | `error` | What to do |
| ----------- | ----------------------- | --------------------------------------------------------- |
| 400 | `authorization_pending` | User hasn't approved yet. Wait `interval` and poll again. |
| 400 | `slow_down` | You're polling too fast. Increase `interval` by 5s. |
| 400 | `expired_token` | The 10-minute window elapsed. Start over from step 1. |
| 400 | `access_denied` | The user declined. Don't poll again. |
| 200 | _none_ | You have `access_token`, `id_token`, and `refresh_token`. |
Refresh tokens are issued automatically for device clients — the `offline_access` scope is implied — so the device can stay signed in across reboots without making the user repeat the activation step.
## Reference implementation
The [test app](https://github.com/kenni-is/kenni/tree/main/apps/test) includes a working device-code flow you can drive from a UI:
- `apps/test/src/app/api/device-code/route.ts` — starts the flow.
- `apps/test/src/app/api/device-code/poll/route.ts` — polls the token endpoint with the returned `device_code`.
Both are short enough to copy into your own service as-is.
---
# Common issues
This page covers the errors you're most likely to hit while integrating Kenni and how to fix them. If you've worked through it and you're still stuck, [email us](mailto:hello@kenni.is) — include the `client_id`, the time of the failure, and the full request URL or response body if you have it.
## Authorization errors
These errors come back as a redirect to your `redirect_uri` with `error=...&error_description=...` in the query string.
### `redirect_uri did not match any registered redirect_uri`
The `redirect_uri` on the authorization request is not on the application's allow-list.
- Check **Settings → Redirect URIs** for the application. Every URI is exact-match — `https://app.example.is/callback` does **not** cover `https://app.example.is/callback/`.
- Local development typically uses `http://localhost:/callback`. Add the exact port your dev server runs on.
- For native and Expo apps, the URI is usually a custom scheme (`com.example.app:/callback`). Match it down to the casing.
### `access_denied — Consent not enabled for this client`
The application is requesting a scope that requires consent (`display_name`, `email`, `picture`, `phone_number`, …) but consent is not enabled on the application.
- Open the application's **Consent** tab and tick **Enable consent**, then add the scopes the user must agree to.
- If your plan doesn't support consent yet, the tab is hidden — see [Consent](https://developers.kenni.is/docs/features/consent).
### `access_denied — Delegation not supported`
The authorization request includes `prompt=delegation` or `prompt=delegation_admin`, but the application's plan tier doesn't support either company or custom delegations.
- Confirm your plan tier supports delegations. See [Company delegations](https://developers.kenni.is/docs/features/company-delegations) and [Custom delegations](https://developers.kenni.is/docs/features/custom-delegations).
- If you didn't intend to ask for delegation, drop the `prompt` parameter from the authorization request.
### `access_denied — Self delegation is disabled and no delegates found for this user`
The user has no company or custom delegations, and **Support self-delegation** is off on the application.
- Either turn on **Support self-delegation** in the application's **Delegations** tab so users without delegations can sign in as themselves, or
- Make sure the user has been granted the relevant company or custom delegations before they try to sign in.
### `access_denied — Delegate does not have permission to manage delegations`
A `prompt=delegation_admin` request reached a user who has no grantable delegation types in the current context.
- For personal grants, the user needs at least one custom delegation type whose **Allow personal granting** is on.
- For sub-delegation, the actor must hold at least one type listed in the target type's **Required delegation types**. See [Custom delegations → Access control](https://developers.kenni.is/docs/features/custom-delegations).
### `access_denied — End-User aborted interaction`
The user clicked the back button or closed the login screen. Not a configuration issue — handle it in your application by showing a friendly "Sign-in cancelled" message.
### `invalid_scope`
The authorization request includes a scope the application is not authorized to use.
- Custom API scopes must be enabled on the application's **API Scopes** tab before they can be requested.
- Identity scopes that require consent only resolve when consent is enabled (see above).
- Scopes are case-sensitive: `Email` and `email` are different scopes, and the second one is the right one.
## Token endpoint errors
These come back as `4xx` responses from `POST /oidc/token` with a JSON body.
### `invalid_client`
Your `client_id` or `client_secret` didn't match Kenni's records.
- Confirm the `client_id` matches what the developer portal shows for the application — the runtime form is `@team-domain/short-name`.
- For confidential clients, confirm the secret. If you've lost it, **rotate** it from the application's Settings tab — there's no way to recover the original.
- Authentication method matters. Web and M2M clients default to `client_secret_basic` (HTTP Basic Auth) or `client_secret_post` (form body). Check what your library is sending.
### `invalid_grant`
The most common culprits, in order:
- **Authorization code reuse.** Codes are single-use and short-lived. If your library is retrying token requests, make sure it's caching the response — not re-submitting the code.
- **PKCE mismatch.** The `code_verifier` on the token request must hash to the `code_challenge` sent on the authorization request. The most common cause is reusing a stale verifier on a retry.
- **Refresh token expired or revoked.** Refresh tokens have a TTL set on the application's Settings tab. Once expired, the user has to sign in again.
- **`redirect_uri` mismatch on the token request.** The `redirect_uri` you send to `/oidc/token` must be byte-identical to the one you sent to `/oidc/auth`.
### Refresh tokens are not issued for M2M
Machine-to-Machine clients use the `client_credentials` grant, which doesn't issue refresh tokens. If you need a fresh token, just call the token endpoint again with your credentials.
## ID token / JWT validation failures
### Signature does not validate
- Fetch the signing keys from `https://idp.kenni.is//oidc/jwks` and cache them with respect for `Cache-Control` — Kenni rotates keys periodically.
- Don't pin keys by `kid`. When a key rotates, refetch JWKS and try again before failing.
### `iss` mismatch
The `iss` claim is `https://idp.kenni.is/`, including the team domain. A mismatch usually means your validator is configured with the wrong issuer URL — make sure it includes the path.
### `aud` mismatch
For ID tokens, `aud` is your `client_id`. For JWT access tokens, `aud` is your team's resource indicator. Configure your validator with the right value for whichever token you're checking.
### Clock skew
If validation passes everywhere except `exp` or `iat`, your server's clock is probably off. Most JWT libraries accept a `clockTolerance` option (typically 30–60 seconds) — set it.
## Scopes are silently dropped from tokens
If you request a scope and the corresponding claim doesn't show up in the ID token or user-info response, work through the list:
1. **The application isn't authorized for the scope.** Custom API scopes must be enabled on the application's API Scopes tab. Identity scopes that require consent need consent enabled.
2. **The scope's subject type doesn't match.** `company_*` scopes only release for company subjects; `display_name`/`email`/etc. only release for individual subjects. See [Scopes and claims → Subject types](https://developers.kenni.is/docs/features/scopes-and-claims).
3. **The user declined the scope on the consent screen.** They can come back and consent later — the next time they hit the consent screen for that application, the previously-declined scopes are listed again.
4. **The user has no value for the claim.** Editable claims (`display_name`, `email`, `picture`, …) only release if the user has set them.
The authorization request itself does not fail when a scope is unsupported — Kenni issues the token with whatever it can release. Always check the actual claims in the response, not just the scopes you asked for.
## Discovery and CORS
### `/.well-known/openid-configuration` returns 404
The discovery URL is `https://idp.kenni.is//.well-known/openid-configuration`. The team domain is the value you set when creating the team — visible at the top of the developer portal.
### CORS errors from a browser app
Kenni's token, user-info, and JWKS endpoints are CORS-enabled for SPA clients. If you're getting a CORS error:
- Confirm your application type is **Web (SPA)**, not **Web**. Server-rendered Web clients don't need CORS, but they also don't get it.
- Confirm the request is going to `https://idp.kenni.is`, not a different host. Mixing in a proxy in front of Kenni typically requires you to forward the relevant headers yourself.
## Session expired during sign-in
If the user pauses too long mid-login (e.g. on the consent or delegation screen), Kenni's interaction session times out and the next click renders a **session expired** page with a button back to your application.
This is expected — there's no value in keeping login interactions alive forever. If your users are running into it routinely, it's usually because something else (an external authenticator app, a slow network, a sleep/wake cycle on mobile) is stalling the flow. The right fix is a fresh authorization request, not a longer session.
## Still stuck?
[Email us](mailto:hello@kenni.is) with as much of the following as you can:
- The `client_id` of the application.
- The exact time of the failure (with timezone).
- The full request URL or the response body of the failing request.
- A brief description of what you expected to happen vs. what happened.
The more concrete the detail, the faster we can find it on our side.