oauth/Providers

Overview

Collection of OAuth 2.0 authorization and OpenId Connect 1.0 identification providers.

Created by the ws microservice. Used when serving requests to the /oauth/…​ Endpoint group.

Based on this collection, alternative external authorization buttons are displayed in the root web application login form. Icons and labels are taken from the entity.

The collection is contained only in the master domain.

Storage type: runtime.

Table 1. Class fields
Field Description

id

Provider identifier

key

OAuth authorization provider key by which the entity is discovered when a request arrives at the URL '/oauth/redirect/<PROVIDER_KEY>'.

Example:
"yandex"

enabled

OAuth authorization provider switch. Determines appearance in the list of alternative authorization methods in the root web application login form.

A disabled provider cannot be used for redirection to the external authorization server.

login_mode

Mode for linking an external account to an internal one. Variants:

  • auto - automatic linking. Based on data from the external server, forms an internal login in the format "oauth.<ProviderKey>.<ExternalLogin>", replacing all unsuitable characters. According to the "register_user_enabled" and "update_user_enabled" settings, it can perform automatic registration in the domain and update local user account properties.

  • script - linking using the token authorization script (set either by the iam_svcscript_code property or in the master domain 'iam_token_svcscript_code' setting). The script determines the linking logic. The authorization request entity and the user properties set in it, provided by the authorization server, must be used to determine, verify, and create the user account. On success the script assigns "result" = 1, "login", "domain" variables.

Default "auto".

iam_svcscript_code

Separate linking script (service script code in the master domain). Applies with login_mode=script.

If the script is not specified, the common script set by the master domain 'iam_token_svcscript_code' parameter is used.

Passed parameters: 1. identifier of the current authorization request (xref:api:rest/v1/model/endpoints/oauth/requests.adoc'/rest/v1/model/oauth/Requests'). 2. JSON authorization request entity. 3. JSON authorization provider entity (xref:api:rest/v1/model/endpoints/oauth/requests.adoc'/rest/v1/model/oauth/Providers'). 4. Client IP address and port.

The script determines the linking logic. If the linking logic is non-trivial, the normal mode is unsuitable and script linking mode should be used. The script must use the authorization request entity and the user properties set in it. User information is entered into the request after the authorization server response in the previous process step. If the authorization server does not return a login explicitly used for linking, it must be generated uniquely in the script. If the script does not return a domain and different users must be linked to different domains, the domain must be determined in the script. Create the user account in the domain if necessary. On success the script assigns "result" = 1, "login", "domain" variables.

For authorization to complete successfully, a user account with the specified login must exist in the specified domain after the script completes. By default the master domain common script is used; if absent, authorization fails.

register_user_enabled

Switch for automatic user account creation mode.

When using "auto" linking mode, it also checks the setting "self_register_mode" in the destination domain and uses "self_register_template" as the template for the created account.

When using "script" mode, checking this setting is delegated to the token authorization script and may not be used by it.

Default "true".

update_user_enabled

Switch for automatic update of fields (name, email) in the local user account based on data received from the external server.

When using "script" mode, checking this setting is delegated to the token authorization script and may not be used by it.

Default "true".

icon_uri

URL of the icon displayed on the alternative authorization button in the root web application login form.

Icons can be placed in the ':SYNC/common/www/.well-known/…​' directory and are available via the URL path: '/.well-known/…​'. This is a justified alternative to placement in the static public resources directory 'www' located in the system modules folder '/usr/lib/era/era_ws/priv/www', since it is automatically synchronized between all servers and is resistant to system updates."

Example:
"/.well-known/resources/oauth/providers/yandex.swg"

label

Text displayed on the alternative authorization button in the root web application login form.

Example:
"Sign in with Yandex"

client_id

The 'client_id' value issued by the external platform when the communication service was registered on it. Used according to the OAuth 2.0 protocol to link the external authorization process with the account registered on the external platform.

client_secret

The 'client_secret' value issued by the external platform when the communication service was registered on it. Used according to the OAuth 2.0 protocol in server-to-server interaction. Secret: on reading — ciphertext; the plain value is not exposed via the API, decrypted by the service when used (Encryption and keys).

redirect_uri

Full URL for reverse redirection from the external server to the system after authorization. As a rule it is registered on the external platform and must match.

The path to the '/oauth/receiver' resource must always be set unchanged, since this is the single page receiving the reverse redirect.

Example:
"https://pbx.incoplax.com/oauth/receiver"

keepInitialHost

Switch for preserving the original URL ("Schema://Host") after authorization. Default false - after authorization the scheme and host from 'redirect_uri' remain.

uri_authorize

Full URI of the external authorization server to which redirection is made for authorization. Displays the authorization page. According to the OAuth 2.0 protocol it is supplemented with the necessary GET parameters and substituted into the Location header. After successful authorization the external server redirects back to 'redirect_uri', passing 'code' and 'state' in GET parameters.

Example:
"https://oauth.yandex.ru/authorize"

uri_token

Full URI of the external authorization server where the server-to-server request is made to exchange the received code for a data access token. According to the OAuth 2.0 protocol a POST request is made to it with the necessary parameters, including the 'code' received during authorization and the 'client_secret' obtained during system registration on the external platform.

Example:
"https://oauth.yandex.ru/token"

certificate_pem

Macro path to a PEM file with a chain of confirming certificates (public keys). The PEM file content itself may be set directly as the value. By default the list of trusted root certificates from the system environment (in the container) is used.

Example:
":SYNC/common/cert/oauth_myprovider1/ca.pem"

Secret: on reading — ciphertext; the plain value is not exposed via the API, decrypted by the service when used (Encryption and keys).

scope

Required data scope. List of sections corresponding to the external authorization system. Substituted as the 'scope' parameter in the 'uri_authorize' authorization server URL. Cannot exceed what was specified when registering the communication system on the external platform.

May remain empty; then the 'scope' parameter is not sent when redirecting to the authorization server, and as a rule the authorization server defaults to the full set of sections specified at registration.

Example:
["login:info", "login:email"]

To arrange the OpenId Connect 1.0 identification process, specify a single value in the scope list: "openid".

optional_scope

Optional data scope. List of sections corresponding to the external authorization system. Substituted as the 'optional_scope' parameter in the 'uri_authorize' authorization server URL. If the authorization server supports optional scope, the user can determine during authorization which optional sections they grant the communication system access to.

May remain empty; then the 'optional_scope' parameter is not sent when redirecting to the authorization server.

Example:
["login:email", "login:avatar"]

params_authorize

Object with additional parameters added to the authorization server redirect URL. Empty by default.

Example:
{
  "display": "popup",
  "force_confirm": "yes"
}

state_mode

State specification mode. Possible variants:

  • param - added as another parameter of the authorization server redirect URL. Used by default. Assumes the authorization server passes the 'state' parameter unchanged on reverse redirect.

  • uri - added as a parameter in redirect_uri. This may be required by authorization servers that do not pass 'state' on reverse redirect and allow incomplete matching of the 'redirect_uri' parameter to the one registered on the external platform.

The 'state' parameter is needed to match the reverse redirect with the 'oauth/Requests' entity.

uri_info

Full URI of the external data server providing information about the user external account by the 'access_token' token.

Example:
"https://login.yandex.ru/info"

query_id

List of search queries for discovering the user identifier in JSON content received from the external data server (external login). The result is substituted into the 'oid' field of the corresponding 'oauth/Requests' request and can be used in the token authorization script.

The query format is described in the "Search queries" section.

When several strings are specified in the list, they are applied sequentially to the source content until a value is successfully found. Several variants can be used to process both the JSON response from the data server and the JWT response or parameter from the identification server.

The identifier search can also be performed after obtaining the access token in the parsed JWT content. Thus the list should consist of several search strings, one resolving in the first case and the second after receiving the response from the data service.

Example:
["sub","oid"]

query_login

List of search queries for discovering/building the user login in JSON content received from the external data server (external login). The result is substituted into the 'login' field of the corresponding 'oauth/Requests' request and can be used in the token authorization script.

The query format is described in the "Search queries" section.

When several strings are specified in the list, they are applied sequentially to the source content until a value is successfully found. Several variants can be used to process both the JSON response from the data server and the JWT response or parameter from the identification server.

Example:
["login"]

query_name

List of search queries for discovering/building the user name in JSON content received from the external data server. The result is substituted into the 'name' field of the corresponding 'oauth/Requests' request and can be used in the token authorization script.

The query format is described in the "Search queries" section.

When several strings are specified in the list, they are applied sequentially to the source content until a value is successfully found. Several variants can be used to process both the JSON response from the data server and the JWT response or parameter from the identification server.

Example:
["name", "full_name"]

query_email

List of search query strings for discovering the user email address in JSON content received from the external data server. The result is substituted into the 'email' field of the corresponding 'oauth/Requests' request and can be used in the token authorization script.

The query string format matches the one used in the Parser script component when working with JSON.

When several strings are specified in the list, they are applied sequentially to the source content until a value is successfully found. Several variants can be used to process both the JSON response from the data server and the JWT response or parameter from the identification server.

Example:
["email","emails/0"]

query_domain

List of query strings for finding the communication system domain in JSON content received from the external data server. The result is substituted into the 'domain' field of the corresponding 'oauth/Requests' request and can be used in the token authorization script.

The query string format matches the one used in the Parser script component when working with JSON.

When several strings are specified in the list, they are applied sequentially to the source content until a value is successfully found. Several variants can be used to process both the JSON response from the data server and the JWT response or parameter from the identification server.

The token authorization script ('iam_token_svcscript_code') determines the existing communication system domain. The domain determined from the response is an auxiliary value for it.

Example:
["domain"]

query_info

Object defining the format for collecting the INFO JSON object, which will be saved in the 'opts.info' field of the user account when 'register_user_enabled' and/or 'update_user_enabled' mode is enabled.

Based on the result received from the external data service after OAuth authorization, collects an object with identical keys. Values are filled using the specified search strings or templates.

The value for each key is set as: * either a string, which is placed into the value unchanged * or a list of search queries (the query format is described in the "Search queries" section).

Example:
{
  "oid": ["oid"],
  "trusted": ["trusted"],
  "mobilePhone": ["mobilePhone"],
  "name": {
    "type": "string",
    "template": "{first} {middle} {last}",
    "keys": {
      "first": ["firstName"],
      "last": ["lastName"],
      "middle": ["middleName"]
    }
  },
  "passport": {
    "type": "string",
    "template": "{series} {number}",
    "keys": {
      "number": ["docs/elements/0/number"],
      "series": ["docs/elements/0/series"]
    }
  },
  "birthDate": ["birthDate"],
  "inn": ["inn"],
  "snils": ["snils"]
  "vehicles": [
      {
        "type": "array",
        "path": "vhls/elements",
        "keys": {
           "name": ["name"],
           "number": ["numberPlate"]
           "reg": [
             {
               "type":"string",
               "template":"{series} {number}",
               "keys":{
                  "series": ["regCertificate/series"],
                  "number": ["regCertificate/number"]
               }
             }]
        }
      }]
}

default_domain

System domain substituted into the 'domain' field of the corresponding 'oauth/Requests' request, which can be used in the token authorization script to create/link a local account in the corresponding domain. Used if the 'query_domain' list is empty or its application to the result received from the external data server found no value.

The token authorization script ('iam_token_svcscript_code') determines the existing communication system domain. The domain determined from the response is an auxiliary value for it.

dialect

Protocol dialect. Supported variants:

  • openid - OpenID Connect 1.0. The user data object is unpacked from the JWT in the 'id_token' field of the response to the 'uri_token' request. No request to 'uri_info' is made.

  • oauth - OAuth 2.0. The user data object is requested separately from 'uri_info', and the object from 'id_token', if present, is placed in 'payload'.

The list of search queries specified in the parameter is applied to JSON content received from the external OAuth authorization server.

The value search/formatting algorithm applies queries from the list sequentially until success, then applies the obtained value and terminates. If all queries fail, no value is formed and the key is not added to the result set.

The search query is a string addressing an arbitrary element in a JSON object or array. The query string format matches the one used in the Parser script component when working with JSON. For example: "vhls/elements/0/reg/series", where 0 is the numeric index of the array element.

Formatting queries can be used. They can also include search and formatting queries at arbitrary depth. For this, the search query is an object with a type field taking the following values:

  • string. String formatting. Field

  • object. Object formatting.

  • array. Formatting a collection of same-type elements located at one level in the source object.

String formation example

To compose a single string from three separate fields (First name, Last name, Middle name):

{
  ...
  "name": "Ivan Ivanovich Ivanov",
  ...
}

formatting query:

{
  "type": "string",
  "template": "{first} {middle} {last}",
  "keys": {
    "first": ["firstName"],
    "last": ["lastName"],
    "middle": ["middleName"]
  }
}

Object formation example

To get an object with separate fields:

{
  ...
  "name": {
    "first": "Ivan",
    "middle": "Ivanovich",
    "last": "Ivanov",
  },
  ...
}

formatting query:

{
  "type": "object",
  "keys": {
    "first": ["firstName"],
    "last": ["lastName"],
    "middle": ["middleName"]
  }
}

Collection formation example

To build a collection:

{
  ...
  "vehicles": [
    {
      "name": "Honda",
      "number": "A133OH177",
      "reg": "77UE 204623"
    }
  ],
  ...
}

formatting query:

{
  "type": "array",
  "path": "vhls/elements",
  "keys": {
    "name": ["name"],
    "number": ["numberPlate"]
    "reg": [
      {
        "type":"string",
        "template":"{series} {number}",
        "keys":{
          "series": ["regCertificate/series"],
          "number": ["regCertificate/number"]
        }
      }
    ]
  }
}

The last example already includes nesting - the 'reg' field of the formed object is itself formed as a string. Nesting can be arbitrary.

The 'path' value points to the collection inside the object, and further search when building objects is performed by relative paths. Thus a collection of any nesting level can be parsed into values.

Examples of various provider types

Yandex.ID

To obtain client_id and client_secret values, register the system in Yandex applications and set the required and optional SCOPE for the data for which permissions will be requested from the authorizing user.

Example provider configuration for connecting Yandex.ID
[
  {
    "id": "0c04b29b-0184-31f2-2e5e-3cecef28bebf",
    "key": "yandex",
    "enabled": true,
    "icon_uri": "/.well-known/oauth/icons/ya.png",
    "label": "Sign in with Yandex ID",
    "order": 20,
    "default_domain": "meet.incoplax.com",
    "dialect": "oauth",
    "client_id": "bef3ce0aebc64abbb7c9............",
    "client_secret": "a95050f939254f2a95ed............",
    "redirect_uri": "https://era.incoplax.com/oauth/receiver",
    "scope": [
      "login:info",
      "login:email"
    ],
    "optional_scope": [],
    "params_authorize": {
      "display": "popup",
      "force_confirm": "yes"
    },
    "state_mode": "param",
    "uri_authorize": "https://oauth.yandex.ru/authorize",
    "uri_token": "https://oauth.yandex.ru/token",
    "uri_info": "https://login.yandex.ru/info?format=json",
    "query_domain": null,
    "query_email": [
      "email",
      "emails/0"
    ],
    "query_id": null,
    "query_login": [
      "login"
    ],
    "query_name": [
      "name",
      "real_name"
    ],
    "login_mode": "auto",
    "iam_svcscript_code": null,
    "register_user_enabled": true,
    "update_user_enabled": true,
    "verify_hash": false
  }
]