OAuth authorization. Developer's guide - Yandex · PDF fileOAuth in Yandex The OAuth 2.0 protocol allows applications to access Yandex services on behalf of a user. Access is explicitly

OAuth authorizationDeveloper's guide

9.04.2018

OAuth authorization. Developer's guide. Version 1.3 Document build date: 9.04.2018.This volume is a part of Yandex technical documentation.Yandex helpdesk site: http://help.yandex.ru© 2008—2018 Yandex LLC. All rights reserved.

Copyright DisclaimerYandex (and its applicable licensor) has exclusive rights for all results of intellectual activity and equated to them means of individualization, used for development, support,and usage of the service OAuth authorization. It may include, but not limited to, computer programs (software), databases, images, texts, other works and inventions, utilitymodels, trademarks, service marks, and commercial denominations. The copyright is protected under provision of Part 4 of the Russian Civil Code and international laws.You may use OAuth authorization or its components only within credentials granted by the Terms of Use of OAuth authorization or within an appropriate Agreement.Any infringements of exclusive rights of the copyright owner are punishable under civil, administrative or criminal Russian laws.

Contact informationYandex LLChttp://www.yandex.comPhone: +7 495 739 7000Email: [email protected]: 16 L'va Tolstogo St., Moscow, Russia 119021

http://help.yandex.ru

http://www.yandex.com

ContentsOAuth in Yandex ................................................................................................................................................................................. 4Terms ................................................................................................................................................................................................... 4Yandex OAuth implementation ........................................................................................................................................................... 5Registering an application .................................................................................................................................................................... 7

Get a token via an authorization code .............................................................................................................................................. 9Token for a code received automatically ..................................................................................................................................... 9Token for a code entered by the user ......................................................................................................................................... 14

Use a refresh token to get a token ...................................................................................................................................................... 20

Extract a token from a URL ........................................................................................................................................................... 22Web applications ........................................................................................................................................................................ 22Mobile applications .................................................................................................................................................................... 25Desktop applications .................................................................................................................................................................. 29

Debugging token ................................................................................................................................................................................ 33Device token ...................................................................................................................................................................................... 33Revoking tokens ................................................................................................................................................................................. 36

Index .................................................................................................................................................................................................. 37

OAuth authorization Developer's guide

OAuth in YandexThe OAuth 2.0 protocol allows applications to access Yandex services on behalf of a user. Access is explicitlyrestricted for each application to the rights assigned during application registration. For information about basicOAuth principles and how the protocol is used in Yandex, see the section Yandex OAuth implementation.

OAuth authorization is supported by Yandex.Disk, Yandex.Webmaster, Yandex.Metrica, and other services.

How to use OAuthTo start using the protocol, you need to:

1. Register your application on Yandex.OAuth.

2. Implement getting a token in one of two ways:

• POST request for a token in exchange for the code returned by Yandex.OAuth.

• Extracting the token from the URL hash (the part of the address after the # symbol).

This method is described in the instructions for mobile, desktop, and web applications.

You can test OAuth applications using debugging tokens.

TermsOAuth token

A string that allows accessing a Yandex service on behalf of a particular user. In the context of the protocol,“OAuth token” can be shortened to “token”.

Every OAuth token always contains:

• The ID of the account that can be accessed.

• The ID of the application that was granted access.

• A set of permissions (actions allowed for the application).

In this way, the token shows what the application can do on behalf of a specific account.

OAuth applicationA program, mobile app, or web service that is registered on Yandex.OAuth.

In the Yandex.OAuth documentation, OAuth applications are referred to as just "applications". Other typesof applications are identified explicitly.

PermissionsAn action or set of actions on behalf of the user that are available with the OAuth protocol.

Yandex.OAuth tokens always indicate the permissions selected by the developer when registering or settingup the application. The same OAuth application can't simultaneously have two active tokens with differingpermissions.

Refresh tokenAn extra string that is returned with the OAuth token. The refresh token is used for renewing an OAuth tokenthat is about to expire.

Developer's guide


4

https://tech.yandex.com/disk/

https://tech.yandex.com/webmaster/

https://tech.yandex.com/metrika/

Yandex OAuth implementationYandex services authorize applications via tokens. Each token is an alphanumeric sequence encodingthe following information:

• The ID of the account that can be accessed.

• The ID of the application that was granted access.

• A set of permissions (actions allowed for the application).

The general principles of using Yandex OAuth tokens are explained below.

Authorization flowApplications use the following flow for requesting tokens:

1. The application directs the user to the OAuth server. On the page that opens, the user can grant the applicationaccess to the requested account data. The application can request:

• All types of access that were specified during application registration. In this case, the user must eithergrant or refuse all the requested access permissions at once.

• Just specific access permissions that are needed right now, from the list of permissions that werespecified during application registration. In this case, the user also must either grant or refuse all therequested access permissions at once.

• The necessary access permissions from the list of permissions that were specified during applicationregistration, along with optional permissions from the list that aren't necessary at the moment.An example of an optional permission is access to the profile picture. In this case, the user can grantall the necessary requested permissions at once, and choose which of the requested optional permissionsto grant.

2. The user grants access to personal data, and the OAuth server redirects the user to the address indicatedby the developer.

The token that is issued (or the code for obtaining it) is embedded in the redirect URL. If the user refusedaccess or an error occurred, an error message is appended to the redirect URL.

3. The application includes the received token in a request to a Yandex service that supports OAuth.

The received token can be stored in the application and used for requests until it expires.

Developer's guide


5

Token lifespanThe token lifespan is how long the token can be used for authorization. The maximum lifespan depends on thepermissions selected during application registration:

Perpetual tokenNever expires and can only be revoked by the user.

During application registration, the lifespan is displayed as "indefinite".

Renewable tokenExpires after several months, but is renewed each time this token is used for authorization.

The minimum lifespan is displayed during application registration, such as “at least 1 year”.

Limited tokenExpires after the duration specified for the respective access permissions.

If multiple permissions were selected during application registration, the shortest time limit is applied to thetoken. For example, permissions to access Yandex.Metrica are set to 1 year, while permissions for usingYandex.Post Office are set to 180 days. This means that a token with permissions for both Yandex.Metricaand Yandex.Post Office will be valid for no longer than 180 days.

Revoking a tokenUsers can revoke any OAuth tokens that have been issued for their accounts:

• To revoke all tokens that were ever issued for an account, the user can change the password or log out ofall computers.

• To revoke tokens that were issued to a specific application, the user can deny access for this applicationon the applications page.

An application can revoke its own token if it was issued for a specific device.

All situations for revoking a token are listed on the page Revoking tokens.

Developer's guide


6

https://yandex.com/support/passport/faq.xml#glogout

https://yandex.com/support/passport/faq.xml#glogout

https://passport.yandex.com/profile/access

User interfaceThe page where the user can grant the application access (the first step in authorization) contains the applicationname and a list of requested permissions:

When the user clicks one of the buttons, the OAuth server redirects the user to the address specified as theCallback URL.

Registering an applicationThe application developer must register the application on the OAuth server in order to get tokens for Yandexusers.

Stages in the registration process:

1. Open the New client page.

2. Specify application properties:

Name The title of the application. It is displayed on the accessrequest page and in the list of registered applications.

Description A brief description of the application. It is displayedin the list of applications that the user has granted accessto the account.

Icon link The link to the application's icon. Optional property.

Application link The link to the application's website. Optional property.

It is displayed in the list of applications that the userhas granted access to the account.

Permissions A set of access rights (the same as the scope parameterin the OAuth protocol). Users allow the applicationto perform the selected actions when tokens are issued.

Developer's guide


7

https://oauth.yandex.com/client/new

https://oauth.yandex.com/client/my

https://oauth.yandex.com

https://oauth.yandex.com

Access rights are registered in the application properties.You can't set them when requesting a token.

Some permissions may limit the maximum lifespanof the token.

Callback URL The address that the user is returned to after grantingor refusing the application access (corresponds to theredirect_uri parameter in the OAuth protocol).

This URL is registered in the application properties.You can't set it when requesting a token.

If you want to get a debugging token for this application,click Set URL for development. A testing URL willbe entered in this field. You can use it for gettingdebugging tokens manually.

3. Click the Create button.

After registration, the application page opens with the application properties: the Callback URL address, as wellas the ID and password to use for requesting a token.

The Registered clients page lists all the applications registered by the developer.

Developer's guide


8

https://oauth.yandex.com/

Get a token via an authorization code

Token for a code received automaticallyObtaining a token in exchange for a code extracted from a URL:

1. The application directs the user to the Yandex.OAuth page, where the user can grant access to personal data.

2. The user grants the application access.

3. Yandex.OAuth redirects the user to the address specified in the Callback URL field during applicationregistration. The authorization code (or error description) is passed in the redirect URL parameter.

4. The application gets the redirect address and extracts the authorization code.

5. The application sends a POST request with the code.

6. Yandex.OAuth returns a token in the message body.

Tip:Debugging tokens can be obtained manually.

The received token can be saved in the application and used for API requests until its lifespan expires. The tokenmust only be accessible to your application, so we do not recommend storing it in browser cookies, openconfiguration files, and so on.

Request for an authorization codeThe application should direct the user to Yandex.OAuth at the following address:

https://oauth.yandex.com/authorize? response_type=code & client_id=<application ID>[& device_id=<device ID>][& device_name=<device name>][& login_hint=<username or email>][& scope=<necessary permissions requested>][& optional_scope=<optional permissions requested>][& force_confirm=yes][& state=<any string>]

Parameter Description

Required parameters

response_type Required response.

When requesting an authorization code, specify the value“code”.

client_id Application ID. Available in the application properties (clickthe name of the application to open its properties).

Additional parameters

device_id Unique ID of the device that the token is being requested for.To ensure uniqueness, it is sufficient to generate the UUIDonce and use it for every request for a new token from thisdevice.



9


https://en.wikipedia.org/wiki/Universally_unique_identifier


The ID must be at least 6 characters and no more than50. Only printable ASCII symbols are allowed (codes32 through 126).

Restriction:An application can't have more than 20 tokens associatedwith devices for a specific user. If Yandex.OAuthsuccessfully issues the application a new token for a device,the oldest token stops working.

For more information about device tokens, see Devicetoken.

device_name The device name to show to users. Maximum of 100characters.

For mobile devices, we recommend passing the device nameset by the user. If it does not have a name, you can makeone up using the device model, OS name and version, and soon.

If the device_name parameter was passed withoutthe device_id parameter, it will be ignored.Yandex.OAuth can only issue a regular token that is notassociated with the device.

If the device_id parameter was passed withoutthe device_name parameter, the user interface will showthe token as issued for an unknown device.

login_hint Explicitly identifies the account that the token is beingrequested for. The parameter value can pass a Yandexaccount username, or an email address for Yandex.Mailor Yandex.Mail for Domain.

This parameter helps the user log in on Yandex withthe account that the application needs to access. After gettingthe parameter, Yandex.OAuth checks the user'sauthorization:

• If the user is already logged in under the necessaryaccount, Yandex.OAuth just asks for permissionto access data.

• If the user isn't logged in under the necessary account,the service displays the Yandex login page with thisparameter value shown in the username field. Keepin mind that the token won't necessarily be requestedfor the account shown: the user might delete the pre-filled username and log in with another one.

If the parameter specifies a non-existent account,Yandex.OAuth can only inform the user of this.The application will have to request the token over again.

scope A space-separated list of permissions that the applicationneeds at this time. The requested permissions must be fromthe list that was specified when registering the application.To find out which permissions are available, go to https://oauth.yandex.com/client/<client_id>/info (specifythe application's ID in place of <client_id>).

If the scope and optional_scope parameters wereomitted from the request, the token is issued withthe permissions that were specified when registeringthe application.

This parameter lets you get a token for just the permissionsthat the application needs right now.



10

https://en.wikipedia.org/wiki/ASCII

https://oauth.yandex.com/client/%3Cclient_id%3E/info



Note:Access permissions that are requested using boththe scope parameter and the optional_scopeparameter simultaneously are treated as optional permissionsthat the application can do without. The user can decidewhich of the requested permissions to grant the application,and which ones to refuse.

optional_scope A list of space-separated optional access permissions thatthe application can function without. Optional permissionsare requested in addition to the permissions specified in thescope parameter. Optional permissions must be fromthe list that was specified when registering the application.To find out which permissions are available, go to https://oauth.yandex.com/client/<client_id>/info (specifythe application's ID in place of <client_id>).


The user can decide which of the requested permissionsto grant the application, and which ones to refuse. The tokenis issued with the permissions specified in the scopeparameter and the permissions fromthe optional_scope parameter that the user selected.

For example, you can use this parameter if the applicationrequires the user's email address for registration, while accessto the user's profile picture is preferable, but not required.

Note:Access permissions that are requested using boththe scope parameter and the optional_scopeparameter simultaneously are treated as optionalpermissions.

force_confirm Indicates that the application must ask the user for permissionto access the account (even if the user has already grantedaccess for this application). When it gets this parameter,Yandex.OAuth asks the user to allow the application accessand to select the desired Yandex account.

This parameter is processed if the value is set to “yes”, “true”,or “1”. If any other value is set, the parameter is ignored.

state The state string, which Yandex.OAuth returns withoutmaking any changes. The maximum length of the stringis 1024 characters.

For example, you can use it for protection from CSRFattacks or for identifying the user that a token is requestedfor.

Getting an authorization code from a URLWhen a user allows access to personal data, Yandex.OAuth redirects this user to the application.The authorization code is included in the redirect URL.

Note:The lifespan of this code is 10 minutes. When it expires, a code must be requested again.

URL format with a code:



11



https://en.wikipedia.org/wiki/Cross-site_request_forgery


http://www.example.com/token? code=<confirmation code>[& state=<value of the state parameter in the request>]

Parameter Descriptioncode The authorization code that can be exchanged for an OAuth

token.

The lifespan of this code is 10 minutes. When it expires,a code must be requested again.



If an authorization code could not be issued, Yandex.OAuth specifies the error code and description in the URL.The description is in the language of the OAuth domain that the request was sent to. For example,for oauth.yandex.com, text will be returned in English.

Format of the URL with error data:

http://www.example.com/token? error=<error code> & error_description=<error description>[& state=<value of the state parameter in the request>]

Possible error codes:

• access_denied — The user denied the application access.

• unauthorized_client — The application was rejected during moderation, or moderation is pending.This code is also returned if the application is blocked.

Exchanging an authorization code for a tokenThe application sends the code, along with its ID and password, in a POST request.

POST /token HTTP/1.1Host: oauth.yandex.comContent-type: application/x-www-form-urlencodedContent-Length: <length of the request body>[Authorization: Basic <encoded client_id:client_secret string>]

grant_type=authorization_code & code=<confirmation code>[& client_id=<application ID>][& client_secret=<application password>][& device_id=<device ID>][& device_name=<device name>]


Required parameters

grant_type Method of requesting an OAuth token.

If you are using the authorization code, enter the valueof “authorization_code”.

code The authorization code received from Yandex.OAuth. Thelifespan of this code is 10 minutes. When it expires, a codemust be requested again.




12



Parameter Descriptionclient_id Application ID. Available in the application properties (click

the name of the application to open its properties).

The application password and ID can also be passed in theAuthorization header.

client_secret Application password. Available in the applicationproperties (click the name of the application to openits properties).


device_id The ID of the device that the token is being requested for.

If the ID was set in the device_id parameter when requestingthe authorization code, the device_idand device_name parameters are ignored whenrequesting the token.

device_name The name of the device that the token is being requested for.

If the device_id parameter was passed when requestingthe authorization code, the device_nameand device_id parameters are ignored when requestinga token.

The application ID and password can also be sent in the Authorization header by encodingthe client_id>:<client_secret> string using base64. If Yandex.OAuth receivesthe Authorization header, the client_id and client_secret parameters in the request bodyare ignored.

Response format with a tokenYandex.OAuth returns the OAuth token, the refresh token, and their lifespans in JSON:

200 OKContent-type: application/json

{ "access_token": "AQAAAACy1C6ZAAAAfa6vDLuItEy8pg-iIpnDxIs", "refresh_token": "1:GN686QVt0mmakDd9:A4pYuW9LGk0_UnlrMIWklkAuJkUWbq27loFekJVmSYrdfzdePBy7:A-2dHOmBxiXgajnD-kYOwQ", "token_type": "bearer", "expires_in": 124234123534}

Key Descriptionaccess_token The OAuth token with the requested permissions, or with

the permissions specified when registering the application.

refresh_token Refresh token.

token_type Type of token issued. Always takes the value “bearer”.

expires_in The token lifespan in seconds.

The lifespan of a refresh token is the same as the OAuth token's lifespan.

If a token could not be issued, the response contains an error description:

{ "error_description": "<error description>", "error": "<error code>"}



13





• bad_verification_code — The passed value of the code parameter is not a 7-digit number.

• invalid_client ― The application with the specified ID (the client_id parameter) was not foundor is blocked. This code is also returned if an invalid application password was passed in theclient_secret parameter.

• invalid_grant ― Invalid or expired authorization code.

• invalid_request ― Invalid request format (one of the parameters in the body was omitted, or wasspecified twice).

• invalid_scope — The application's permissions changed after the authorization code was generated.

• unauthorized_client — The application was rejected during moderation, or moderation is pending.

• unsupported_grant_type ― Unacceptable value for the grant_type parameter.

• Basic auth required — The authorization type in the Authorization header is set to somethingother than Basic.

• Malformed Authorization header — The Authorization header doesn't conform to theformat <client_id>:<client_secret>, or this string isn't base64-encoded.

Token for a code entered by the userSome applications (for example, applications for consoles or that are installed on Smart TVs) are not able to getthe authorization code from the URL. In this case, users must get the code from Yandex.OAuth and enter it inthe application themselves.

Obtaining a token in exchange for a code entered by the user:

1. The application opens the Yandex.OAuth page in the browser, where the user can grant access to personaldata.

If the device where the application is installed doesn't have a browser, the user will have to go to theappropriate address on a computer. To make it easier to enter the address, provide a QR code or short linkfor the user.

2. The user goes to the open page or short link and allows access for the application.

3. Yandex.OAuth displays the authorization code. (For this to happen, the Callback URL applicationparameter must indicate the address https://oauth.yandex.ru/verification_code).

4. The application sends a POST request with the code.

5. Yandex.OAuth returns a token in the message body.



Getting an authorization code1. The application should direct the user to Yandex.OAuth at the following address:



14

https://oauth.yandex.com/authorize? response_type=code & client_id=<application ID>[& device_id=<device ID>][& device_name=<device name>][& login_hint=<username or email>][& scope=<necessary permissions requested>][& optional_scope=<optional permissions requested>][& force_confirm=yes][& state=<any string>]


Required parameters


When requesting an authorization code, specify the value“code”.

client_id Application ID. Available in the application properties(click the name of the application to open its properties).


device_id Unique ID of the device that the token is being requestedfor. To ensure uniqueness, it is sufficient to generatethe UUID once and use it for every request for anew token from this device.


Restriction:An application can't have more than 20 tokens associatedwith devices for a specific user. If Yandex.OAuthsuccessfully issues the application a new token for adevice, the oldest token stops working.



For mobile devices, we recommend passing the devicename set by the user. If it does not have a name, you canmake one up using the device model, OS nameand version, and so on.


If the device_id parameter was passed withoutthe device_name parameter, the user interface willshow the token as issued for an unknown device.




15





This parameter helps the user log in on Yandex withthe account that the application needs to access. Aftergetting the parameter, Yandex.OAuth checks the user'sauthorization:


• If the user isn't logged in under the necessaryaccount, the service displays the Yandex login pagewith this parameter value shown in the usernamefield. Keep in mind that the token won't necessarilybe requested for the account shown: the user mightdelete the pre-filled username and log in withanother one.


scope A space-separated list of permissions that the applicationneeds at this time. The requested permissions mustbe from the list that was specified when registeringthe application. To find out which permissionsare available, go to https://oauth.yandex.com/client/<client_id>/info (specify the application's ID in placeof <client_id>).


This parameter lets you get a token for justthe permissions that the application needs right now.

Note:Access permissions that are requested using boththe scope parameter and the optional_scopeparameter simultaneously are treated as optionalpermissions that the application can do without. The usercan decide which of the requested permissions to grantthe application, and which ones to refuse.

optional_scope A list of space-separated optional access permissionsthat the application can function without. Optionalpermissions are requested in addition to the permissionsspecified in the scope parameter. Optional permissionsmust be from the list that was specified when registeringthe application. To find out which permissionsare available, go to https://oauth.yandex.com/client/<client_id>/info (specify the application's ID in placeof <client_id>).


The user can decide which of the requested permissionsto grant the application, and which ones to refuse.The token is issued with the permissions specified in thescope parameter and the permissions fromthe optional_scope parameter that the userselected.



16






For example, you can use this parameter if theapplication requires the user's email addressfor registration, while access to the user's profile pictureis preferable, but not required.


force_confirm Indicates that the application must ask the userfor permission to access the account (even if the userhas already granted access for this application). Whenit gets this parameter, Yandex.OAuth asks the userto allow the application access and to select the desiredYandex account.

This parameter is processed if the value is set to “yes”,“true”, or “1”. If any other value is set, the parameteris ignored.



2. When the user grants access to personal data, Yandex.OAuth returns an authorization code. The lifespanof this code is 10 minutes. When it expires, a code must be requested again.

Exchanging an authorization code for a tokenThe application sends the code, along with its ID and password, in a POST request.



17




grant_type=authorization_code & code=<confirmation code>[& client_id=<application ID>][& client_secret=<application password>][& device_id=<device ID>][& device_name=<device name>]


Required parameters


If you are using the authorization code, enter the valueof “authorization_code”.

code The authorization code received from Yandex.OAuth. Thelifespan of this code is 10 minutes. When it expires, a codemust be requested again.




The application ID and password must be passed either in therequest parameters or in the Authorization header.

client_secret Application password. Available in the applicationproperties (click the name of the application to openits properties).

The application ID and password must be passed either in therequest parameters or in the Authorization header.

device_id The ID of the device that the token is being requested for.

If the ID was set in the device_id parameter when requestingthe authorization code, the device_idand device_name parameters are ignored whenrequesting the token.

device_name The name of the device that the token is being requested for.

If the device_id parameter was passed when requestingthe authorization code, the device_nameand device_id parameters are ignored when requestinga token.





18

https://oauth.yandex.com/client/my










The lifespan of a refresh token is the same as the OAuth token's lifespan.




• bad_verification_code — The passed value of the code parameter is not a 7-digit number.


• invalid_grant ― Invalid or expired authorization code.


• invalid_scope — The application's permissions changed after the authorization code was generated.







19

Use a refresh token to get a tokenGetting an access token in exchange for a refresh token:

1. The application sends a POST request with a refresh token.

2. Yandex.OAuth returns the access token and a new refresh token in the message body.


Exchanging a refresh token for an OAuth tokenThe application sends the refresh token, along with its ID and password, in a POST request.


grant_type=refresh_token & refresh_token=<refresh_token>[& client_id=<application ID>][& client_secret=<application password>]


Required parameters


If you are using a refresh token, set the value “refresh_token”.

refresh_token The refresh token received from Yandex.OAuth withthe OAuth token. Both tokens have the same lifespan.




client_secret Application password. Available in the applicationproperties (click the name of the application to openits properties).The application password and ID can also be passed in theAuthorization header.



Developer's guide


20















• invalid_grant — Invalid or expired refresh token. This code is also returned if the refresh token belongsto another application (if it doesn't match the client_id that is passed).






Developer's guide


21

Extract a token from a URL

Web applicationsGetting a token for a web application:

1. The application directs the user to the Yandex.OAuth page, where the user can grant access to personal data.


3. Yandex.OAuth redirects the user to the address specified in the Callback URL field during registration.Token data is passed in the redirect URL after the # symbol.

The server environment might not transmit this part of the URL to the web application. In this case, datacan be extracted from the address using JavaScript, or tokens can be obtained using an authorization code.

4. The application gets the redirect address and extracts the token.



Token request URLThe application should direct the user to Yandex.OAuth at the following address:

https://oauth.yandex.com/authorize? response_type=token & client_id=<application ID>[& device_id=<device ID>][& device_name=<device name>][& display=popup][& login_hint=<username or email>][& scope=<necessary permissions requested>][& optional_scope=<optional permissions requested>][& force_confirm=yes][& state=<any string>]


Required parameters


When requesting a token, specify the value “token”.






22











display Indicates the lightweight layout (without standard Yandexnavigation) for the page for granting access.

The lightweight layout should be requested if, for example,the page for granting access must be displayed in a smallpopup window.

Only the “popup” value is processed. Other valuesare ignored.








23


Parameter Descriptionscope A space-separated list of permissions that the application

needs at this time. The requested permissions must be fromthe list that was specified when registering the application.To find out which permissions are available, go to https://oauth.yandex.com/client/<client_id>/info (specifythe application's ID in place of <client_id>).















24







Response from Yandex.OAuthToken data is passed in the redirect URL after the # symbol. If the server environment does not allowthe application to receive this part of the URL, data can be extracted using JavaScript, or tokens can be obtainedusing an authorization code.

URL format with a token:

http://www.example.com/token# access_token=<new OAuth token> & expires_in=<token lifespan in seconds> & token_type=bearer[& state=<value of the state parameter in the request>]

Parameter Descriptionaccess_token The OAuth token with the requested permissions, or with




state The value of the state parameter from the source request,if this parameter was passed.

If a token could not be issued, Yandex.OAuth appends the error code and description to the address. Thedescription is in the language of the OAuth domain that the request was sent to. For example,for oauth.yandex.com, text will be returned in English.

Format of the URL with error data:

http://www.example.com/token# error=<error code> & error_description=<error description>[& state=<value of the state parameter in the request>]




Extracting data from the URL using JavaScriptThe part of the address after the # symbol is available in the JavaScript propertydocument.location.hash.

For example, the token can be obtained like this:

var token = /access_token=([^&]+)/.exec(document.location.hash)[1];

Mobile applicationsGetting a token for a mobile application:

1. The application directs the user to the Yandex.OAuth page, where the user can grant access to personal data.The page can be opened in a browser or in the WebView element embedded in the application.


3. Yandex.OAuth redirects the user to the address specified in the Callback URL field during applicationregistration. Token data is passed in the redirect URL after the # symbol.



25

To intercept the URL from the browser, you can use a custom URI scheme in the address, such as myapp://token . Going to this type of URL will launch the application that is registered in the operatingsystem as the handler for the myapp scheme.

4. The application gets the redirect address and extracts the token.






Required parameters












26





















27














Response from Yandex.OAuthToken data is passed in the redirect URL, after the # symbol.




28





myapp://token# access_token=<new OAuth token> & expires_in=<token lifespan in seconds> & token_type=bearer[& state=<value of the state parameter passed in the request>]







myapp://token# state=<value of the state parameter in the request>& error=<error code>




Desktop applicationsGetting a token for a desktop application:

1. The application directs the user to the Yandex.OAuth page, where the user can grant access to personal data.The page can be opened in a browser or in a window embedded in the application.


3. Yandex.OAuth redirects the user to the address specified in the Callback URL field during applicationregistration. Token data is passed in the redirect URL after the # symbol.

To intercept the URL from the browser, you can use a custom URI scheme in the address, such as myapp://token . Going to this type of URL will launch the application that is registered in the operatingsystem as the handler for the myapp scheme.

4. The application gets the redirect address and extracts the token (or the error information).






29



Required parameters


















30




Parameter Descriptionlogin_hint Explicitly identifies the account that the token is being

requested for. The parameter value can pass a Yandexaccount username, or an email address for Yandex.Mailor Yandex.Mail for Domain.














31












OAuth server responseToken data is passed in the redirect URL, after the # symbol.


myapp://token# access_token=<new OAuth token> & expires_in=<token lifespan in seconds> & token_type=bearer[& state=<value of the state parameter passed in the request>]







myapp://token# state=<value of the state parameter in the request>& error=<error code>






32



Debugging tokenYou can use debugging tokens to test applications that use OAuth. Debugging tokens are obtained by openingoauth.yandex.com in a browser with the necessary parameters. Debugging tokens, like any other tokens,can always be revoked.

To get a token manually:

1. When registering or editing an application, click Set URL for development in the Callback URL field.

2. Log in on Yandex with the user account that the application will be working on behalf of, then click the linkthat looks like this:

https://oauth.yandex.com/authorize?response_type=token&client_id=<application ID>

The ID is available in the application properties (click the name of the application to open its properties).

3. On the page that opens, click the Confirm button to grant access to your account. You do not need to grantaccess if a token has already been issued for this application and it has not expired yet.

The OAuth server will redirect you to the address from the Callback URL field, appending the token data afterthe # symbol:

http://www.example.com/token# access_token=<new OAuth token> & expires_in=<token lifespan in seconds>




If the token could not be issued, the OAuth server appends an error code to the address:

http://www.example.com/token# error=<error code>




See alsoAuthorization flowRegistering an application

Device tokenYandex.OAuth allows requesting a token for an application on a specific device. To do this, the token requestor authorization code must specify the device ID and name (the device_id and device_name parametersdescribed in the request parameters in this document). The user can see this name on the access managementpage in Passport. If only the ID is specified without the name, the token is marked as issued for an unknowndevice.

Developer's guide


33





Restriction:An application can't have more than 20 tokens associated with devices for a specific user. If Yandex.OAuthsuccessfully issues the application a new token for a device, the oldest token stops working.

Revoking a token on a specific deviceUse a request to Yandex.OAuth to revoke a token issued for a specific device, for example, to guarantee loggingout of an account.

To revoke a token, pass it to Yandex.OAuth with the application ID and password.

Application authenticationRequests to Yandex.OAuth should specify the ID and password that were generated during applicationregistration.

There are various ways to pass them in the request:

• In the Authorization header, base64-encoded in the <client_id>:<client_secret> string.In this case, specify the Basic authorization method.

Header example:

Authorization: Basic NDc2MDE4N2Q4MWJjNGI3Nzk5NDc2YjQycjUxMDM3MTM6ZjI1YmViZjk5MWZmNDE5ODkzZGIyNTU3MjhlNGUxZGU=

• In the body of the POST request, in the client_id and client_secret parameters. These parametersmust be passed at the same time.

If Yandex.OAuth receives the Authorization header, the client_id and client_secret parametersin the request body are ignored.

Request formatSend the request over the HTTPS protocol using the POST method.

Request format for revoking a token:

POST /revoke_token HTTP/1.1Host: oauth.yandex.ruContent-type: application/x-www-form-urlencodedContent-Length: <length of the request body>[Authorization: Basic <encoded client_id:client_secret string>]

access_token=<token to revoke>[& client_id=<application ID>][& client_secret=<application password>]


Required parameter

access_token The OAuth token to revoke.



This parameter is required if the Authorization headerwas omitted in the request.

Developer's guide


34


Parameter Descriptionclient_secret Application password. Available in the application

properties (click the name of the application to openits properties).

This parameter is required if the Authorization headerwas omitted in the request.

Response formatYandex.OAuth returns the response in a JSON document.

The token was revoked successfully or was already invalidA response is returned with the HTTP 200 code and the following message body:

{ "status": "ok"}

An error occurredIf the request could not be executed, the response returns the HTTP error code and description:

{ "error_description": "Client not found", "error": "invalid_client"}

Key Descriptionerror_description Human-readable error description.

error Error code. The table below lists possible error codes.

Supported error codesHTTP responsecode

Error code Description

400 invalid_request Invalid request format (omitted required parameter, and so on).

400 invalid_grant The token that was passed does not belong to the specified app.

400 or 401 invalid_client Returned in the following cases:

• The application with the specified ID was not found or is blocked.

• An invalid password was passed for the specified application ID.

The HTTP 401 response code is returned if the application ID and passwordwere passed in the Authorization header. Otherwise, the HTTP 400 codeis returned.

400 unsupported_token_type

The token can't be revoked because the request for this token did not specifythe device ID (the device_id parameter).

If the token can't be revoked, you can delete it from local storage so theapplication loses access to the user's data.

Developer's guide


35



Revoking tokensYandex.OAuth revokes tokens in the following cases:

• The user revoked the token on the Third party clients page. When an OAuth token is revoked,the corresponding refresh token is revoked automatically.

• The token expired.

• The application owner changed the requested permissions or the value of the Callback URL field, or deletedthe application. In this case, all tokens that were ever issued to this application are revoked.

• The user performed an action that revokes all OAuth tokens and refresh tokens ever issued for the account:

• Changed the password.

• Enabled or disabled two-factor authentication.

• Successfully restored account access.

• Clicked the Log out of all computers link in Passport or another service.

Revoking tokens in the applicationAn application can revoke OAuth tokens that were issued for a specific device, using a special requestto Yandex.OAuth.

To log out of an account for regular tokens, you can delete the account's tokens from local storage. There is noway to restore a deleted token using Yandex.OAuth, so the application will have to request access again.

However, nothing will change for the user on the Third party clients page. The token issued to the applicationwill be considered active until it is revoked in one of the ways listed above.

Developer's guide


36


https://help.yandex.com/passport/authorization/twofa.xml

https://passport.yandex.com/passport?mode=passport


console application 9, 14debugging token 33desktop applications 29mobile applications 25OAuth 4oauth.yandex.com 33oauth.yandex.ru 4refresh 20script 9smart tv 14token 20web service 22

Index


OAuth authorizationDeveloper's guide

9.04.2018

Documents

OAuth authorization. Developer's guide - Yandex · PDF fileOAuth in Yandex The OAuth 2.0 protocol allows applications to access Yandex services on behalf of a user. Access is explicitly