How authorization works

Yandex Dialogs interacts with the skill and authorization server via OAuth 2.0 using authorization code grant.

When the user authenticates at the authorization server, the server sends the code to Yandex Dialogs to get the token. Yandex Dialogs uses this code to request an OAuth token and a refresh token used for updating the access token when it expires.

Yandex Dialogs sends the OAuth token to the skill. The skill must use this token in its requests to your app to get private resources.

OAuth authorization and roles

OAuth 2.0 defines the following roles:

Resource owner: The user.
Resource server: The smart device manufacturer's server that provides access to device data using access tokens.
Client: An application (skill) used to set up the connection between the user and smart devices.
Authorization server: Verifies the authenticity of the data provided by the user and issues authorization tokens.
The client uses them to request access to the user's devices.

The response length is limited to 5000 characters, and the length of the OAuth token or refresh token to 2048 characters. Token lifetime (the expires_in property) must be an integer between 1 and 4,294,967,296.

The Aqara app example below shows how OAuth roles are used in skills.

Role in OAuth	Role in skills
Resource owner	The user that wants to allow the skill to access their account in the Aqara app.
Resource server	The Aqara app that stores data on the users' devices.
Client	Your skill that is used to set up communication between the user and the Aqara resource server.
Authorization server	This server does the following: Authenticates skill users. Requests confirmation for accessing data in the Aqara app. Generates a token. The token is passed to the skill, and the skill sends it in requests to Aqara.

Scenarios for developing authorization-based skills

You develop your own resource server and authorization server

You independently implement an authorization server to run OAuth 2.0. The authorization server will authenticate the user, request permission to access their private data, and issue tokens.

Set up communication between the authorization server and resource server. The resource server will process requests from the client, validate tokens, and output the private resource to the skill.

Instead of your own authorization server, you can use the Yandex ID API to authenticate Yandex users. However, authorization using Yandex ID is unavailable for official skills.

In this case, you develop your own resource server, but use a third-party authorization server

The authorization server can be part of your server with smart device data, such as Aqara. As an alternative, you can use a third-party authorization server. For example, for unofficial skills, you can set up external authorization via Yandex.

A third-party authorization server can provide the user data to the skill, such as username or email (if the user agrees). This way you can collect statistics about your skill users.

You use both a third-party resource server and a third-party authorization server

You don't have to own an authorization server or resource server that hosts smart device data.

For example, make an unofficial skill for the Aqara app with an external API. The skill connects to the API, authenticates the user, and sends requests on behalf of the user based on their voice commands. The app must support OAuth 2.0.

If you use third-party systems, look up the following in their documentation:

Whether the OAuth 2.0 protocol is implemented on the authorization server.
Whether the authorization server supports authorization code grant.
How you can register an OAuth application on the authorization server.
Which URIs to use for authorization requests and OAuth token requests.
How to call the service's API to access the data of a specific skill user.

How authorization works with a skill

When the user taps Привязать к Яндексу (Link to Yandex), Yandex Dialogs redirects them to the login page of your app (authorization endpoint). You specify the URL of this page when linking accounts in the developer console. Yandex Dialogs passes the following parameters within the authorization URL:
- state: Authorization state. It is generated by Yandex Dialogs to track the authorization process. The authorization server must return this parameter to Yandex Dialogs with the same value.
- redirect_uri is the page where the authorized user is redirected (redirect endpoint). Specify the Yandex Dialogs URI as redirect_uri: https://social.yandex.net/broker/redirect.
- response_type: Authorization type. Accepts the value of the code.
- client_id: The identifier of your OAuth app.
- scope: An access scope to be granted to the requested OAuth tokens (access token scope). For example: read, home:lights. To specify multiple accesses, separate them with &.
The user enters the username and password from their account in your app.
The authorization server verifies the data entered by the user. If successful, it generates the code to get the token.
The authorization server redirects the user to the URI https://social.yandex.net/broker/redirect. In the request, the server passes the parameters: code, state, client_id, and scope. The authorization server must return them with the same values that Yandex Dialogs passed to the authorization URL (see Step 1).
Yandex Dialogs uses the code to get an OAuth token and a refresh token for the user account. For this purpose, Yandex Dialogs sends requests to the URL you specified when creating an authorization in the developer console (in the URL для получения токена (URL for getting a token) and URL для обновления токена (URL for updating a token) fields).

The response length is limited to 5000 characters, and the length of the OAuth token or refresh token to 2048 characters. Token lifetime (the expires_in property) must be an integer between 1 and 4,294,967,296.
Yandex Dialogs saves the OAuth token and refresh token (if any). The accounts are now linked.

Was the article helpful?

When to use

How users see it