Additional authentication method#

Blitz Identity Provider allows you to connect your own developed authentication method. To do this, the system acting as a provider of such an authentication method must:

  • provide an authentication request handler;

  • send the authentication result to Blitz Identity Provider;

  • provide the authentication method applicability verification method Optional.

In Blitz Identity Provider, the developed authentication method must be registered as an external authentication method.

Request handler service#

The interaction of Blitz Identity Provider with the authentication request handler service is performed as follows:

  1. The handler service is a URL for receiving HTTP requests from Blitz Identity Provider. When requesting authentication, Blitz Identity Provider will make a POST request to this address.

    In the request body, Blitz Identity Provider will transmit the following data in JSON format:

    • request ID (id);

    • statements characterizing the user (claims) are optional, only when called as a second factor;

    • the ID of the system that requested the login (rpId);

    • authentication context identifier (loginContextId);

    • request data (request), which includes headers (headers), the user’s IP address (remoteAddress), the method address (uri), a list of cookie (cookies) and the user’s User Agent (userAgent).

    Example of the request body#
    {
    "id": "a9692091-4613-41aa-91d2-9a71a3fc2e07",
    "claims": {},
    "rpId": "_blitz_profile",
    "loginContextId": "4502aa51-f28c-4a64-951c-5ab1e77b1294",
    "request": {
      "headers": {},
      "remoteAddress": "172.25.0.1",
      "uri": "/blitz/login/methods2/outside_test",
      "cookies": {},
      "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:80.0)…"
    }
}

  2. Blitz Identity Provider request must be handled on the side of the external method provider . As a result, the external method must return:

    • If authentication is possible - an HTTP response to be executed in the user’s browser, which, for example, contains the HTML page code or initiates a browser redirect to the required page of the external method.

    • An error if user authentication is impossible.

    Blitz Identity Provider request handling requirements

    • the response should include a cookie setup (on the shared Blitz Identity Provider and external method domain);

    • the cookie name must be pre-registered in Blitz Identity Provider;

    • the session ID generated by an external method must be used as the cookie value.

    Example of an HTTP response with a redirect and cookie setup#
    HTTP/1.1 302 Found
Location: https://login.company.com/blitz/begin?id=a9692091-4613-41aa-91d2
Set-Cookie: Bmr=YTk2OTIwOTEtNDYxMy00MWFhLTkxZDItOWE3MWEzZmMyZTA3; Domain=company.com; path=/blitz; Secure; HttpOnly

    Important

    When passing the external method, the provider must verify that the cookie value for this request has not been changed.

    Recommended return codes:

    HTTP response code

    Response value

    Description of the response

    200

    OK

    Initiating an external method by displaying the page content

    302

    Found

    Initiating an external method through a redirect

    400

    Bad Request

    Required request parameters are missing

    500

    Internal Server Error

    Incoming request handling internal error

Transmission of the authentication result#

After passing the external method, the provider must perform the following actions:

  1. The server part of the provider must call Blitz Identity Provider using the POST method at:

    https://login.company.com/blitz/login/methods/outside/save?methodName=outside\_{name}

    In this request, name is the name of the external method assigned to it in Blitz Identity Provider during registration.

    Request body

    If authentication is successful, the request body must specify:

    • request ID (id);

    • extSessionId is the session ID generated by an external method. The ID must match the value passed in the original cookie request;

    • claims is a list of statements that need to enrich the user’s session. The list may be empty;

    • subjectId is the user ID (only for the first factor; when calling an external method, the user ID cannot be passed as the second factor);

    • loginContextId is the authentication context ID corresponding to the original request.

    Request example#
    POST /blitz/login/methods/outside/save?methodName=outside_test HTTP/1.1
Content-Type: application/json

{
   "id": "426b5139-e4f7-41e6-a206-9503de6f34dd",
   "extSessionId": "YTk2OTIwOTEtNDYxMy00MWFhLTkxZDItOWE3MWEzZmMyZTA3",
   "claims": {},
   "loginContextId": "3ca4d1f0-654a-4665-be98-d105ab6ec35d",
   "subjectId": "2db787c7-6e37-4018-abe9-2bea1011c047"
}

    In case of an error, the request body must specify:

    • id is the request ID;

    • extSessionId is the session ID generated by an external method. The ID must match the value passed in the original cookie request;

    • error is error code;

    • msg is a text description of the error (optional).

    Request example#
    POST /blitz/login/methods/outside/save?methodName=outside_test HTTP/1.1
Content-Type: application/json

{
   "id": "426b5139-e4f7-41e6-a206-9503de6f34dd",
   "extSessionId": "YTk2OTIwOTEtNDYxMy00MWFhLTkxZDItOWE3MWEzZmMyZTA3",
   "error": "not_found",
   "msg": "User not found"
}

    If the authentication results are saved (both successful and unsuccessful), Blitz Identity Provider returns the HTTP 200 OK response.

  2. The browser part of the provider should ensure that the user is redirected back to Blitz Identity Provider. To do this, you need to redirect the browser to:

    https://login.company.com/blitz/login/methods/outside/callback?methodName=outside\_{name}

    In this request, name is the name of the external method assigned to it in Blitz Identity Provider during registration.

Method verification service#

The authentication method applicability verification service is a URL for receiving HTTP requests from Blitz Identity Provider. Prior to the authentication request, Blitz Identity Provider will make a POST request to this address, passing the same data in the body in JSON format as in the authentication request.

As a response, the external method should return JSON with the following attributes:

  • request ID (id);

  • the applicability verification result (result), which takes either true (the method is applicable) or false (the method is not applicable) value;

  • the authentication context ID (loginContextId) corresponding to the request.

If the service returns false as the applicability verification result, then Blitz Identity Provider will not execute the authentication request for this user.