Adding a new OAuth authorization provider

Registering the application on the authorization server

Recommendation. Before connecting a new specific OAuth authorization provider, it is useful to practice and master the process by connecting Yandex.ID

The application (communication system) must be registered with the authorization provider and obtain identifiers that will be used later in interaction between the application and the authorization server. Usually, within the application, among other data, 'redirect_uri' and 'scope' must be passed.

redirect_uri

'redirect_uri' — a URL or list of several URLs to which redirects are allowed after successful authorization. Specify "https://<URL_DOMAIN>/oauth/receiver", or simply "https://<URL_DOMAIN>". Note that not all providers allow redirects to unencrypted http, but some do. As URL_DOMAIN, specify the DNS name or address by which all users without exception reach the system. This can be either a public name or a name known to the internal network DNS. In the authorization provider entity, the URL must be specified as "https://<URL_DOMAIN>/oauth/receiver". It is mandatory that at least one of the URLs submitted for registration match it or be a prefix of it.

{
    ...
    "redirect_uri": "https://pbx.incoplax.com/oauth/receiver",
    ...
}

scope

'scope' — the required amount of user information. The set of parameters provided by the authorization server must be determined, and the list corresponding to the most minimal authorization selected. Each authorization provider has a unique set of options. After selecting the required values, they should also be set in the authorization provider entity. For example, for Yandex.ID this is:

{
    ...
    "scope": [
      "login:info",
      "login:email"
    ],
    "optional_scope": [],
    ...
}

The main thing when choosing a scope is that the authorization service provides a unique login. By login the communication system associates authorization with its own user account or may even create this user. If there is no explicit login field, it must be composed uniquely from what is provided. To do this, a service token authorization script set in the master domain parameters (iam_token_svcscript_code) must be created and used, and in it, from the information provided by the authorization server, select values and form a unique login, assigning it to the script variable "login".

Other options

If there are many domains and the authorization server distinguishes domain orientation within the communication platform, then either the domain name or some other parameter must be returned by which the communication platform domain the user belongs to can be unambiguously determined. If not, the 'default_domain' property must be specified in the authorization provider entity. Implicit domain determination must also be performed in the service token authorization script (iam_token_svcscript_code), assigning it to the script variable "domain".

{
    ...
    "default_domain": "users.pbx.incoplax.com",
    ...
}

Among non-standard request options, it may be necessary to specify that access_token is passed in JWT format. Some providers do this by default, and some only by option.

Registration result

After registering the application on the authorization server, client_id and client_secret values are provided. They should be entered into the authorization provider entity:

{
    ...
    "client_id": "1ecf9d9aaf3248...",
    "client_secret": "c46b732a8...",
    ...
}

Filling the provider entity

Based on the registration results, an authorization provider entity is created (/rest/v1/model/oauth/Providers). At this stage the 'client_id', 'client_secret', 'default_domain', 'scope', 'optional_scope' properties are filled in the authorization provider entity.

Parameters for matching with the platform user account

Next, in the authorization provider entity, specify which fields in the REST server response of the authorization system correspond first to the user login, second to the user name, third to the domain, and fourth to other fields (email, etc.). Some other values may also be applied and get into the user entity (when creating or updating its account). For example, for Yandex.ID the following is set in the authorization provider entity:

{
    ...
    "query_login": [
      "login"
    ],
    "query_name": [
      "name",
      "real_name"
    ],
    "query_email": [
      "email",
      "emails/0"
    ],
    "query_domain": null,
    "query_id": null,
    "query_info": null,
    ...
}

Having received the REST server response, the corresponding value is parsed and matched according to the specified rules ('query_*' fields). The results go into the authorization request entity, and from there either directly into the matching mechanism or into the service token authorization script, where they can be additionally transformed.

Basic provider properties

Also specify basic parameters in the provider entity (their description is available in the reference https://vendor.incoplax.com/docs/era/latest/api/rest/v1/model/endpoints/oauth/providers.html). For example, for Yandex.ID this is:

{
    ...
    "id": "0c04b29b-0184-31f2-2e5e-3cecef28bebf",
    "key": "yandex",
    "label": "Sign in with Yandex ID",
    "enabled": true,
    "order": null,
    "icon_uri": "/.well-known/oauth/icons/ya.png",
    "dialect": "oauth",
    ...
}

The ya.png icon should be placed manually in the ':SYNC/common/www/.well-known/oauth/icons' directory and its path specified in the 'icon_uri' property.

Other entity properties are discussed further in the context of the multi-step authorization process.

Authorization process

1. Redirect to the authorization server

When authorization providers are enabled, corresponding buttons appear in the login form. The user can choose standard authorization or go through an external authorization provider. If all users must be directed to an external authorization provider, direct login-password authorization should be blocked. This can be done, for example, by activating the external authorization script in the master domain (iam_general_svcscript_code), in which the variable "result" is assigned the value 0 (authorization prohibited).

First, according to the procedure, clicking the external authorization button redirects to the authorization server specified in 'uri_authorize'. For Yandex.ID this is:

{
    ...
    "uri_authorize": "https://oauth.yandex.ru/authorize",
    ...
}

When redirecting to the authorization server, the following standard OAuth parameters are substituted and passed in the URL:

    response_type = code
    client_id = <Account's client_id>
    scope = <Account's scope>
    optional_scope = <Account's optional_scope>
    redirect_uri = <Account's redirect_uri>
    state = <Unique request identifier>

The parameter response_type = code is a constant defining the standard path: the authorization server will generate a code and pass it as an additional parameter during further redirection, and the token will then be obtained by the code.

The 'state' parameter from the redirect URL is generated by the platform for a specific external authorization request and serves to match different parts of the process across redirects. Depending on the 'state_mode' parameter from the entity, the 'state' parameter from the URL may be substituted either simply as another parameter or included as a parameter specifically in redirect_uri. This depends on whether the authorization server automatically forwards the 'state' parameter during redirection and whether it allows specifying 'redirect_uri' with an extension relative to the one set at registration or requires strict conformance. For example, for Yandex.ID:

{
    ...
    "state_mode": "param"
    ...
}

If necessary, set additional parameters to customize a specific authorization provider. They are substituted into the redirect URL unchanged. For example, for Yandex.ID:

{
    ...
    "params_authorize": {
      "display": "popup",
      "force_confirm": "yes"
    },
    ...
}

At this step control of the authorization process is passed to the authorization server, and a request entity in the 'initial' state is added to the /rest/v1/model/oauth/Requests collection.

2. Authorization on the external OAuth server

The user web page displays the authorization window of the connected OAuth server, where the user is asked to enter login and password and possibly agree to provide the application with certain user information (that same scope). On success the authorization server redirects back to the application page specified in 'redirect_uri'.

If the user has already authorized and still has an active session on the authorization server, this step proceeds invisibly, and the authorization server immediately redirects back.

3. Back redirect after authorization, obtaining the access token

Control returns to the page at the above 'redirect_uri'.

Accordingly, the user web page again contacts the communication platform web server (this is /oauth/receiver). The web server, processing the received request with the passed 'state' parameter (the identifier of the specific authorization request in the communication platform) and 'code' (the identifier of the authorization session on the authorization server), contacts the authorization server for an access token and passes the 'client_secret' value among the POST request parameters.

Since this is a server-side request, the OAuth protocol excludes the possibility of intercepting client_secret externally by a specific user.

The request to the authorization server for an access token is made to the address specified in the 'uri_token' property. For example, for Yandex.ID this is:

{
    ...
    "uri_token": "https://oauth.yandex.ru/token",
    ...
}

The POST request is made passing the following parameters

   grant_type = authorization_code
   code = <Authorization code from redirected URL>
   client_id = <Account's client_id>
   client_secret = <Account's client_secret>
   redirect_uri = <Account's redirect_uri

The parameter grant_type = authorization_code is a constant; this is the standard mechanism (and the platform in the current version supports only it).

On success the authorization server returns 200 and a JSON body with the access token.

4. Obtaining user information

The communication platform web server makes a GET request to the REST server of the authorization system, substituting the header

Authorization: OAuth <Access Token>.

The request is made to the address specified in the 'uri_info' property:

{
    ...
    "uri_info": "https://login.yandex.ru/info?format=json",
    ...
}

The response comes in JWT format. If the communication platform web server detects a hash verification failure (in the log journal: "Invalid JWT signature"), the 'verify_hash' property can be set in the provider entity to disable JWT hash verification:

{
    ...
    "verify_hash": false,
    ...
}

The communication platform web server unpacks the JWT and parses the target values according to the 'query_*' rules. On success it changes the state ('authorized') and the authorization request composition, filling it with the parsed content of the received response.

This completes the session of interaction with the authorization server. Next, binding to the user account and creating a session in the communication platform occur.

5. Redirect to the linking page

The user web page is redirected to /oauth/enter/<RequestId>.

The 'login_mode', 'register_user_enabled', 'update_user_enabled' properties determine how the authorization server response is linked to the system user account.

The value login_mode=auto uses the specified 'default_domain' (or the domain explicitly issued by the authorization server and parsed with 'query_domain'), searches by matching the 'login' value issued by the authorization server in this domain (parsed with 'query_login'), and creates a web server session.

  • If a user with this login is not found in this domain, then with permission set simultaneously in the provider entity property 'register_user_enabled' and in the domain parameter 'self_register_allowed', an account may be created there. When creating, the user account template specified in the domain parameter 'self_register_template' is used.

  • If the user account is found, then with permission set in the provider entity property 'update_user_enabled' it is updated based on the current user information provided by the authorization server and parsed by the 'query_*' rules.

The value login_mode=script uses the token authorization script (taken from the iam_svcscript_code property or, if empty there, from the master domain parameter 'iam_token_svcscript_code'). The first parameter receives the authorization request identifier, the second the JSON representation of the authorization request entity, the third the JSON representation of the authorization provider entity, and the fourth the client IP address and port. For successful linking and authorization, the script assigns the value 1 to the variable "result", and assigns corresponding values to the variables "login" and "domain", by which the system can then find the user account. If necessary, such an account must be created during script execution. Login and domain can also be formed arbitrarily based on user information provided by the authorization server and stored in the authorization request (the second script parameter).

6. Session creation

As a result, a response is sent to the redirected request — the main page with applications, in which a session cookie is set. All subsequent requests are made by the web page passing the session cookie.

Some additions

If the process is unexpectedly interrupted somewhere, the authorization request is automatically deleted from the /rest/v1/model/oauth/Requests collection after a few seconds.

The described scenario lacks a basic check of whether the user is already authorized, whether the authorization server cookie is already present in the request, and whether only reading information and linking is needed without redundant redirects. As a rule in this case redirects pass through without displaying the login and password window, and this remains invisible to the user. However, this point can be improved in the communication platform.