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.

As the Access Tokens used by the OIDC Provider from BankID are self-contained most of the validation process can be performed without 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 simplifies 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.

Overview

URL	`https://<oidc-baseurl>/protocol/openid-connect/token/introspect`
Request	`POST` with 24878955 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 24878955
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 24878955

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

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
`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 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/current/protocol/openid-connect/token/introspect HTTP/1.1
Host: auth.current.bankid.no
User-Agent: curl/7.64.1
Accept: */*
Authorization: Basic dGluZm86MDEyMzQ1NjctODlhYi1jZGVmLTAxMjMtNDU2Nzg5YWJjZGVm
Content-Length: 1538
Content-Type: application/x-www-form-urlencoded

token_type_hint=bid_access_token&token=eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICI3VkZaSVp2UlBOY1lSUUZUcEQ4MHVJaElpVVB4WUNkaEtoUjZudjJDQnJnIn0.eyJleHAiOjE2MjkyODk5NTMsImlhdCI6MTYyOTI4OTY1MywiYXV0aF90aW1lIjoxNjI5Mjg5NjM0LCJqdGkiOiJiNDdlNDFhYS1mNjg5LTRmNjgtODBkNC00ZmRkYTE4NTVmOGQiLCJpc3MiOiJodHRwczovL2F1dGguY3VycmVudC5iYW5raWQubm8vYXV0aC9yZWFsbXMvY3VycmVudCIsImF1ZCI6InRpbmZvIiwic3ViIjoiMmNkN2NlY2QtZDQ0NC00Njg1LWJiMDQtOGJiZmRiNDVhMDY5IiwidHlwIjoiQmVhcmVyIiwiYXpwIjoib2lkYy10ZXN0Y2xpZW50Iiwibm9uY2UiOiJkZW1vTm9uY2UiLCJzZXNzaW9uX3N0YXRlIjoiNjY4MDFjZWYtNzc0Ni00ZGQ2LWEwMTgtNDNiZGE1YzcwMDJiIiwibmFtZSI6IlRlc3QgVXNlciBCYW5rSUQiLCJnaXZlbl9uYW1lIjoiVGVzdCBVc2VyIiwiZmFtaWx5X25hbWUiOiJCYW5rSUQiLCJiaXJ0aGRhdGUiOiIyMDE4LTA1LTA5IiwiYWNyIjoidXJuOmJhbmtpZDpiaWQ7TE9BPTQiLCJyZWFsbV9hY2Nlc3MiOnsicm9sZXMiOlsicHJvZmlsZSJdfSwicmVzb3VyY2VfYWNjZXNzIjp7InRpbmZvIjp7InJvbGVzIjpbInByb2ZpbGUiXX19LCJzY29wZSI6Im9wZW5pZCBwcm9maWxlIiwiYW1yIjoiQklEIiwicmVzb3VyY2VfY2xhaW1zIjp7fSwiYmFua2lkX2FsdHN1YiI6Ijk1NzgtNjAwMC00LTYzNDU4MiIsIm9yaWdpbmF0b3IiOiJDTj1CYW5rSUQgLSBUZXN0QmFuazEgLSBCYW5rIENBIDMsT1U9MTIzNDU2Nzg5LE89VGVzdEJhbmsxIEFTLEM9Tk87T3JnaW5hdG9ySWQ9OTk4MDtPcmlnaW5hdG9yTmFtZT1CSU5BUztPcmlnaW5hdG9ySWQ9OTk4MCJ9.OjXahrNqO2RWp-aJ9mpUz40xuhZMqo8uAHN60hKL3-62SRrm7izO9tiEWfF1fxCd-QhKnO4WCvri3naVL-VFqZQmWHpoPCFCcB9042K7GNLnNWuwH-IqOL912SzeGdKzc2u6CqB_i4M-78KmRB1KFi5mzzxXoizmulKQtTborCGirVx3RUPVYEBhns2azmVouWJwDUsk5Tx33AP7Crjf6OQRamsx3PYkHe6OSuFWcUb3sLzWJXSDKL85vtj_vA5oXR2j7ZfzIikcxDy1d6YSOmJx03BY2Cuk7ySscicXN_cNE5Mux54VmG7DFqzN4N-bsaSoYLpmMB06mixJ4y-QUQ

HTTP/1.1 200 OK
Date: Wed, 18 Aug 2021 12:28:48 GMT
Server: web
X-XSS-Protection: 1; mode=block
Strict-Transport-Security: max-age=31536000
X-Content-Type-Options: nosniff
Content-Type: application/json
Referrer-Policy: no-referrer
Content-Length: 966

{
    "exp": 1629289953,
    "iat": 1629289653,
    "auth_time": 1629289634,
    "jti": "b47e41aa-f689-4f68-80d4-4fdda1855f8d",
    "iss": "https://auth.current.bankid.no/auth/realms/current",
    "aud": "tinfo",
    "sub": "2cd7cecd-d444-4685-bb04-8bbfdb45a069",
    "typ": "Bearer",
    "azp": "oidc-testclient",
    "nonce": "demoNonce",
    "session_state": "66801cef-7746-4dd6-a018-43bda5c7002b",
    "name": "Test User BankID",
    "given_name": "Test User",
    "family_name": "BankID",
    "birthdate": "2018-05-09",
    "acr": "urn:bankid:bid;LOA=4",
    "realm_access": {
        "roles": [
            "profile"
        ]
    },
    "resource_access": {
        "tinfo": {
            "roles": [
                "profile"
            ]
        }
    },
    "scope": "openid profile",
    "client_org_no": "918713867",
    "nnin_altsub": "09051888860",
    "amr": "BID",
    "resource_claims": {},
    "active": true,
    "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",
    "partner_org_no": "918713867",
    "token_type": "Bearer",
    "client_name": "OIDC Testklient",
    "client_id": "oidc-testclient"
}