Document toolboxDocument toolbox

Introspect

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

URLhttps://<oidc-baseurl>/protocol/openid-connect/token/introspect
Request

POST with parameters in body as application/x-www-form-urlencoded data

AuthenticationOIDC/OAuth2 client authentication according to supported methods
Success response200 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

ExampleSee 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.

ParameterDescription
tokenJWT value of the token subject to introspection
token_type_hintMust 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:

ParameterDescription
active
Indicator of whether or not the presented token is currently active 
client_idIdentifier of the OIDC client that requested the token
usernameEqual to preferred_username in the access token subject to introspection
nnin_altsubSee 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
}