Document toolboxDocument toolbox

Access Tokens

The OpenID Connect Provider from BankID provides by default Access Tokens.

Structure

The default access token structure builds on Keycloak and consists of the following three parts:

  • A General part telling that the supported token type corresponds to standard Bearer Token usage
  • An ID part that contains key claims from the corresponding ID Token
  • An Access part that contains details on resource access, including in particular the audience (aud) for the access token.

The supported default token type is self-contained since it contains enough information to determine the authorization context, in particular the following:

  • The issuer (iss)of the access token. See corresponding claim in ID Token.
  • The authorized party (azp) for the access token. See corresponding claim in ID Token.
  • The subject identifier (sub) of the access token, ie. a reference to the end-user (resource owner) that authorized the access token. See corresponding claim in ID Token.
  • Intended audience (aud)for the access token, ie. a reference to resource servers that the access token regulates access to. Note that this is not related to the corresponding claim in the ID Token. The audience for the ID Token (being the OIDC Client) is different from the audience for an Access Token.
  • The specific set of resources that the access token grants access to, corresponding to the set of scopes included in the Authorize request that subsequently resulted in the issuance of the Access Token.

Note that access tokens for the Client Credential Grant have a different structure for the ID part since there is no ID Token involved in that case.

Note finally that the OIDC Provider form BankID supports signed Access Tokens in JWT format. The below table shows claims in the payload part of the JWT. Claims contained in the JWT header are not shown. See session handling for the life-time of an access token. To cater for access tokens that are either revoked before their expiry, or that have expired prematurely for other reasons, validation of access tokens via Introspect is supported. Another use of introspection is for eligible resource servers to retrieve confidential claims that are not carried in the access token itself. One such examle is the bankid_altsub claim.

Scopes and claims

The claims in the Access token is outlined in the table below. The origin column indicates non-standard claims. Such claims are either added by Keycloak or the result of customization made by the BankID OIDC Provider.

ClaimOriginScopeExampleDescriptionComment
General part
typKeycloaknone requiredBearerToken typeAlways Bearer for Access Tokens
allowed-originsKeycloaknone required
[ ]Not in use by the OIDC Provider from BankID
ID part

acr

Standardnone required

4

See ID Token

amr

Standardnone required

API Version 1: BID

API Version 2 onwards: ["bid"]

See ID Token 

auth_time

Standardnone required

1510497762

See ID Token 

azp

Standardnone required

oidc_testclient

See ID Token 

bankid_altsub

Customnone required

9578-5999-4-1765512

See ID Token 

exp

Standardnone required

1510498063

See session handling 

iat

Standardnone required

1510497763

See session handling 

iss

Standardnone required

<oidc-baseurl>

See ID Token 

jti

Standardnone required

7f22fd6a-3d46-4d5a-ae56-6de3c53e1873

See ID Token 

nbf

Standardnone required

0

See ID Token 

nonce

Standardnone required

<random value>

See ID Token 

session_state

Keycloaknone required

abf823c2-9810-4133-9369-7bff1223d6c1

See ID Token 

sub

Standardnone required

e8c523ff-52a2-42e2-a7a5-f1d0fbb76204

See ID Token 

birthdate

Standardnone required

1966-12-18

See ID Token

family_name

Standard

profile

Nilsen

See ID Token 

given_name

Standard

profile

Frode Beckmann

See ID Token 

name

Standard

profile

Nilsen, Frode Beckmann

See ID Token 

preferred_username

Standard

profile

Nilsen, Frode Beckmann

See ID Token 
api_ver
Custom

none required

1
See ID Token 
Access part
audStandardnone required
tinfoAudienceList of VAS-names for which the access token in question is intended
realm_accessKeycloak

profile
address
phone
email nnin_altsub
nnin

{"roles:

  ["profile","address","phone","email","nnin_altsub","nnin"]

}

 

Resource access designator at the OIDC platform level.

 

resource_access
Keycloak

profile
address
phone
email
nnin

 

{"tinfo:
{"roles
["address","phone_number", "email", "nnin"]
}}
Resource access designator.

Examples

Access token for electronic signing

The following is an example of a valid access token to the SignDoc resource server. The resource designator signdoc as well as the role read_write is added to the resource_access claim of the access token to signify access to the associated endpoint of the SignDoc resource server API. 

{
    "exp": 1629281602,
    "iat": 1629281302,
    "jti": "7cc03090-7c8b-4775-9532-51169932adc7",
    "iss": "https://auth.current.bankid.no/auth/realms/current",
    "aud": "signdoc",
    "sub": "b9ce6414-2ddc-46e2-8330-7f3d59000c64",
    "typ": "Bearer",
    "azp": "oidc-testclient",
    "acr": "1",
    "realm_access": {
      "roles": []
    },
    "resource_access": {
      "signdoc": {
        "roles": [
          "read_write"
        ]
      }
    },
    "scope": "signdoc/read_write",
    "clientHost": "xxx.xxx.xxx.xx",
    "clientId": "oidc-testclient",
    "resource_claims": {},
    "clientAddress": "xxx.xxx.xxx.xx"
}

Access token for access to userinfo

Below is example of a valid Access Token for access to the TINFO resource server, used in context of the api-userinfo API. The resource designator tinfo is added to the resource_access claim of the access token to signify access to various parts of the TINFO dataset. Since Userinfo (TINFO Userinfo Endpoints) supports standardized claims, the same set of claims is also included under realm_access.

{
    "sub": "2cd7cecd-d444-4685-bb04-8bbfdb45a069",
    "resource_access": {
        "tinfo": {
            "roles": [
                "address",
                "phone",
                "profile",
                "email"
            ]
        }
    },
    "birthdate": "2018-05-09",
    "amr": "BID",
    "iss": "https://auth.current.bankid.no/auth/realms/current",
    "typ": "Bearer",
    "bankid_altsub": "9578-6000-4-634582",
    "originator": "CN=BankID - TestBank1 - Bank CA 3,OU=123456789,O=TestBank1 AS,C=NO;OrginatorId=9980;OriginatorName=BINAS;OriginatorId=9980",
    "given_name": "Test User",
    "nonce": "a6c03ff5-936c-4bff-ab98-a9898d37984f",
    "aud": "tinfo",
    "acr": "urn:bankid:bid;LOA=4",
    "realm_access": {
        "roles": [
            "address",
            "phone",
            "profile",
            "email"
        ]
    },
    "azp": "oidc-testclient",
    "auth_time": 1629280890,
    "scope": "openid phone address profile email",
    "resource_claims": {},
    "name": "Test User BankID",
    "exp": 1629281190,
    "session_state": "66801cef-7746-4dd6-a018-43bda5c7002b",
    "iat": 1629280890,
    "family_name": "BankID",
    "jti": "2fc59b32-e1ed-47cb-abf7-87786504912a"
}

Other notes

To be prepared for a possible future change from multi-audience access tokens to single-audience access tokens, OIDC Clients are recommended to not include a set of scopes in the same request that affects more that one VAS. The recommended integration practise is to use a series of subsequent requests for access tokens to separate VAS. Using this recommended integration practise will not break backwards compatibility if a single-audience restriction is introduced. For authentication flows involving the end-user subsequent requests can be made via the id_token_hint option for the Authorize endpoint to avoid repeated authentication of the end-user.

Note that the OIDC Provider from BankID currently supports multi-audience tokens. If an OIDC Client requests a set of scopes that affect several resource servers, each of the affected services will be listed in the aud claim of the access token.

This practise may be changed in a future release of the OIDC Provider from BankID by imposing a restriction to not allow requests for a set of scopes that affect more than one VAS in each request. Introducing such a single-audience restriction has the benefit of giving tighter control since a bearer token in wrong hands gives access to fewer resources. The downside of a single-audience restriction is that integration becomes more complex for OIDC clients since multiple requests must be made, one for each set of requested scopes, to get a series of access tokens, one for each affected VAS.