Transaction token

Introduction

The transaction token will be available as a sealed (signed by a Nets MitID Broker OCES3 organization certificate) record of the end-user completed transaction.

The transaction token response is self-contained and cryptographically sealed record suitable for long-term storage and as a proof-of-transaction.

The transaction token includes the relevant authentication information, a unique transaction identifier as well as relevant transaction specific information like end-user approved text linked to the transaction.

Transaction token

The transaction token will contain additional claims based on the end-user identity provider and provided identity provider parameters. These additional claims are explained under the specific identity provider in this document.

Transaction tokens are meant as a receipt for the completed end-user transaction. The token is signed by a special signing key and formatted to support long-term verification of the end-user transaction.

Many of the issued claims, are the same as found in the accompanied ID token.

In this section all the claims that are always present in transaction tokens are specified. In addition, each identity provider will have its own set of claims that can be included depending the context.

Transaction tokens will be set in the Token endpoint response, if configured for the client and if requested using the trans_token scope.

An accompanying OCSP revocation check response for the signing certificate, will be set in the Token endpoint response, formatted as a UTF-8+Base64 encoded string. The signing_cert_ocsp_nonce claim set in the transaction token is the nonce used for the OCSP response.

Token endpoint response:

{
  "id_token": "AGGSSDDhY3Rpb…AFGGRh",
  …,
  "transaction_token": "VHJhbnNhY3Rpb…BEYXRh",
  "transaction_token_ocsp_resp": "VHJhbnNhY3Rpb2…UZXN0IERhdGE="
}

Transaction tokens issued always include the following claims:

Claim

Value

iss

Identifier for the issuer as an URL using https scheme.

sub

NMB specific UUID representing the authenticated end-user.

Primary end-user identifier.

iat

Time at which the JWT was issued. Its value is a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time.

auth_time

Time when the end-user authentication occurred.

Its value is a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time.

nonce

String value used to associate a client session with a transaction token, and to mitigate replay attacks. The value is passed through unmodified from the authentication request to the transaction token.

This is the same nonce as set in the ID token.

signing_cert_ocsp_nonce

Nonce for signing certificate OCSP revocation status check.

UTF-8+Base64 encoded string.

Nonce used for checking OCSP revocation status for the transaction token signing certificate after the token has been signed.

amr

Authentication method reference

acr

Authentication Context Class Reference.

Represents the Authenticated Level of Assurance (LoA). The [NSIS] framework forms the basis for how NMB handles LoA for authentications, but the available acr values are not restricted to the values specified in [NSIS].

Refer to the specific identity providers for a list of possible acr values.

ial

Identity Assurance Level

Strength of the Identity registration process.

Identity Assurance Level can be higher than the acr/LoA value, as the identity can be enrolled/registered at a higher level, than the achieved authentication level for a specific session.

If the ial is not known, this value is not set.

idp

Identity provider who issued the underlying identity.

Refer to the specific identity providers for a list of possible idp values.

identitytype

One of

  • private
  • professional
  • test

transaction_id

Transaction ID.

Unique identifier for the completed (end-user) transaction. Distinct identifiers are used to identity different transactions completed at NMB.

recipient_info

Type: JSON.

The top-level members of the recipient_info JSON object are:

  • organization.number
  • organization.name
  • organization.country
  • redirect_uri: The URL that the end-user is redirect to from NMB upon successful completing the transaction.

The recipient_info parameter value is represented as UTF-8 encoded JSON.

spec_ver

0.9 for this version. (Still under development)

The receiving party should store both the transaction token and the OCSP response. Optionally, the signing certificate can be stored.

Verification of transaction token

  • The expected Issuer Identifier MUST exactly match the value of the iss (issuer) claim.
  • The client MUST validate the signature of transaction tokens according to JWS [JWS] using the algorithm specified in the JWT alg Header Parameter. The client MUST use the keys provided by the Issuer (available via the Discovery endpoint).
  • The client MUST validate that the signing certificate is a Voces3 certificate with the exact certificate DN specified in the environments section in this document.
  • The iat Claim can be used to reject tokens that were issued too far away from the current time, limiting the amount of time that nonces need to be stored to prevent attacks. The acceptable range is client specific.
  • If a nonce value was sent in the authentication request, a nonce claim MUST be present, and its value checked to verify that it is the same value as the one that was sent in the authentication request. The client SHOULD check the nonce value for replay attacks. The precise method for detecting replay attacks is client specific.
  • If the auth_time claim was requested, either through a specific request for this claim or by using the max_age parameter, the client SHOULD check the auth_time claim value and request re-authentication if it determines too much time has elapsed since the last end-user authentication.
  • The client MUST validate that the OCSP response validates for the signing certificate and that the OCSP response time is after the transaction token issued time (iat).
  • The client MUST validate that the expected restrictions for acr, ial, amr, idp and identitytype are as expected.

Transaction token MitID specific claims

Claim value Possible values
mitid.uuid Same value as for ID token.
mitid.referencetext Passthrough of the MitID referencetext identity provider parameter.
mitid.transactiontext Passthrough of the MitID transactiontext identity provider parameter.
dk.cpr Danish CPR.

Included if and only if configured as a requirement for the transaction token for the client in the administration interface.

Will trigger the same user interaction as setting the ssn scope.