The recommended practise for merchants is to use the Introspect URL from Openid-configuration rather than hardcoding the below URL value.

URL	`https://<oidc-baseurl>/protocol/openid-connect/token/introspect`
Request	`POST` with parameters in body as `application/x-www-form-urlencoded` data
Authentication	OIDC/OAuth2 client authentication according to supported methods
Success response	`200 OK` with JSON containing response elements
Error response	`401 Unauthorized` if client authentication fails with JSON containing same standard error reponse elements as for the Token endpoint `200 OK` with JSON containing only "active : false" if the query is otherwise invalid
Example	See below

Introspect is a standard endpoint mainly used by Resource Servers to determine the particuar authorization context for an Access Token. A Resource Server may need such information to validate incomming tokens before granting access to Proteted Resources it hosts.

Since the Access Tokens used by the OIDC Provider from BankID are self-contained most of the validation process can be performed wihtout calling the Introspection endpoint. There are however two reasons for still using introspect:

To check if the token has not been revoked for any reason prior to the expiry time that is embedded in the token itself
To get access to confidential claims that are not contained in the access token itself. The bankid_altsub is one such example

Using introspect also simlifies the validation process for the OIDC Client by leaving all self-contained checks to the OIDC Provider.

Note that the OIDC Provider from BankID does not support introspection of Refresh Tokens.

Request parameters

The following standard parameters are supported. In addition comes parameters related to Client authentication.

Parameter	Description
`token`	JWT value of the token subject to introspection
`token_type_hint`	Must contain the value `bid_access_token` to signify that the Access Token in question is of the type supported by the OIDC Provider from BankID

Response elements

The response is a JSON structure containing the same claims as those contained in the JWT Access Token subject to introspection. The following additional claims that are specific for the introspection response are also included:

Parameter	Description
`active`	Indicator of whether or not the presented token is currently active
`client_id`	Identifier of the OIDC client that requested the token
`username`	Equal to `preferred_username` in the access token subject to introspection
`nnin_altsub`	See ID Token. This claim may be returned via introspection to eligible resources servers regardless of any such claim returned in the ID Token to the OIDC client in question

Note that the scope claim is not supported in the introspection response by the OpenID Connect Provider from BankID. Resource servers may instead determine the involved scopes via the realm_access and resources_access claims of the response (which in turn originate from the access token subject to introspection).

Note that the introspection reponse for tokens via the Client Credential Grant have a different structure since there is no end user involved in that case.

Example

Introspection

POST /auth/realms/preprod/protocol/openid-connect/token/introspect HTTP/1.1
Host: oidc-preprod.bankidapis.no
Connection: close
Content-Length: 1321
Authorization: Basic UG9zdG1hbjo5YWE3NDBhZi03NGIxLTQ2ODMtOWFhNi02NWJiNDBmYmY1Zjk=
Postman-Token: 00976d86-f2ab-73ca-b0c4-78570bb367bd
Cache-Control: no-cache
Origin: chrome-extension://fhbjgbiflinjbdggehcddcbncdddomop
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/61.0.3163.100 Safari/537.36
Content-Type: application/x-www-form-urlencoded
Accept: */*
Accept-Encoding: gzip, deflate
Accept-Language: en-US,en;q=0.8


token=eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICI3VkZaSVp2UlBOY1lSUUZUcEQ4MHVJaElpVVB4WUNkaEtoUjZudjJDQnJnIn0.eyJqdGkiOiI0NTIyNGYyYS02MmQwLTRlNTgtODY1Yi1iODA2NjZlMjM3NzEiLCJleHAiOjE1MTA4MzgzNzYsIm5iZiI6MCwiaWF0IjoxNTEwODM4MDc2LCJpc3MiOiJodHRwczovL29pZGMtcHJlcHJvZC5iYW5raWRhcGlzLm5vL2F1dGgvcmVhbG1zL3ByZXByb2QiLCJhdWQiOiJ0aW5mbyIsInN1YiI6ImIzZjRkOTE5LThjYzUtNDEzYy05ZTExLTNjMmM2NzViMmY4ZiIsInR5cCI6IkJlYXJlciIsImF6cCI6IlBvc3RtYW4iLCJhdXRoX3RpbWUiOjE1MTA4MzgwNTAsInNlc3Npb25fc3RhdGUiOiJiZjBhNGM5Zi0yZDAwLTQzZDgtODI4OC0wMWI4M2FiMWU1ODAiLCJuYW1lIjoiRnJvZGUgQmVja21hbm4gTmlsc2VuIiwiZ2l2ZW5fbmFtZSI6IkZyb2RlIEJlY2ttYW5uIiwiZmFtaWx5X25hbWUiOiJOaWxzZW4iLCJhY3IiOiI0IiwiYWxsb3dlZC1vcmlnaW5zIjpbXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm5uaW5fYWx0c3ViIiwicHJvZmlsZSJdfSwicmVzb3VyY2VfYWNjZXNzIjp7InRpbmZvIjp7InJvbGVzIjpbImFkZHJlc3MiLCJwaG9uZSIsImVtYWlsIl19fSwiYW1yIjoiQklEIiwicHJlZmVycmVkX3VzZXJuYW1lIjoiTmlsc2VuLCBGcm9kZSBCZWNrbWFubiIsImJhbmtpZF9hbHRzdWIiOiI5NTc4LTYwMDAtNC0zMDc5OSJ9.EWLAWLfy4FFGa4UACJfLfCBiPKyNOoLJxUoEirrcR3JR81ruJW3T3SyTP4iMZ74nFbHclS9z4j8AhzBYfhdj9ZpCqAnYiJUGdwyMLPTRMoY_qW57qd1ZXoP93nAK9yhByLEI-N4U6wsC_FJado2EfyT_9oyKFx5YGa9Rg4wldbyt9EcUXsl-AuoLEhDbNjr3O-O9eixCXkyCj_sSptOlu4bdzTDpkYaAenXahncST6H_-n7Pe1Q1eZJuDjx2ofLsn3TGXlAb5zuOdiNUdmBk9jkUZiTz-5CxR-z9JQDZPfwJYSuC-z4X-rnknfDw06OnlbY7zGYPL827Nzw74snnRg


HTTP/1.1 200 OK
Date: Thu, 16 Nov 2017 13:15:21 GMT
Server: WildFly/10
X-Powered-By: Undertow/1
Content-Type: application/json
Content-Length: 717
Via: 1.1 oidc-preprod.bankidapis.no
Connection: close

{
    "jti": "45224f2a-62d0-4e58-865b-b80666e23771",
    "exp": 1510838376,
    "nbf": 0,
    "iat": 1510838076,
    "iss": "https://oidc-preprod.bankidapis.no/auth/realms/preprod",
    "aud": "tinfo",
    "sub": "b3f4d919-8cc5-413c-9e11-3c2c675b2f8f",
    "typ": "Bearer",
    "azp": "Postman",
    "auth_time": 1510838050,
    "session_state": "bf0a4c9f-2d00-43d8-8288-01b83ab1e580",
    "name": "Frode Beckmann Nilsen",
    "given_name": "Frode Beckmann",
    "family_name": "Nilsen",
    "preferred_username": "Nilsen, Frode Beckmann",
    "acr": "4",
    "allowed-origins": [],
    "realm_access": {
        "roles": [
            "nnin_altsub",
            "profile"
        ]
    },
    "resource_access": {
        "tinfo": {
            "roles": [
                "address",
                "phone",
                "email"
            ]
        }
    },
    "amr": "BID",
    "bankid_altsub": "9578-6000-4-30799",
    "client_id": "Postman",
    "username": "Nilsen, Frode Beckmann",
    "active": true
}