Connecting a web application

Tip

See the description of the interaction between a web application and Blitz Identity Provider via OIDC.

Connection settings

To connect a mobile application to Blitz Identity Provider, you will need the data obtained when registering it in product:

• the identifier assigned to the application in Blitz Identity Provider (client_id);

• the secret of the application (client_secret);

• return URLs registered for the application during authorization;

• logout return URLs registered for the application;

• the permissions registered for the application (scope).

In order to interact with Blitz Identity Provider, the web application must use the following addresses:

• URL for authorization and authentication:

  • https://login-test.company.com/blitz/oauth/ae (test environment)

  • https://login.company.com/blitz/oauth/ae (production environment)

• URL for getting and updating the access token:

  • https://login-test.company.com/blitz/oauth/te (test environment)

  • https://login.company.com/blitz/oauth/te (production environment)

• URL for getting user data:

  • https://login-test.company.com/blitz/oauth/me (test environment)

  • https://login.company.com/blitz/oauth/me (production environment))

• URL for getting access token data:

  • https://login-test.company.com/blitz/oauth/introspect (test environment)

  • https://login.company.com/blitz/oauth/introspect (production environment)

• URL for performing the logout:

  • https://login-test.company.com/blitz/oauth/logout (test environment)

  • https://login.company.com/blitz/oauth/logout (production environment)

All these URLs, as well as additional information, are located at the address of dynamically updated settings (metadata) of each Blitz Identity Provider environment:

Tip

See RFC 8414 OAuth 2.0 Authorization Server Metadata.

• https://login-test.company.com/blitz/.well-known/openid-configuration (test environment)

• https://login.company.com/blitz/.well-known/openid-configuration (productive environment)

Application developers can use a single link to Blitz Identity Provider metadata instead of listing all of the URLs in their application’s configuration.

Ready-made libraries

To integrate an application with Blitz Identity Provider, you can use one of the many ready-made OAuth 2.0 libraries or implement the interaction yourself.

Getting the authorization code

To identify and authenticate the user, the application must direct the user to the URL to receive the authorization code in Blitz Identity Provider, passing as parameters:

• client_id is the client’s ID;

• response_type – response type (takes the value code, token, code token, code id_token, code id_token token, id_token token, id_token);

  Important

  The value of the response_type parameter indicates the way the application has chosen to interact with Blitz Identity Provider:

  • code – Authorization Code Flow;

  • code token, code id_token token, code id_token token – Hybrid Flow;

  • id_token token, id_token – OIDC Implicit Flow;

  • token – OAuth 2.0 Implicit Flow.

• response_mode (optional parameter) – allows you to explicitly specify the required method of transmitting the authorization code. When the application is normally connected to Blitz Identity Provider, this parameter should not be transmitted, since it is recommended to use standard methods of transmitting the authorization code (query – for Authorization Code Flow and fragment – for Implicit/Hybrid Flow).

  Possible values of the response_mode parameter:

  • query – the value of the authorization code (code) is returned to the redirect_uri of the application in the form of a query parameter. The standard mode for Authorization Code Flow.

  • fragment – the value of the authorization code (code) is returned to the redirect_uri of the application in the form of a fragment parameter (#). The standard mode for Implicit Flow.

  • form_post – in this mode, the authorization response parameters are encoded as HTML form values, which are automatically sent to the User Agent and transmitted to the client via the HTTP POST method, while the resulting parameters are encoded in the body using the application/x-www-form-urlencoded format.

• scope – the requested permissions, for authentication, the openid permission and the necessary additional scope must be passed to receive user data, for example, profile (when multiple scopes are requested, they are transmitted in one line and separated from each other by a space);

• redirect_uri is a link to return the user to the application, the link must match one of the registered values;

• state is a set of random characters in the form of a 128-bit request identifier (used to protect against interception), the same value will be returned in the response – an optional parameter;

• access_type (optional parameter) – whether the application needs to receive refresh_token, which is necessary to obtain information about the user in the future when the user is offline. Takes the value online or offline, refresh_token is provided when access_type=offline. If the value is not set, then the behavior is determined by the setting set for the specified application in Blitz Identity Provider;

• prompt (optional parameter) – specifies Blitz Identity Provider the required login mode. Possible values of the prompt parameter:

  • none is a ban on authentication.

    If, when executing a request, Blitz Identity Provider needs to display the identification/authentication request screen to the user, Blitz Identity Provider will not do this, but will return the login_required error to the system on its redirect_uri. A call with the prompt=none parameter should be made if the application wants to check if the user has a Blitz Identity Provider session, but does not want the user to see the Blitz Identity Provider login screen when performing such a check.

  • select_account – request to change the current user.

    Blitz Identity Provider will display an account selection screen to the user so that the user can log in with a different account.

  • login is a ban on SSO.

    If, when executing the request, Blitz Identity Provider finds out that the user has already been identified/authenticated before, then Blitz Identity Provider will explicitly require the user to re-identify/authenticate. At the same time, Blitz Identity Provider additionally checks that the login will be performed by the same user whose user session is open.

    If, during re-identification/authentication, the user logs in with a different account, Blitz Identity Provider returns the login_required error to the system on its redirect_uri. A call with the prompt=login parameter should be made if the application wants to explicitly request identification/authentication from the user, for example, when accessing an application function that requires increased protection.

  Note

  For prompt=login for the application, if necessary, you can enable a different scenario for processing the situation that the user logged in with a different account than he was previously logged in to the session. Namely, you can enable that when prompt=login is called, the current session is forcibly logged out and the session is created under a new account. This behavior is not recommended, but can be enabled for the application on a separate request.

• nonce (optional parameter) is a string used to bind an application session to an identification token. When the application is connected to Blitz Identity Provider using Authorization Code Flow as standard, there is no need to use the nonce parameter.

  When connecting via Implicit Flow or Hybrid Flow, this parameter must be passed. The nonce value must be a random text string.

• display (optional parameter) – the parameter in the script value is passed only if the login process is started via HTTP API.

• bip_action_hint (optional parameter) – specifies Blitz Identity Provider that the login page should open in one of the special modes:

  • open_reg – open in user registration mode; when using this mode, you can additionally specify the login_hint parameter with the user’s email value, and then the “Email address” field will be filled with the specified email value;

  • open_recovery – open in password recovery mode; when using this mode, you can additionally specify the login_hint` parameter with the value of the user’s email, and then the “Login” field will be filled with the specified email value;

  • used_externalIdps:apple:apple_1 – open in Apple ID login mode;

  • used_externalIdps:facebook:facebook_1 – open in Facebook login mode [1];

  • used_externalIdps:google:google_1 – open in Google login mode;

  • used_password – open in password login mode (default behavior);

  • used_webAuthn – open in login mode using the FIDO2 key (Passkey);

  • used_x509 – open in the login mode by electronic signature;

  • used_qrCode – open in QR code login mode;

  • used_spnego – open in login mode by operating system session;

  • used_sms – open in the login mode by SMS code;

  • used_outside_methodname – open in login mode via an external authentication method named methodname.

• bip_user_hint (optional parameter) – the identifier (sub) of the user account is passed, which should be selected automatically when the login screen is opened.

  The ID must match one of the accounts stored on the device, or the login page will be opened in the new user login mode;

• login_hint (optional parameter) – a value is passed that must be filled in the login field if the login page is open in the new user login mode.

  If you need to fill in the login in the case when there is already a remembered user, then you need to use the login_hint parameter in combination with the bip_user_hint parameter;

• bip_extIdps_user_choose_hint (optional parameter) – the identifier (sub) of the user account is passed, which should be selected automatically if the user logs in through an external identification provider to which several Blitz Identity Provider accounts are linked;

• code_challenge_method (optional parameter) – the value “S256” is passed if the connected application supports the PKCE specification for additional protection of interaction with Blitz Identity Provider.

  Tip

  See RFC 7636 Proof Key for Code Exchange by OAuth Public Clients.

  PKCE is not required to connect web applications.

  PKCE must be used to connect mobile applications to Blitz Identity Provider.

• code_challenge (optional parameter) – when using PKCE, the value calculated from code_verifier is passed to this parameter using the following formula:

  Tip

  When debugging, it is convenient to use the online calculator.

  code_challenge=BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))
  

  Note

  It is forbidden to open the login page in the frame. The user should see the URL of the login page, and also be able to verify that the HTTPS connection is available by the web portal``login.company.com``.

Example of a request to receive an authorization code (identification/authentication and access token with openid and profile permissions were requested):

https://login.company.com/blitz/oauth/ae?client_id=ais&response_type=code&scope=openid+profile&access_type=offline&state=342a2c0c-d9ef-4cd6-b328-b67d9baf6a7f&redirect_uri=https%3A%2F%2Fapp.company.com%2Fre

An example of a response with the value of the authorization code (code) and the state parameter:

https://app.company.com/re?code=f954…nS0&state=342a2c0c-d9ef-4cd6-b328-b67d9baf6a7f

Possible errors when calling /oauth/ae comply with RFC 6749 and are described here.

An example of a request for an authorization code in which Blitz Identity Provider should not open the login page if the user has not yet been identified/authenticated in the current web browser:

https://login.company.com/blitz/oauth/ae?client_id=ais&response_type=code&scope=openid+profile&access_type=offline&state=342a2c0c-d9ef-4cd6-b328-b67d9baf6a7f&prompt=none&redirect_uri=https%3A%2F%2Fapp.company.com%2Fre

An example of an error response if, in order to receive the authorization code, the user must explicitly pass identification/authentication on the Blitz Identity Provider login page, and the request was executed with the prompt=none parameter:

https://app.company.com/re?error=login_required&error_description=The+Authorization+Server+requires+End-User+authentication…&state=342a2c0c-d9ef-4cd6-b328-b67d9baf6a7f

Example of a request for an access token and an identification token using OIDC Implicit Flow:

https://login.company.com/blitz/oauth/ae?client_id=ais&response_type=id_token%20token&scope=openid+profile&state=342a2c0c-d9ef-4cd6-b328-b67d9baf6a7f&nonce=n-0S6_WzA2Mj&redirect_uri=https%3A%2F%2Fapp.company.com%2Fre

An example of a response from Blitz Identity Provider with access and identification tokens obtained using OIDC Implicit Flow:

https://app.company.com/re#access_token=SlAV32hkKG&token_type=Bearer&id_token=eyJ0…NiJ9.eyJ1c…I6IjIifX0.DeWt4Qu…ZXso&expires_in=3600&state=342a2c0c-d9ef-4cd6-b328-b67d9baf6a7f

Example of a request for an authorization code and an identification token using OIDC Hybrid Flow:

https://login.company.com/blitz/oauth/ae?client_id=ais&response_type=code%20id_token&scope=openid+profile&state=342a2c0c-d9ef-4cd6-b328-b67d9baf6a7f&nonce=n-0S6_WzA2Mj&redirect_uri=https%3A%2F%2Fapp.company.com%2Fre

An example of a response from Blitz Identity Provider with access and identification tokens obtained using OIDC Hybrid Flow:

https://app.company.com/re#code=f954…FxS0&id_token=eyJ0…NiJ9.eyJ1c…I6IjIifX0.DeWt4Qu…ZXso&state=342a2c0c-d9ef-4cd6-b328-b67d9baf6a7f

Getting tokens

In order to carry out the result of identification/authentication of the user and obtain his data, Blitz Identity Provider issues various tokens to the application.

Tokens used in Blitz Identity Provider

Name	Designation	Purpose and validity period
Access token	access_token	Getting access to a protected resource, for example, user data. The token is valid for 3600 seconds.
Refresh token	refresh_token	Updating the access token. The refresh_token token is provided only if the application specified the need to receive a refresh_token during registration, or if the access_type=offline parameter was specified in the request for an authorization code. The token is valid until the moment of use, but no longer than 365 days.
ID token	id_token	Obtaining identification information, for example, a user ID. The token is valid for 3 hours.

Exchange of the authorization code for tokens

After receiving the authorization code, the application must exchange it for tokens.

Attention

The token collection service must be called from the servers of the application connected to Blitz Identity Provider. Calling the service from the program code executed on the side of the web browser (for example, from the JavaScript code of a web page) is PROHIBITED. The received access token (access_token) must be processed by the backend of the application and must not be transmitted through the user’s browser.

Method

POST https://login.company.com/blitz/oauth/te

Headers

Authorization with the value Basic {secret}, where secret is client_id:client_secret (for example, app:topsecret) in Base64 format.

Request body

• code – the value of the authorization code that was previously received;

• grant_type – takes the value authorization_code, if the authorization code is exchanged for an access token;

• redirect_uri – the link to which the user should be directed after giving permission for access (the same value that was specified in the request for an authorization code);

• code_verifier (only if PKCE is used) is the value of the verification code used in calculating the code_challenge when receiving the authorization code.

Returns

• If successful, an access token, an update token, and an identification token.

  Tip

  Using the received access token, the application can request up-to-date user data from Blitz Identity Provider.

• If the authorization code has already been used, the redirect_uri did not match the one previously used in the call to /oauth/ae, or the code expired, or the code_verifier passed does not match code_challenge, an error will be returned as a response. Possible errors when calling /oauth/te comply with RFC 6749 and are described here.

Examples

Request

POST /blitz/oauth/te HTTP/1.1
Authorization: Basic cG9ydGFsLmlhc2l1LmxvY2FsOnBvcnRhbC5pYXNpdS5sb2NhbA==
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=FLZHS…GU&redirect_uri=https%3A%2F%2Fapp.company.com%2Fre

Response

{
    "id_token": "eyJhbGciOiJSUzI1NiJ9.eyJub…n0=.Ckt…sQ",
    "access_token": "dO-xym…BE",
    "expires_in": 3600,
    "refresh_token": "1lEWX…Iw",
    "token_type": "Bearer"
}

Error

{
    "error": "invalid_grant",
    "error_description": "The provided authorization grant … is invalid, expired, revoked…"
}

Updating the access token

Method

POST https://login.company.com/blitz/oauth/te

Headers

Authorization with the value Basic {secret}, where secret is client_id:client_secret (for example, app:topsecret) in Base64 format.

Request body

• refresh_token is refresh token;

• grant_type – takes the value``refresh_token`` if the refresh token is exchanged for an access token.

Request example

POST /blitz/oauth/te HTTP/1.1
Authorization: Basic cG9ydGFsLmlhc2l1LmxvY2FsOnBvcnRhbC5pYXNpdS5sb2NhbA==
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=jj2DA…bQ

Exchanging an access token

An application can exchange an access_token with one set of permissions (scopes) and claims (claims) for an access_token with another set of permissions and claims using the OAuth 2.0 Token Exchange. This can be useful before transferring the access_token from the application that received it to another application, so that the application receives a reduced set of permissions and user information.

Attention

To use the access token exchange, the application must be granted special permission to use the OAuth 2.0 Token Exchange (urn:ietf:params:oauth:grant-type:token-exchange is allowed). The settings for the access token exchange rules must also be set.

Method

POST https://login.company.com/blitz/oauth/te

Headers

Authorization with the value Basic {secret}, where secret is client_id:client_secret (for example, app:topsecret) in Base64 format.

Request body

Attention

One of the resource or audience parameters must be specified.

• grant_type – takes the value urn:ietf:params:oauth:grant-type:token-exchange.

• resource – takes the name of the resource for which the exchange of the access token is requested.

• audience – takes the names of applications for which an access token is requested.

• subject_token_type – the required type of the received token is passed. In the current version of Blitz Identity Provider, only the urn:ietf:params:oauth:token-type:access_token type is supported.

• subject_token – the value of the replaced access token (access_token) is passed.

• Optional parameter scope – specifies the list of requested scope in the new token. If this parameter is not specified, then all the scope allowed by the exchange rule will be included in the new token.

• Optional parameter token_format – specifies the required format for the issued access token. Possible values: jwt or opaque. If this parameter is omitted, the new access token will be issued in the same format as the access token passed to subject_token.

Examples

Request

Standard request

POST /blitz/oauth/te HTTP/1.1
Authorization: Basic cG9…A==
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:token-exchange&resource=…&subject_token_type=urn:ietf:params:oauth:token-type:access_token&subject_token=eyJ…vA

Request with transmission of audience, token_format and scope

POST /blitz/oauth/te HTTP/1.1
Authorization: Basic cG9…A==
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:token-exchange&token_format=opawue&audience=system1 system2&scope=openid profile&subject_token_type=urn:ietf:params:oauth:token-type:access_token&subject_token=uuy…OE

Response

{
    "access_token": "eyJr...-g",
    "expires_in": 3600,
    "scope": "openid new_scope",
    "token_type": "Bearer",
    "issued_token_type": "urn:ietf:params:oauth:token_type:access_token"
}

Error

No rules were found to allow the requested access token exchange

{
    "error": "invalid_target",
    "error_description": "Access denied for resource or audience"
}

The access token has expired

{
    "error": "bad_access_token",
    "error_description": "Access token 'CmJ…Dk' not found"
}

Using OAuth 2.0 Resource Owner Password Credentials

If the application has been granted special permission to use OAuth 2.0 Resource Owner Password Credentials (ROPC) (grant_type – password` is allowed), then the application can request an access token as follows.

Method

POST https://login.company.com/blitz/oauth/te

Headers

Authorization with the value Basic {secret}, where secret is client_id:client_secret (for example, app:topsecret) in Base64 format.

Request body

• grant_type – takes the value password;

• username – contains the username of the user;

• password – contains the user’s password;

• scope – contains a list of requested permissions.

Returns

• If successful, an access token.

• In case of failure, an error. Possible values for error_description in case of an account problem:

  • Invalid user credentials – invalid username or password;

  • User_locked - account locked;

  • User locked by inactivity – the account is blocked due to prolonged inactivity;

  • Password method locked – a ban on using password authentication is enabled for the account;

  • Password method not configured – the password authentication method is not configured;

  • Password expired – the password has expired;

  • Need password change – a mandatory password change is required when logging in.

Request

POST /blitz/oauth/te HTTP/1.1
Authorization: Basic cG9…A==
Content-Type: application/x-www-form-urlencoded

grant_type=password&username=testuser&password=testpwd1&scope=profile

Response

{
    "access_token": "dO-xym…BE",
    "expires_in": 3600,
    "scope": "profile",
    "token_type": "Bearer"
}

Error

{
    "error": "invalid_grant",
    "error_description": "Invalid user credentials"
}

ID token

To obtain identification and authentication data, the application can independently analyze the content of the ID token (id_token).

Tip

Instead of analyzing the id_token , it is recommended to use a request to updating user data by access token.

Token structure

The ID token consists of three parts:

• the header (header),, which contains general information about the type of token, including the cryptographic operations used during its formation;

• a set of statements (payload / claim set) with meaningful information about the token;

• a signature (signature) that certifies that the token was issued by Blitz Identity Provider and was not changed during transmission.

The parts of the token are separated by a dot, it looks like:

HEADER.PAYLOAD.SIGNATURE

The token is passed as a string in the Base64url format.

Token header

• alg – description of the encryption algorithm (parameter alg); currently Blitz Identity Provider supports the electronic signature algorithm RSA SHA-256 recommended by the specification (corresponds to the value RS256);

• kid – ID of the key used to sign the token.

Set of statements

Attributes:

• exp is the time of expiration, indicated in seconds from January 1, 1970. 00:00:00 GMT;

• iat is the time of issue, indicated in seconds from January 1, 1970. 00:00:00 GMT;

• sub is the identifier of the subject, the value of the user ID is specified as the value;

• ua_id is the user’s device identifier;

• aud is the recipient of the token, the client_id of the application that sent the authentication request is indicated;

• iss – the organization that issued the token, specify the issuer URL, https://login.company.com/blitz by default;

• nonce is a security string, the value nonce is specified, which was passed by the application to Blitz Identity Provider in the original request to /oauth/ae. It is used only with Implicit or Hybrid Flow. When an application receives a token using Implicit or Hybrid Flow, the application must match nonce from the identification token with nonce from its request;

• at_hash is half of the hash of the access token, transmitted only when using Implicit or Hybrid Flow. It represents the Base64 encoded left half of the value of the SHA‑256 function from access_token. An application that receives an access token using Implicit or Hybrid Flow must extract the value at_hash from the identification token and compare it with the access token.

• c_hash is half of the hash of the authorization code, transmitted only if Hybrid Flow is used. It is the Base64 encoded left half (128 bits) of the SHA‑256 function value from the authorization code (code); An application that receives an authorization code using Hybrid Flow must extract the value c_hash from the identification token and compare it with the authorization code.

• amr – authentication methods passed, a list of authentication methods passed by the user is indicated. The list may include the following method identifiers:

  • password – login using a password;

  • cls:<method>` (for example, ``cls:password) – automatic login from a memorized device (in the name of the identifier, after the colon, the authentication method initially passed by the user is indicated, as a result of which the user was memorized on this device);

  • css – automatic login based on the results of user registration, password recovery, or switching to a web application from a mobile application using a call using scope=native;

  • sms – confirmation of login using the code in the SMS message (the second authentication factor);

  • email – confirmation of login using the code in the email message (the second authentication factor);

  • push – confirmation of login using the code in the push notification to the mobile application (the second authentication factor);

  • hotp – login confirmation using a code generated by the HOTP confirmation code generator (the second authentication factor);

  • totp – confirmation of login using a code generated by the software TOTP-generator of confirmation codes (the second authentication factor);

  • tls – login in automatic authentication mode using TLS Proxy;

  • spnego – login using an operating system session;

  • userApp – login to the mobile application with a user account linked to the device (Touch ID/Face ID/PIN);

  • webAuthn – login using a FIDO2 key (Passkey) or login confirmation using a U2F key;

  • x509 – login using an electronic signature;

  • qrCode - login via QR code;

  • externalIdps:apple:apple_1 – login using an Apple ID account;

  • externalIdps:facebook:facebook_1 – login using a Facebook account [1];

  • externalIdps:google:google_1– login using a Google account;

  • externalIdps:mail:mail_1 – login using the Mail ID account;

  • externalIdps:vkid:vkid_1 – login using VK ID account;

  • externalIdps:ok:ok_1 – login using an account on the Odnoklassniki social network;

  • externalIdps:vk:vk_1 – login using a VK social network account;

  • externalIdps:yandex:yandex_1 – login using a Yandex account;

  • outside_methodname – indicates that the user used an external authentication method named methodname during the login process.

• sid is the user’s session ID;

• additional attributes in accordance with the request to connect the application to Blitz Identity Provider (see possible attributes to include in id_token here).

Example of a set of statements

{
    "exp": 1445004777,
    "iat": 1444994212,
    "ua_id": "f8a235ff-cb85-4c4b-b55d-544f9358a8d7",
    "sub": "3d10f626-ea77-481d-a50bd4a4d432d86b",
    "amr": [
        "externalIdps:esia:esia_1"
    ],
    "aud": [
        "ais"
    ],
    "iss": "https://login.company.com/blitz",
    "sid": "5a600d12-4b14-447e-ba21-2dc40344a44a"
}

Token signature

It is performed according to the algorithm specified in the alg parameter of the token. The signature is calculated from the two previous parts of the token (HEADER.PAYLOAD`). The Blitz Identity Provider public key certificate required to verify the signature can be downloaded from the following links (located in the x5c, attribute, key ID is located in the kid attribute):

• https://login-test.company.com/blitz/.well-known/jwks (test environment)

• https://login.company.com/blitz/.well-known/jwks (production environment)

Working with an ID token

1. After receiving the ID token, the application is recommended to validate the ID token, which includes the following checks:

   1. Obtaining the Blitz Identity Provider (sub) identifier contained in the ID token and obtaining other additional user attributes required by the application.

   2. Verification of the application identifier, i.e. it is the application that must be specified as the recipient of the ID token.

   3. Verification of the signature of the ID token (using the algorithm specified in the token).

   4. Verification that the current time should be no later than the expiration time of the ID token.

   After validating the ID token, the application can consider the user authenticated.

2. To analyze the content of the ID token, as well as to simplify the development of modules for its verification, you can use the available online decoders and libraries.

   Tip

   See resources http://jwt.io/ and http://kjur.github.io/jsjws/mobile/tool_jwt.html#verifier.

Checking the access token through the introspection service

The access token data (access_token) must be checked in the following cases:

• the application needs to track the expiration date of the token in order to quickly change it to a new one;

• the application has increased security requirements, and the application wants to check the token to make sure that the token is not canceled prematurely. Revocation of the access token (access_token) or ID token (id_token) may occur for security purposes if the user account password has been reset/changed or if the user account has been blocked;

• the application is a resource provider and provides access to these resources upon presentation of an access token issued by Blitz Identity Provider to the application requesting the resource.

Method

POST https://login.company.com/blitz/oauth/introspect

Tip

See RFC 7662 OAuth 2.0 Token Introspection.

The introspection service can be called by any system registered in Blitz Identity Provider to verify any access token (the system can verify a token issued to another system). You can check not only the access token, but also the refresh token.

Headers

• Authorization with the value Basic {secret}, where secret is client_id:client_secret (for example, app:topsecret) in Base64 format;

• Content-Type with the value application/x-www-form-urlencoded.

Request body

• token s the access token that you want to view the data about.

• Optional parameter ` ``token_type_hint` is the type of access token (for example,``access_token``), designed to speed up the search.

Returns

Access token data:

• active is an indication of the validity of the access token, it takes the values true or false. The token is valid if it was issued by the authorization service Blitz Identity Provider, has not been revoked and its validity has not expired;

• scope is the access area to which the access token has been issued. It is transmitted as a list of permissions;

• client_id is the identifier of the client system that received this access token;

• sub is the identifier of the user (the owner of the resource that provided access to their data), defined as the base identifier in Blitz Identity Provider. The parameter value is returned only if it can be passed within the scope of the presented access token;

• jti is the identifier of the access token (in the form of a string);

• token_type is the type of the presented access token;

• iat is the time when the token was issued (in Unix Epoch);

• exp is the expiration time of the token (in Unix Epoch).

Examples

Request

POST /blitz/oauth/introspect HTTP/1.1
Authorization: Basic cG9ydGFsLmlhc2l1LmxvY2FsOnBvcnRhbC5pYXNpdS5sb2NhbA==
Content-Type: application/x-www-form-urlencoded

token=MkvRf…No

Response

Valid access_token

{
   "sub": "3d10f626-ea77-481d-a50bd4a4d432d86b",
   "scope": "openid profile",
   "jti": "10jdlNohfHzuv3xoFurvWSPheEJEC7KHdHr-dcaVyYYvV3h0l2sh",
   "token_type": "Bearer",
   "client_id": "ais",
   "active": true,
   "iat": 1699938503,
   "exp": 1699942103
}

Valid id_token

{
    "exp": 1699939472,
    "iat": 1699935872,
    "jti": "fU2FTCzm9G5I4YC6VDFnfjFY5QeIULwHlYo_BH6OuCQ",
    "token_type": "id_token",
    "active": true,
    "client_id": "ais",
    "sub": "3d10f626-ea77-481d-a50bd4a4d432d86b"
}

Valid refresh_token

{
    "sub": "3d10f626-ea77-481d-a50bd4a4d432d86b",
    "scope": "openid profile",
    "jti": "10jdlNohfHzuv3xoFurvWSPheEJEC7KHdHr-dcaVyYYvV3h0l2sh",
    "token_type": "refresh_token",
    "client_id": "ais",
    "active": true,
    "iat": 1699938503,
    "exp": 1699942103
}

Invalid access token

{
    "active": false
}

Verification of the access token by the application

When registering an application in Blitz Identity Provider, you can specify that the application should receive an access token (access_token) in the JWT format. In this case, the application gets the opportunity to independently verify the access token by parsing it.

The structure of the initially received access token will be similar to the structure of this identification token. The secondary access tokens obtained as a result of the exchange of the refresh token (refresh_token) will not contain session information (amr and additional user attributes will be missing).

Access tokens in the JWT format should be used only if the application has special reasons for doing so. In other cases, it is recommended to use regular access tokens in the opaque format.

Logout

If the application provides the user with the opportunity to initiate a logout from the application (logout), then it is not enough for the application to complete a local session to ensure a logout. You must also call the logout operation in Blitz Identity Provider.

If this is not done, then a situation may arise that the user has clicked the button in the application Logout, after which he/she immediately tried to press the button Login, and instead of the expected identification and authentication request, a``Single Sign-On`` was triggered, and the user immediately automatically turned out to be logged in.

To initiate a logout in Blitz Identity Provider, after closing its local session, the application must direct the user to Blitz Identity Provider to the URL to perform the logout, passing as parameters:

Note

The logout call is performed in accordance with the OpenID Connect RP-Initiated Logout 1.0 specification.

• Optional parameter ` ``id_token_hint` - Blitz Identity Provider checks that the id_token of the parameter value is released by it. Valid logout return addresses and logout page design are used according to the configured application with the client_id from the aud field from the id_token.

• Optional parameter ` ``client_id` – valid logout return addresses and logout page design are used in accordance with the specified client_id.

• Optional parameter ` ``post_logout_redirect_uri` is the address of the return to the application after the logout. If the parameter is not set, then redirection to the application after logging out is not performed. If set, it is checked that the value corresponds to at least one allowed return prefix for the application corresponding to the application passed to id_token_hint (the aud field from id_token) or the passed client_id. When passing the post_logout_redirect_uri parameter, it is also necessary to pass the id_token_hint or client_id parameter.

• state s a set of random characters in the form of a 128-bit request identifier. The same value will be returned in the response when redirecting the user to post_logout_redirect_uri.

Example of a logout request:

https://login.company.com/blitz/oauth/logout?id_token_hint=eyJhbGciOiJSUzI1NiJ9.eyJub…n0=.Ckt…sQ&post_logout_redirect_uri=https://app.company.com/redirect_uri&state=342a2c0c-d9ef-4cd6-b328-b67d9baf6a7f

If Blitz Identity Provider completes the logout successfully, it will redirect the user back to the application using the passed URL.

Alternative example of a logout request:

https://login.company.com/blitz/oauth/logout?client_id=test-app&post_logout_redirect_uri=https://app.company.com/redirect_uri&state=342a2c0c-d9ef-4cd6-b328-b67d9baf6a7f

Valid prefixes of the return pages must be registered in the Blitz Identity Provider settings, otherwise an error will be returned during the logout.

Applications connected to Blitz Identity Provider via OIDC can subscribe to notify them of the user’s logout from Blitz Identity Provider. The following features are supported:

• Notification via web browser (Front channel) See OpenID Connect Front-Channel Logout 1.0.

• Notification via the server (Back channel). See OpenID Connect Back-Channel Logout 1.0.

For notification via a web browser, the handler “Link to clear the user’s session in the browser (Front channel)” is registered in the application settings in Blitz Identity Provider. If the handler is registered and the user logged into the application during the session, then when the user calls the Blitz Identity Provider logout through the browser on the user’s logout page through the frame <iframe src= "ссылка">, the application handler specified in the configuration will be called via HTTP GET. If the setting “Add session ID and issuer to the session cleanup link in the browser (Front channel)” was selected, the following parameters will additionally be passed in the request:

• iss is the identifier of the identification provider;

• sid is the user’s session ID.

Example of calling a link to clear a user’s session in the browser (Front channel):

https://app.company.com/front_channel_logout?iss=https://login.company.com/blitz&sid=4ac78c75-b99d-44dc-9304-d2599c829440

In response to the call, the application must terminate the local session and return an HTTP 200 OK` response. Headers should also be included in the response:

Cache-Control: no-cache, no-store
Pragma: no-cache

Note

When implementing an application-side handler for receiving notifications via a web browser, it is necessary to take into account the features of modern browsers that counteract the transfer of cookies when calling handlers in a frame to URL domains other than the URL domain of the parent page:

– in order for the cookie of a third-party site to be transmitted from the frame, the cookie must have the SameSite=None flag and the Secure boxes checked, the X-Frame-Options header must not be transmitted at the time of setting or overwriting the cookie, and the handler itself must be accessible via HTTPS;

– the handler will not be called in some browsers if the page is opened in Hide ID mode.

For notification via the server, the handler “Link to clear the user’s session in the application (Back channel)” is registered in Blitz Identity Provider in the application settings. If the handler is registered and the user logged into the application during the session, then when the user calls the logout, the Blitz Identity Provider server will call the application server via HTTP POST to the application handler specified in the configuration. The logout token logout_token will be passed to the call, which is a JWT token, the body of which contains the following parameters:

• iss is the identifier of the identification provider;

• aud – identifiers of notified applications;

• iat – the time of the refresh token release;

• jti is the ID of the logout token;

• events – constant value http://schemas.openid.net/event/backchannel-logout according to the OpenID Connect Back-Channel Logout 1.0 specification;

• sid is the user’s session ID;

• sub is the user ID.

The refresh token contains either sub (if the setting “Add session ID and issuer to the session clear link in the application (Back channel)” is not enabled) or``sid`` (if the setting “Add session ID and issuer to the session clear link in the application (Back channel)” is enabled).

Example of calling the user session clear service in the application (Back channel):

POST /back_channel_logout HTTP/1.1
Host: app.company.com
Content-Type: application/x-www-form-urlencoded

logout_token=eyJ…J9.eyJ…J9.RV8…Nw

Example of the disassembled body of the logout token with the “Add session ID and issuer to the session clear link in the application (Back channel)” setting disabled:

{
    "iss": "https://login.company.com/blitz",
    "aud": [
        "ais"
    ],
    "iat": 1646979918,
    "jti": "ee75ccd8-ad30-4175-9a61-3ae06c1a6730",
    "events": {
        "http://schemas.openid.net/event/backchannel-logout": {}
    },
    "sub": "3d10f626-ea77-481d-a50bd4a4d432d86b"
}

Example of the disassembled body of the logout token with the “Add session ID and issuer to the session clear link in the application (Back channel)” setting enabled:

{
    "iss": "https://login.company.com/blitz",
    "aud": [
        "ais"
    ],
    "iat": 1646979918,
    "jti": "ee75ccd8-ad30-4175-9a61-3ae06c1a6730",
    "events": {
        "http://schemas.openid.net/event/backchannel-logout": {}
    },
    "sid": "4ac78c75-b99d-44dc-9304-d2599c829440"
}

In response to a call, the application must:

1. Verify the signature of the logout token by analogy with the verification of the identification marker signature.

2. Verify that:

• iss corresponds to the issuer of the deployed system;

• aud includes the ID of the called application;

• the refresh token was released (iat) no earlier than 2 minutes ago;

• sid or sub correspond to the current user sessions.

3. If any checks of the logout token are unsuccessful, then return the code HTTP 400 Bad Request.

4. If all checks are successful, then terminate the user’s local session and return``HTTP 200 OK`` if successful or HTTP 501 Not Implemented if the session failed.

   It is recommended to include headers in the response:

Cache-Control: no-cache, no-store
Pragma: no-cache

[1] (1,2)

Meta is recognized as an extremist organization and is banned in Russia, while the activities of its social networks Facebook and Instagram are also banned in Russia.