Connecting a mobile app#

Tip

See the description of the interaction between a mobile app 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:

identifier assigned to the application in Blitz Identity Provider (software_id);
initial access token (Initial Access Token);
application metadata (software_statement);
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 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 dynamic registration of a mobile application instance:
- https://login-test.company.com/blitz/oauth/register (test environment)
- https://login.company.com/blitz/oauth/register (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#

An information resource https://appauth.io/, which provides an SDK for iOS/Android, will be useful for integrating mobile applications with Blitz Identity Provider.

Dynamic registration of an application instance#

Prerequisites for dynamic registration of a mobile application instance:

the user must install the mobile application;
the mobile application must have the following data:
- mobile application ID (software_id);
- initial access token (Initial Access Token);
- metadata of the mobile application (software_statement).

The mobile application must send an HTTP request using the POST method to Blitz Identity Provider to the address of the dynamic registration service /blitz/oauth/register.

Parameters must be passed:

mobile application ID (software_id);
metadata of the mobile application (software_statement);
the type of device on which the mobile application is running (device_type) is one of the possible values shown in the table:

Tokens used in Blitz Identity Provider

Device type (`device_type`)	Description
`iphone`	Smartphones of the iPhone family
`ipad`	Tablets of the iPad family
`android_phone`	Smartphones running Android OS
`android_tab`	Tablets running Android OS
`win_mobile`	Devices running Windows 10 Mobile

The dynamic registration request must contain the Authorization header with the primary access token (type – Bearer) issued to the application.

Request example:

POST /blitz/oauth/register HTTP/1.1
Content-Type: application/json
Authorization: Bearer NINxnizbgYYQg94vEd6MjkTPxR3r2s9IAHBO92AszgTIqItY

{
   "software_id": "CSI",
   "device_type": "iphone",
   "software_statement": "eyJ0e…xQ"
}

Upon successful completion of the request, Blitz Identity Provider returns to the instance of the mobile application a list of statements, among which the following are necessary for further work (they must be stored in a secure manner on the user’s device):

ID of the mobile application instance (client_id);
the secret of the mobile application instance (client_secret);
configuration management token (registration_access_token);
configuration management URL (registration_client_uri).

Response example:

{
    "grant_types": [
        "authorization_code"
    ],
    "registration_client_uri": "https://login.company.com/blitz/oauth/register/dyn~CSI~4e6904c5-ef29-4ae5-8d30-99c359b8270f",
    "scope": "openid profile",
    "registration_access_token": "eyJ0e…tw",
    "client_id": "dyn~CSI~4e6904c5-ef29-4ae5-8d30-99c359b8270f",
    "software_id": "CSI",
    "software_version": "1",
    "token_endpoint_auth_method": "client_secret_basic",
    "response_types": [
        "code"
    ],
    "redirect_uris": [
        "com.example.app:/oauth2redirect/example-provider"
    ],
    "client_secret": "3r0tt2OlyeGecWq",
    "client_secret_expires_at": 0
}

User’s initial login#

After receiving the client_id / client_secret pair, the mobile application instance must identify and authenticate the user according to the OIDC/OAuth 2.0 specifications and taking into account the additional specification RFC 7636 Proof Key for Code Exchange by OAuth Public Clients (mobile application when interacting with Blitz Identity Provider should use PKCE).

The identification and authentication scenario includes the following steps:

request for an authorization code;
getting an access token;
getting user data in exchange for an access token.

The user’s initial login to the mobile application must occur within 1 hour after the completion of dynamic registration in the Blitz Identity Provider instance of the mobile application. Otherwise, the client_id will be canceled and a new dynamic registration will be required.

Getting the authorization code#

To authenticate, an instance of the mobile application must call the regular browser of the mobile platform and redirect the user to the URL Blitz Identity Provider of the authorization and authentication service (/blitz/oauth/ae).

When using the browser with a mobile application, the following features should be taken into account:

for iOS, you must use the built-in browser: the SFSafariViewController class or the SFAuthenticationSession class (in-app browser tab pattern);
for Android, you need to use the built-in browser: the Android Custom Tab function (implements the in-app browser tab patter).

Attention

The use of an Embedded browser is not allowed.

The request parameters should be specified:

client_id is the ID of the mobile application instance;
response_type is a response type (takes the value code);
scope is the requested permissions, the openid permission must be passed and the necessary additional scope to receive user data (these scope must be provided with metadata);
redirect_uri is a link to return the user to the application, the link must match one of the values specified in the metadata. In order for Blitz Identity Provider to be able to call the mobile application back after authorization, the following schemes should be used:
- for iOS:
  
  Tip
  
  For an example of implementation, see: openid/AppAuth-iOS
  - option 1 is to use the private-use URI scheme (custom URL scheme). Type of return links: com.example.app:/oauth2redirect/example-provider (CFBundleURLTypes keys are registered in Info.plist);
  - option 2 is to use a URI like``https`` (Universal links). Type of return links: https://app.example.com/oauth2redirect/example-provider (the “Universal links” function is used, URLs are registered in the entitlement file in the application and associated with the application domain). This method is preferable for iOS 9 and above.
- for Android:
  
  Tip
  
  For an example of implementation, see: openid/AppAuth-Android
  - option 1 is to use the private-use URI scheme (custom URL scheme`). Type of return links: ``com.example.app:/oauth2redirect/example-provider (link support using Android Implicit Intents, links are registered in the manifest);
  - option 2 is to use a URI like https (Universal links). Type of return links: https://app.example.com/oauth2redirect/example-provider (available starting from Android 6.0, links are registered in the manifest). This method is preferable for Android 6.0 and higher.
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”/“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;
code_challenge_method is the method for encrypting the request ID, “S256” should be specified;
code_challenge is the encrypted identifier of the request. The request ID (code_verifier) must be stored by the mobile application instance for subsequent transmission to the access token request. The encrypted value is calculated as follows:

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

Example of a request to receive an authorization code (authentication and access token with openid and profile permissions were requested, PKCE is used):

https://login.company.com/blitz/oauth/ae?scope=openid+profile
&access_type=online&response_type=code
&state=342a2c0c-d9ef-4cd6-b328-b67d9baf6a7f
&client_id=dyn~CSI~4e6904c5-ef29-4ae5-8d30-99c359b8270f
&code_challenge_method=S256&code_challenge=qjrzSW9gMiUgpUvqgEPE4
&redirect_uri=https%3A%2F%2Fapp.example.com%2Foauth2redirect%2Fexample-provider

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

https://app.example.com/oauth2redirect/example-provider?code=f954nEzQ08DXju4wxGbSSfCX7TkZ1GvXUR7TzVus8fGnu4AUl-YIosgax-BLXMeQQAlasD6CN2qG_0KXK5NIjARoKykhuR9IpbuzqeFxS0&state=342a2c0c-d9ef-4cd6-b328-b67d9baf6a7f

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

Getting tokens by an application instance#

After receiving the authorization code, the mobile application instance must exchange it for tokens. To do this, the instance must form a POST request to the URL to receive the token. The request must contain the header Authorization with the value Basic {secret}, where secret is``client_id:client_secret`` (for example, dyn~CSI~4e69…Wq) in Base64 format.

Example of a header:

Authorization: Basic ZHluOkNTSTo…dx

The request body must contain the following parameters:

code is the value of the authorization code that was previously received by an instance of the mobile application from Blitz Identity Provider;
grant_type is the value authorization_code;
redirect_uri – must be the same value that was specified in the request to receive the authorization code;
code_verifier is the request ID generated by the mobile application instance when requesting an authorization code.

Request example:

POST /blitz/oauth/te HTTP/1.1
Authorization: Basic ZHluOkNTSTo…dx
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code&code=FLZHS…GU
&redirect_uri=https%3A%2F%2Fapp.example.com%2Foauth2redirect%2Fexample-provider
&code_verifier=M25iVXpKU3puUjFaYWg3T1NDTDQtcW1ROUY5YXlwalNoc0hhakxifmZHag

An access token and an identification token are returned in response.

Example of a response with successful execution of the request:

{
    "id_token": "eyJhb…J9. eyJub…0=.Ckt_dr…sQ",
    "access_token": "dO-xym…BE",
    "expires_in": 3600,
    "scope": "openid profile",
    "token_type": "Bearer"
}

After receiving the access token, the instance of the mobile application becomes associated with the user account. It is recommended that the mobile application prompts the user to set a PIN code or enable Touch ID/Face ID.

Besides, using the received access token, the application can request user data.

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.

Example of an error response:

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

Possible errors when calling /oauth/te match RFC 6749 and are described here.

User re-login#

Each time a user logs into an instance of a mobile application, if Internet access is available from the device, the user should be authenticated by calling the Blitz Identity Provider service. In particular, each time you log into an instance of a mobile application, you need to check the user’s PIN code or Touch ID/Face ID, then extract the client_id / client_secret securely stored on the device and make a request to Blitz Identity Provider to re-log the user. Use the access token received in response from Blitz Identity Provider to get up-to-date user data.

The request to Blitz Identity Provider to re-log in must be made by the POST method to the URL to receive the token (/oauth/te). The request must contain the header Authorization` with the value Basic {secret}, where secret is the client_id:client_secret of the mobile application instance in Base64 format.

The request body must contain parameters:

grant_type is the value client_credentials;
scope is a list of permissions requested by the instance of the mobile application.

Request example:

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

grant_type=client_credentials&scope=profile

The response returns an access token and information about this token.

Example of a response with successful execution of the request:

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

Using the received access token, an instance of the mobile application can request up-to-date user data from Blitz Identity Provider in order to visualize or update this data in the device if necessary.

If a user in Blitz Identity Provider revoked the authorization right in Blitz Identity Provider from an instance of a mobile application, the mobile application instance will receive an error as a result of calling Blitz Identity Provider.

Example of an error response:

{
    "error": "invalid_client",
    "error_description": "Client authentication failed…"
}

Possible errors when calling /oauth/te match RFC 6749 and are described here.

User switching or logging out#

If the mobile application has a user exit or change function, then when the user calls such a function, the mobile application must also call Blitz Identity Provider and delete the client_id / client_secret pair released for this instance of the mobile application. If this is not done, then when the user logs out of the mobile application, the user in the web application Blitz Identity Provider Security Settings will still see that the mobile application is still linked to his account.

Note

The standard address looks like this: https://login.company.com/blitz/profile.

To delete the client_id/ client_secret pair released for an instance of a mobile application from Blitz Identity Provider, the mobile application must send to Blitz Identity Provider a DELETE request to the configuration management URL (registration_client_uri) received and stored by the mobile application when calling the dynamic registration in Blitz Identity Provider instance of the mobile application. The request must contain the header Authorization with the value Bearer {registration_access_token}, where registration_access_token is a configuration management token, also received and stored during the dynamic registration process. The request does not require specifying parameters.

Request example:

DELETE /blitz/oauth/register/dyn~CSI~4e6904c5-ef29-4ae5-8d30-99c359b8270f HTTP/1.1
Authorization: Bearer eyJ0e…tw

If, after deleting the client_id / client_secret pair, the mobile application immediately requests a new client_id / client_secret pair and requests user login, then if the previous login was performed in the same browser session, then SSO will work and the user will automatically log in with the previous account. This is usually an undesirable behavior to log in immediately after logging out, since it is expected that the user will want to log in with a different account. Therefore, after logging out, it is recommended to request a new login using one of the following methods:

When requesting an authorization code, specify the additional parameter prompt=login in the request. Then Blitz Identity Provider will prompt the current user to authenticate, even if the Blitz Identity Provider session is active. The user can also select Change account on the login page to log in with a different account.
When requesting an authorization code, specify the additional parameter prompt=select_account in the request. So Blitz Identity Provider will immediately prompt the user to select an account from among the remembered ones or log in with a new account. The user does not have to additionally press the button Change account on the login page.

Opening web resources from the application#

In some mobile applications, developers may need to provide a function for opening web resources that also require user identification/authentication and use Blitz Identity Provider (end-to-end authentication mode) for this purpose.

When accessing a web resource, a user logged into a mobile application may encounter a situation that Blitz Identity Provider will repeatedly require him to complete identification/authentication in a web resource as a result of a request by the corresponding web application for user identification/authentication in Blitz Identity Provider. To prevent this from happening, the mobile application can immediately request Blitz Identity Provider to receive an access token (access_token) for a special permission (scope) with the name native immediately before calling the web resource.

You can get an access token using the method described in User re-login or Getting tokens (if the application has a refresh_token).

Request example:

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

grant_type=client_credentials&scope=native

In response, not only the access token and information about this token are returned, but also a special attribute – the end-to-end login marker css (cookie short session).

Example of a response with the css attribute:

{
    "access_token": "dO-xym…BE",
     "css": "nUngQ…LA",
    "expires_in": 3600,
    "scope": "native",
    "token_type": "Bearer"
}

After that, the mobile application can open a web resource. At the same time, in the launched web browser, the mobile application must first set a cookie with the following parameters:

cookie name – css;
cookie domain – login.company.com;
cookie path – /blitz;
flags HTTPOnly=true and Secure=true;
the cookie value is the value received in the css parameter when receiving an access token from Blitz Identity Provider on the scope named native.

If the launched web resource initiates identification (authentication) in Blitz Identity Provider within 300 seconds from the moment of launch, and the cookie was correctly set, then Blitz Identity Provider, at the request of the web application, will automatically perform end-to-end identification and authentication of the user under the account with which the user previously logged into the instance of the mobile application that invoked the web resource.

Login to the application using a QR code#

QR code login can be used in Blitz Identity Provider as the first authentication factor (an alternative to entering a username/password). When choosing this login method, Blitz Identity Provider generates and displays to the user a QR code in which the login request is encoded (Figure 6). The validity period of the QR code is limited, and the generated request is a one-time request. Upon expiration of the displayed QR code, the user is given the opportunity to request the display of a new QR code.

The link encoded in the QR code looks like: QR_URL?code=b0671081-cb73-4839-8bc1-8cf020457228, for example:

https://login.company.com/blitz/login/qr?code=b0671081-cb73-4839-8bc1-8cf020457228

The QR_URL value can be configured so that if a smartphone is pointed at a QR code using a standard camera application, the user can see a web page with instructions on how to get the correct mobile application to download QR codes or the ability to call a suitable mobile application via Universal Link.

The QR code login process on the mobile application side consists of the following steps:

Before photographing the QR code with a mobile application, the user must be logged into the mobile application using Blitz Identity Provider, and the mobile application must receive a valid access token from scope named blitz_qr_auth (permission to log in using a QR code) in Blitz Identity Provider.
When photographing a QR code, the mobile application should discard the QR_URL value (the application does not need it and should be ignored) and the application should read the value of the code parameter passed in the link.
After reading the QR code, the mobile application should call the Blitz Identity Provider service to receive information about the login request, passing the value of the received code to the service, as well as the header with the access token and the header of the user’s current language.

Example of a call:

curl --location --request GET 'https://login.company.com/blitz/api/v3/auth/qr/b0671081-cb73-4839-8bc1-8cf020457228' \
--header 'Accept-Language: ru' \
--header 'Authorization: Bearer eyJhb…tA'

The response will return a JSON containing information about the IP address, operating system and browser of the device on which the user is trying to log in using a QR code, as well as the name of the application that the user is trying to log in to.

Example of a successful response:

{
    "ip": "83.220.238.103",
    "rp_name": "User profile",
    "ip_city": "Москва",
    "browser": "Chrome 109",
    "ip_state": "Москва",
    "os": "macOS 10.15.7",
    "ip_lng": "37.6171",
    "device_type": "pc",
    "ip_lat": "55.7483",
    "ip_country": "Россия",
    "rp_id": "\_blitz_profile",
    "device_name": "macOS Big Sur (11)",
    "ip_radius": "20",
    "device": "PC"
}

Besides, the user will be shown a screen in the web page that a login confirmation is expected.

The user in the mobile application needs to display the application name (rp_name), IP address (ip), geodata (ip_country, ip_state, ip_city - a text description of the address or show on the map at the coordinates ip_lat, ip_lng), the device used (device_name), browser (browser).

Possible values of device_type now: kindle, mobile, tablet, iphone, windowsPhone, pc, ipad, playStation, unknown. You can use them to visualize a message, or you can simply output the device name as a text string from device.

Example of a response with an invalid access token:

{
    "type": "security_error",
    "error": "bad_access_token",
    "desc": "expired_access_token"
}

Example of a response with an expired QR code:

{
    "type": "process_error",
    "error": "qr_session_expired",
    "desc": "Error while getting QR authentication session"
}

Example of a response with an invalid code:

{
    "params": {},
    "desc": "Error while getting QR authentication session",
    "error": "qr_session_not_found"
}

An example of a response when calling from an already used QR session (when the login has already been confirmed or rejected):

{
    "type": "process_error",
    "error": "qr_session_already_completed",
    "desc": "Error while getting QR authentication session"
}

The mobile application should display the login information received from Blitz Identity Provider JSON to the user, as well as the choice of action: “Allow” or “Reject”. In the case of “Reject”, request the reason for the rejection (“Login caused by error” or “I did not request login”).
Depending on the user’s decision, the mobile application should call the Blitz Identity Provider service to confirm or deny login. An access token with scope named blitz_qr_auth must be used during the call.

Example of a call when confirming login:

curl --location --request POST 'https://login.company.com/blitz/api/v3/auth/qr/5e20b01e-5c7c-4101-8292-98e6865c7bfb/confirm' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhb…cQ'

If successful, HTTP 204 No Content without body will be returned. The user will also log into the application.

If the code is expired, it will be returned:

{
    "type": "process_error",
    "error": "qr_session_expired",
    "desc": "Error while confirming QR authentication session"
}

If the code does not exist, it will return:

{
    "params": {},
    "desc": "Error while confirming QR authentication session",
    "error": "qr_session_not_found"
}

Example of a response with an invalid access token:

{
    "type": "security_error",
    "error": "bad_access_token",
    "desc": "expired_access_token"
}

An example of a response when calling from an already used QR session (when the login has already been confirmed or rejected):

{
    "type": "process_error",
    "error": "qr_session_already_completed",
    "desc": "Error while getting QR authentication session"
}

An example of a call when login is rejected:

curl --location --request POST 'https://login.company.com/blitz/api/v3/auth/qr/845f2334-fa6b-40c0-9a71-f57997166e39/refuse' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhb…bQ' \
--data-raw '{
"cause_id": "mistake",
"desc": "Вход вызван по ошибке"
}'

If login is rejected, you need to pass JSON with the cause_id attribute in the request body. It is recommended that if the user rejects the login, ask the reason. If the user reports that he “changed his mind” (or “caused the login by mistake`), then fill in cause_id=mistake. But if the user reports that he did not initiate the login, then fill in cause_id=unauthorized. The desc parameter is optional – you can specify any text string.

If the call is successful, HTTP 204 No Content without body will be returned. The user will also be shown an error screen:

If the code is expired, an error will be returned:

{
    "type": "process_error",
    "error": "qr_session_expired",
    "desc": "Error while refusing QR authentication session"
}

If the code does not exist, it will return:

{
    "params": {},
    "desc": "Error while refusing QR authentication session",
    "error": "qr_session_not_found"
}

Example of a response with an invalid access token:

{
    "type": "security_error",
    "error": "bad_access_token",
    "desc": "expired_access_token"
}

An example of a response when calling from an already used QR session (when the login has already been confirmed or rejected):

{
    "type": "process_error",
    "error": "qr_session_already_completed",
    "desc": "Error while getting QR authentication session"
}