oauth/Providers
Overview
Collection of OAuth 2.0 authorization and OpenId Connect 1.0 identification providers.
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.
| Field | Description |
|---|---|
|
Provider identifier |
|
OAuth authorization provider key by which the entity is discovered when a request arrives at the URL '/oauth/redirect/<PROVIDER_KEY>'. Example:
"yandex" |
|
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. |
|
Mode for linking an external account to an internal one. Variants:
Default "auto". |
|
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. |
|
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". |
|
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". |
|
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" |
|
Text displayed on the alternative authorization button in the root web application login form. Example:
"Sign in with Yandex" |
|
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. |
|
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). |
|
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" |
|
Switch for preserving the original URL ("Schema://Host") after authorization. Default false - after authorization the scheme and host from 'redirect_uri' remain. |
|
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" |
|
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" |
|
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). |
|
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 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"] |
|
Object with additional parameters added to the authorization server redirect URL. Empty by default. Example:
{
"display": "popup",
"force_confirm": "yes"
}
|
|
State specification mode. Possible variants:
The 'state' parameter is needed to match the reverse redirect with the 'oauth/Requests' entity. |
|
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" |
|
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"] |
|
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"] |
|
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"] |
|
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"] |
|
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"] |
|
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"]
}
}]
}
}]
}
|
|
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. |
|
Protocol dialect. Supported variants:
|
Search and formatting queries
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.
[
{
"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
}
]