Dialog Tokens

Reference information about dialog tokens

Introduction

See getting started with dialog tokens for a functional overview of dialog tokens and what they can be used for.

Dialog tokens allows for unproxied frontend requests to endpoints requiring authentication and authorization, without having to rely on ID-porten SSO and redirects.

Usage for end-user systems (OAuth clients)

Dialog tokens are embedded within the single-dialog response model (see dialogToken), and are self-contained, signed JWTs containing claims from the authenticated user and the dialog itself, including which actions and authorization attributes the user is authorized for.

Dialog tokens should be transferred as-is as bearer tokens in an Authorization HTTP header. The contents of the dialog token should normally not be inspected by clients, i.e., the token should be treated as an opaque string.

The altinn.no portal uses dialog tokens on all URLs associated with write actions and front channel embeds. Other end-user systems might also use dialog tokens for API actions, subject to service-specific protocols defined by the respective service owner.

Dialog token lifetime

A fresh dialog token is issued for each fetch of the dialog aggregate. The lifetime (exp claim) is 10 minutes, so end-user systems should refetch the dialog to ensure that the endpoints accept the token, and that it matches current authorization data.

Receving and verifying dialog tokens (OAuth resource servers)

With the help of dialog tokens, the resource server will be able to fully authenticate and authorize requests that are otherwise unauthenticated, i.e., without cookies or any other state. Dialog tokens should be transferred as bearer tokens using an Authorization HTTP header.

Note that for browser-based clients, including the Altinn.no portal, the resource server must also implement the CORS protocol in order to handle requests.

List of Dialogporten specific claims

Example of decoded token

{
  "alg": "EdDSA",
  "typ": "JWT",
  "kid" : "dp-2023-01" 
}
// .
{
  "c": "urn:altinn:person:identifier-no:12018212345", 
  "l": 4,  
  "u": "urn:altinn:organization:identifier-no:825827991",
  "p": "urn:altinn:organization:identifier-no:991825827", 
  "i": "e0300961-85fb-4ef2-abff-681d77f9960e",
  "s": "urn:altinn:resource:super-simple-service",
  "a": "read;write;sign;elementread,urn:altinn:subresource:autorisasjonsattributt1",
  "exp": 1672772834,
  "iss": "https://dialogporten.no",
  "nbf": 1672771934,
  "iat": 1672771934 
}
 
// .
// <signature>

Token signature cipher

Dialog tokens use an Edwards-Curve Digital Signature Algorithm (EdDSA) with the Ed25519 curve to sign dialog tokens, making it possible for consumers to verify that the token has been issued by Dialogporten and trust the information in the claims. Also see RFC 8037 for information about using EdDSA in JOSE contexts.

Well-known endpoints

Dialogporten provides OAuth 2.0 Authorization Server Metadata (RFC8414) allowing for runtime key discovery, rotation and token validation. Consult the OpenAPI specification (tag “Metadata”) for the well-known URLs for the given environment.

Key sets and rotations

The JSON Web Key sets published on the well-known endpoints will always contain at least two JWKs. All endpoints that accept and verify dialog tokens issued by Dialogporten should allow tokens signed by any of the keys present in the key set for the given environment.

The key set should be cached and refreshed with a frequency no more than 24 hours. Dialogporten may at any point introduce new keys into the key set, but will not sign any dialog tokens until the key has been published and available at the well-known endpoint for at least 48 hours. This will allow for consumers to refresh their caches and verify the signature of any token issued by Dialogporten.

Token validation recommendations

Please consult RFC 8725 and the aforementioned RFCs for information about best practices for JWS signature validation.