introspect

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

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

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.

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
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 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"
}