oauth/Providers
Overview
A collection of OAuth 2.0 authorization and identity providers OpenId Connect 1.0.
Based on this collection, alternative external authorization buttons are displayed in the root web application login form. The icons and captions are taken from the entity.
The collection is contained in the master domain only.
Storage Type: runtime.
| Field | Description |
|---|---|
|
Provider ID |
|
The OAuth-authorization provider key by which the entity is discovered when a request is made to URL '/oauth/redirect/<PROVIDER_KEY>'. Example:
"yandex" |
|
OAuth authorization provider switch. Determines whether the root web application login form appears in the list of alternative authorization methods. A disabled ISP cannot be used to redirect to an external authorization server. |
|
The mode of linking an external account to an internal account. Options:
Default "auto". |
|
Detached binding script (service script code in the master domain). Applies when login_mode=script. If no script is specified, the generic script specified by the 'iam_token_svcscript_code' parameter of the master domain is applied. Transmittable Parameters: 1. identifier of the current authorization request (xref:api:rest/v1/model/endpoints/oauth/requests.adoc'/rest/v1/model/oauth/Requests'). 2. JSON-the essence of an authorization request. 3. JSON-authorization provider entity (xref:api:rest/v1/model/endpoints/oauth/requests.adoc'/rest/v1/model/oauth/Providers'). 4. IP-client address and port. It is the script that determines the binding logic. If the binding logic is non-trivial, the normal mode is not suitable and the scripted binding mode should be used. The script must use the authorization request entity and the user properties specified in it. Information about the user is entered into the request after the authorization server responds in the previous step of the process. If the authorization server does not explicitly return the login used for binding, it must be uniquely generated in the script. If the script does not return a domain, and different users need to bind to different domains, then the domain must be defined in the script. If necessary, create a user account in the domain. The script, if successful, assigns values to the variables "result" = 1, "login", "domain". To successfully complete the authorization, the user account with the specified login must exist in the specified domain after the script completes. By default, a generic master-domain script is used, and if there is no master-domain script, authorization fails. |
|
Turns off the automatic user account creation mode. When using binding mode "auto" also checks in the destination domain setting "self_register_mode", uses "self_register_template" as the template for the account to be created. When using the "script" mode, this setting is checked by the token authorization script and may not be used by it. Default "true". |
|
Turns off automatic updating of fields (name, email) in the local user account based on the data received from the external server. When using the "script" mode, this setting is checked by the token authorization script and may not be used by it. Default "true". |
|
URL icon displayed on the alternative authorization method button in the root web application login form. Icons can be placed in the ':SYNC/common/www/.well-known/…' directory and can be accessed via the URL path: '/.well-known/…'. This is a reasonable alternative to placing it in the 'www' static public resources directory located in the system modules folder '/usr/lib/era/era_ws/priv/www' because it is automatically synchronized between all servers and is resistant to system updates." Example:
"/.well-known/resources/oauth/providers/yandex.swg" |
|
Text displayed on the alternative authorization method button in the root web application login form. Example:
"Login via Yandex" |
|
The 'client_id' value issued by the external platform, generated when a communication service is registered on it. Used in accordance with the OAuth 2.0 protocol to associate an external authorization process with an account on a system registered on an external platform. |
|
The 'client_secret' value issued by the external platform, generated when a communication service is registered on it. Used in accordance with the OAuth 2.0 protocol when communicating between servers. |
|
Full URL for redirecting back from the external server to the system after authorization. Typically registered on an external platform and must match. The resource path '/oauth/receiver' should always be set unchanged, as this is the single page receiving the reverse redirection. Example:
"https://pbx.era-platform.ru/oauth/receiver" |
|
Switch for saving the original URL ("Schema://Host") after authorization. Defaults to false - the scheme and host from the 'redirect_uri'. |
|
The full URI of the external authorization server to which the authorization redirects. Displays the authorization page. In accordance with the OAuth 2.0 protocol, it is supplemented with the necessary GET parameters and substituted in the header Location. The external server redirects back to 'redirect_uri' after successful authorization by passing in the GET parameters 'code' and 'state'. Example:
"https://oauth.yandex.ru/authorize" |
|
The full URI of the external authorization server where the inter-server request is made to exchange the received code for the data access token. In accordance with the OAuth 2.0 protocol, a POST request is made to it, passing the necessary parameters, including the 'code' received during authorization and the 'code' received during system registration on the external platform 'client_secret'. Example:
"https://oauth.yandex.ru/token" |
|
Required Data Scope. A list of partitions corresponding to an external authorization system. Substituted as the 'scope' parameter in the URL of the authorization server 'uri_authorize'. Cannot be greater than that specified when registering the communication system on the external platform. It can be left empty, then the 'scope' parameter is not sent when redirecting to the authorization server, and as a rule the authorization server by default applies the full set of sections specified during registration as it. Example:
["login:info", "login:email"] To organize the identification process by OpenId Connect 1.0, you must specify a single value in the scope list: "openid". |
|
Optional data scoop. A list of partitions corresponding to an external authorization system. Substituted as the 'optional_scope' parameter in the URL of the authorization server 'uri_authorize'. If the authorization server supports optional scoping, the user has the ability to determine which of the optional partitions he or she allows the communication system to access when authorizing. Can be left empty, then the 'optional_scope' parameter is not sent when redirecting to the authorization server. Example:
["login:email", "login:avatar"] |
|
An object with additional parameters added to the URL redirecting to the authorization server. The default is blank. Example:
{
"display": "popup",
"force_confirm": "yes"
}
|
|
Indication mode state. Possible options:
The 'state' parameter is required to map the reverse redirect to an entity 'oauth/Requests'. |
|
The full URI of the external data server providing external user account information by token 'access_token'. Example:
"https://login.yandex.ru/info" |
|
A list of search queries to discover a user ID in JSON content received from an external data server (external login). The result is substituted into the 'oid' field of the corresponding request 'oauth/Requests', and can be used in a token-based authorization script. The format of the search query is described in "Search Queries". When multiple rows are specified in a list, they are sequentially applied to the original contents until a value is successfully found. Multiple variants can be used to process both a JSON response from a data server and a JWT response or parameter from an identity server. The identifier can be searched also after receiving an access token in the parsed content JWT. Thus the list should consist of multiple search strings, one of which is resolved in the first case, and the second after receiving a response from the data service. Example:
["urn:esia:sbj_id","oid"] |
|
A list of search queries to discover/build a user login in JSON content received from an external data server (external login). The result is substituted into the 'login' field of the corresponding request 'oauth/Requests', and can be used in a token-based authorization scenario. The format of the search query is described in "Search Queries". When multiple rows are specified in a list, they are sequentially applied to the original contents until a value is successfully found. Multiple variants can be used to process both a JSON response from a data server and a JWT response or parameter from an identity server. Example:
["login"] |
|
A list of search queries to discover/build a username in JSON content retrieved from an external data server. The result is substituted into the 'name' field of the corresponding request 'oauth/Requests', and can be used in a token-based authorization script. The format of the search query is described in "Search Queries". When multiple rows are specified in a list, they are sequentially applied to the original contents until a value is successfully found. Multiple variants can be used to process both a JSON response from a data server and a JWT response or parameter from an identity server. Example:
["name", "full_name"] |
|
A list of search query strings to discover a user’s email address in JSON content retrieved from an external data server. The result is substituted into the 'email' field of the corresponding request 'oauth/Requests', and can be used in a token authorization script. The format of the search string matches the one used in the scripting component Parser when working with the JSON. When multiple rows are specified in a list, they are sequentially applied to the original contents until a value is successfully found. Multiple variants can be used to process both a JSON response from a data server and a JWT response or parameter from an identity server. Example:
["email","emails/0"] |
|
A list of query strings to search for a communication system domain in JSON content received from an external data server. The result is substituted into the 'domain' field of the corresponding request 'oauth/Requests', and can be used in a token-based authorization scenario. The format of the search string matches the one used in the scripting component Parser when working with the JSON. When multiple rows are specified in a list, they are sequentially applied to the original contents until a value is successfully found. Multiple variants can be used to process both a JSON response from a data server and a JWT response or parameter from an identity server. It is the token authorization script ('iam_token_svcscript_code') that defines the existing domain of the communication system. The domain defined from the response is an auxiliary value for it. Example:
["domain"] |
|
Object defining the collection format of the INFO JSON object that will be stored in the 'opts.info' field of the user account when 'register_user_enabled' is enabled and/or 'update_user_enabled'. Based on the result received from an external data service after OAuth authorization, collects an object with identical keys. Values are populated using specified search strings or templates. The value for each key is set to: * or a string, then it is unchanged in the value * or a list of search queries (the search query format is described in "Search Queries")"]). 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"]
}
}]
}
}]
}
|
|
The domain of the system, substituted in the 'domain' field of the corresponding 'oauth/Requests' request, which can be used in a token authorization script to create/bind a local account in the corresponding domain. Used if the 'query_domain' list is empty, or applying it to a result retrieved from an external data server has not detected a value. It is the token authorization script ('iam_token_svcscript_code') that defines the existing domain of the communication system. The domain defined from the response is an auxiliary value for it. |
Search and formatting queries
The search query list specified in the parameter is applied to JSON content received from an external OAuth authorization server.
For EUIA, multiple queries are made to the external REST server according to a given SCOPE, and the results are combined into one large object.
The value retrieval/formatting algorithm applies the queries from the list sequentially until success, after which it applies the retrieved value and terminates. If all queries fail, no value is generated 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 format of the search string matches the one used in the scripting component Parser when working with the JSON. For example: "vhls/elements/0/reg/series", where 0 is the numeric index of the array element.
It is possible to use formatting queries. They can also include search and formatting queries to any depth.
For this purpose, an object with the type field taking the following values acts as a search query:
-
string. Formatting a string. Field -
object. Formatting an object. -
array. Formatting a collection of items of the same type located at the same level in the source object.
Example of string formation
To make a single string from three separate fields (First Name, Last Name, Patronymic):
{
...
"name": "John Michael Smith",
...
}
formatting query:
{
"type": "string",
"template": "{first} {middle} {last}",
"keys": {
"first": ["firstName"],
"last": ["lastName"],
"middle": ["middleName"]
}
}
Example of object formation
To get an object with separate fields:
{
...
"name": {
"first": "John",
"middle": "Michael",
"last": "Smith",
},
...
}
formatting query:
{
"type": "object",
"keys": {
"first": ["firstName"],
"last": ["lastName"],
"middle": ["middleName"]
}
}
Example of collection formation
To build a collection:
{
...
"vehicles": [
{
"name": "Honda",
"number": "A133ON177",
"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"]
}
}
]
}
}
In the last example nesting is already enabled - the 'reg' field of the formed object is itself formed as a string. The nesting can be arbitrary.
The 'path' value - specifies the path to the collection inside the object, and further search when building objects is performed by relative paths. In this way it is possible to parse collections of any nesting level into values.
Examples of different types of providers
Yandex.ID
To obtain client_id and client_secret values, it is necessary to register the system in Yandex applications, and set the required and optional SCOPE for the data under which the authorizing user will be asked for permissions.
[
{
"id": "0c04b29b-0184-31f2-2e5e-3cecef28bebf",
"key": "yandex",
"enabled": true,
"icon_uri": "/.well-known/oauth/icons/ya.png",
"label": "Login with Yandex ID",
"order": 20,
"default_domain": "meet.era-platform.ru",
"dialect": "oauth",
"client_id": "bef3ce0aebc64abbb7c9............",
"client_secret": "a95050f939254f2a95ed............",
"redirect_uri": "https://era.era-platform.ru/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
}
]
ESIA
In order to use integration with ESIA, the system must be registered with the authorities. The system uses GOST3410 certificate, also registered with the Ministry of Communications, to sign requests.
All urls are flashed in the system and may not be set. The urls of specific information retrieval requests are flashed for the SCOPE core values. The digital signature generated in each request is passed as 'client_secret'.
First, the operation in the TESIA test environment is set up. To do this, the 'dialect' field should be set to "tesia". When switching to a product environment, the 'dialect' field must be set to a value of "esia".
{
"id": "edf5074b-0184-4770-4f4f-005056aee515",
"key": "esia",
"enabled": true,
"icon_uri": "/.well-known/oauth/icons/esia.svg",
"label": "Logging in via EUIA",
"order": 10,
"default_domain": "meet.era-platform.ru",
"dialect": "esia",
"client_id": "0...",
"certificate_pem": ":SYNC/common/cert_esia/cert.pem",
"redirect_uri": "https://era-platform/oauth/receiver",
"scope": [
"openid",
"fullname",
"email",
"birthdate",
"mobile",
"id_doc",
"vehicles"
],
"query_id": ["urn:esia:sbj_id","oid"],
"query_login": ["urn:esia:sbj_id"],
"query_name": ["lastName","firstName","middleName"],
"query_email": ["email"],
"query_info": {
"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"]
}
}]
}
}]
},
"login_mode": "auto",
"iam_svcscript_code": null,
"register_user_enabled": true,
"update_user_enabled": true,
"verify_hash": false
}
-
The 'query_info' field is optional. It sets the collection mode of the complex object, which, when 'register_user_enabled' and/or 'update_user_enabled' is enabled, is included in the 'opts.info' field of the user account.
-
The fields 'uri_authorize', 'uri_token', 'uri_info' are not applied, the values are flashed in the system.