Invoking the auxiliary application at the moment of login#

At the moment of logging in, Blitz Identity Provider can invoke an auxiliary application that will perform additional operations (for example, show the user an information message or request data updating), after which it will return the user to Blitz Identity Provider for subsequent logging into the target application.

From a technical point of view, the auxiliary application must perform the following actions:

handle a request to open the auxiliary application,
return the user to Blitz Identity Provider after handling is completed.

Request to open the application#

A request to invoke the auxiliary application is received as follows:

The auxiliary application is accessed by redirecting the user to the link provided by the application. The link will contain the authorization code (code) as an option.
Example of a link to initiate a request#
```
https://<app_hostname>/?lang=ru&theme=default&code=0Tj…qw
```
The application must exchange the authorization code for an access token according to the OAuth 2.0 specification. The access token will be used to obtain the session ID to return the user to Blitz Identity Provider, as well as user data if necessary.

Example
Request
curl -k -d "grant_type=authorization_code&redirect_uri=https%3A%2F%2Fapp.company.com%2F&client_id=app&client_secret=EW…l0&code=0Tj…qw" -X POST https://login.company.com/blitz/oauth/te
Received access token
{ "access_token": "ey…J9.ey…n0.Wa…Pw", "token_type": "Bearer", "expires_in": 3600, "scope": "profile" }
Important

The auxiliary application must be pre-registered in Blitz Identity Provider, taking into account the following features:
- a predefined return URL must be specified, which should then be used to receive the token;
- the default permissions (scope) must be configured, they determine the amount of data received by the auxiliary application.

Returning the user to Blitz Identity Provider#

The user is returned to Blitz Identity Provider as follows:

After completing the necessary actions (for example, showing the user an informational message), the auxiliary application should return the user to Blitz Identity Provider. To do this, you need to decode the received access token, received in JWT format, and extract from it the statement with the user’s session (sessionId).

Example of the decoded access_token body#

{
    "scope": "blitz_api_user blitz_api_user_chg blitz_api_usec_chg",
    "jti": "kfP…jA",
    "client_id": "app",
    "exp": 1631026605,
    "sessionId": "ce9f3109-ac79-46b4-b277-099ff1aa1ff0",
    "iat": 1631023005,
    "sub": "8b970179-e141-43b9-b9d5-25997be99261",
    "aud": [
        "app"
    ],
    "crid": "u9th2LzMXZdwb3rRmI3Paw",
    "iss": "https://login.company.com/blitz"
}

After decoding the access token, the auxiliary application must make a POST request to the URL of the authentication completion handler Blitz Identity Provider /login/pipe/save/<sessionId>. The request body may contain a set of statements (claims) to be added to the user’s session, or error information (error).
Request example#
```
curl -v --location --request POST 'https://login.company.com/blitz/login/pipe/save/ce9f3109-ac79-46b4-b277-099ff1aa1ff0' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic Z2…ww' \
--data-raw '{"claims":{"org_id":"12345678"}}'
```
If successful, Blitz Identity Provider will return HTTP 204 No Content. After receiving it, the auxiliary application should return the user’s browser to the address /login/pipe/callback so that the user completes logging in to the target application.
Example of a redirect link#
```
https://login.company.com/blitz/login/pipe/callback
```