How to register the application correctly#

Authentication in OIDC/OAuth terminology 2.0 is the result of the interaction of three parties:

the authorization service (Authorization Server) or the resource provider (Resource Server), which is Blitz Identity Provider;
the client system (Client), which is an application that requests access to a resource (user information and data);
the resource owner (Resource Owner), which is the user, since during authentication he allows access to data about himself.

The first step when connecting an application is to register it as a client system in Blitz Identity Provider. Authentication requests will use and take into account the data specified during application registration:

Web application

application ID (client_id);
application secret (client_secret).
permitted return addresses (lists redirect_uri and post_logout_redirect_uri);
list of requested permissions (scope list);
information about non-standard modes required by the application:
- the application needs to receive a refresh_token – by default, the refresh_token application will not be returned; when selecting this mode, you must additionally specify the required validity period of refresh_token (by default, the validity period of the token will be 1 day, the maximum possible - 365 days);
- the application needs to use a non–standard interaction scenario (for example, Implicit Flow, Hybrid Flow) - by default, the application is allowed to use only Authorization Code Flow;
- the application needs to receive an access token in the JWT format – by default, the access token is provided in the opaque format;
- the application needs to receive an access token (access_token) with a non–standard expiration date - the access token is valid for 1 hour as standard;
a list of additional attributes that Blitz Identity Provider should add to the identification token (additional attributes to be passed as part of id_token);
login mode (login as an individual or as a representative of an organization).

Mobile application

mobile application ID (software_id);
initial access token (Initial Access Token);
application metadata in the form of a JWS token (software_statement).
permitted return addresses (lists redirect_uri and post_logout_redirect_uri);
list of requested permissions (scope list);
non-standard modes required by the application:
- the application needs to receive a refresh_token – by default, the refresh_token application will not be returned; when selecting this mode, you must additionally specify the required validity period of refresh_token (by default, the validity period of the token will be 1 day, the maximum possible - 365 days);
- the application needs to use a non–standard interaction scenario (for example, Implicit Flow, Hybrid Flow) - by default, the application is allowed to use only Authorization Code Flow;
- the application needs to receive an access token in the JWT format – by default, the access token is provided in the opaque format;
- the application needs to receive an access token (access_token) with a non–standard expiration date - the access token is valid for 1 hour as standard;
a list of additional attributes that Blitz Identity Provider should add to the identification token (additional attributes to be passed as part of id_token);
login mode (login as an individual or as a representative of an organization).

Note

When developing a mobile application, you can use both common Initial Access Token` and software_statement for your iOS/Android implementations, and request different sets of Initial Access Token and software_statement for each OS and possibly each edition (phone/tablet) and even the version of the application. For simplicity of further presentation, the text of the document will imply that the mobile application uses one common Initial Access Token and one common software_statement.

When creating a login function in mobile applications using Blitz Identity Provider, it is recommended to take into account the following features:

it is inconvenient for mobile app users to enter their username and password on the authentication Blitz Identity Provider web page every time they log in. Instead, they are more accustomed to using the PIN code of the application or Touch ID/Face ID when re-logging in;
a user can use his/her Blitz Identity Provider account to log in to multiple installations of the same mobile application (for example, log in to an application installed on an iPhone and log in to the same application installed on an iPad). The user should be able to revoke the access rights granted to these application installations to their information in Blitz Identity Provider;
for security reasons, it is undesirable to store the application password (client_secret) on the user’s device (inside the mobile application assembly), which is used to interact the application with Blitz Identity Provider.

To take into account the above features, Blitz Identity Provider provides a number of special mechanisms designed for use by mobile applications.

The recommended scenario for the interaction of a mobile application with Blitz Identity Provider is described in Connecting a mobile app.

Below you will find information on how to determine which allowed return addresses, scope permissions, additional attributes in id_token you can set when registering the application in Blitz Identity Provider.

What permissions can be requested

Permissions (scope in OIDC/OAuth 2.0 terminology) determine which data and which rights to perform which operations the application will receive based on authentication results.

The list of permissions provided in Blitz Identity Provider is shown in the table.

Available permissions (scope)

Permission	Description	Composition of the received attributes
`openid`	A technical authorization indicating that authentication is performed according to the OIDC specification	When requesting this `scope`, Blitz Identity Provider provides the application with an `id_token`. From the `id_token` the application can get the necessary user attributes.
`profile`	Basic user profile data	List of data: `sub` is a unique identifier `family_name` is a surname `given_name` is a given name `middle_name` is a middle name `email` is a business email address `phone_number` is a mobile phone number
`usr_grps`	Getting a list of user groups	`groups` is a list of groups that the user is included in. Each entry in the list includes the following attributes of the organization: `id` is the ID of the group `name` is the name of the group
`native`	Permission to perform end-to-end login to the web application from the mobile application	Relevant only for mobile applications.

What additional attributes can be included in the id_token

There is usually no need to get user attributes directly from the identification token (id_token) – a simpler and recommended way is to get user data through a REST service call.

If you still need to get information about the user from id_token, then the available attributes are selected from the following list.

Possible additional user attributes in id_token

Attribute	Description
`family_name`	Last name
`given_name`	Name
`middle_name`	Patronymic
`email`	E-mail address
`phone_number`	Mobile phone

Tip

Blitz Identity Provider also allows you to place application design elements on the Blitz Identity Provider login page. If you want to create a personalized login page for the connected system, you need to adapt the template for the design of the login page to the design of the connected system. The template for the design of the login page is a zip archive, inside which the HTML framework of the login page and the stylesheet, images, and JavaScript handlers used on the page are recorded.

The prepared archive of the login page theme should be uploaded to Blitz Identity Provider.