Skip to main content

OAuth 2.0 service provider

note

This article is intended primarily to indicate system support for this standard. For more information, see the standard description or its documentation.

tip

This authorization method is intended to simplify the development and connection of third-party applications to the system. To authorize requests made to the system directly, request tokens manually.

caution

If you are developing a single-page, mobile or native application, make sure you can ensure Client Secret privacy.

See OAuth documentation for more details.

One of the main ideas behind OAuth 2.0 is to provide a secure and convenient way to authorize an end user accessing the system through a third-party application. It allows the user to provide the application the right to interact with the system on his behalf, and to define the level of interaction without revealing user credentials.

For a third-party developer, the use of this standard means simplified application development: instead of creating a custom authorization mechanism with subsequent storage of credential hashes, it is possible to adapt ready-made compact libraries used for interaction with the OAuth service to the project. In addition, user login and password remain unknown for the application what reduces the possibility of data leakage.

Terms and entities​

To avoid possible confusion, let's define the main terms and entities of the article:

  • Access token — short-term token used to authorize requests to resources
  • Client — an application requesting access to a resource from a service on behalf of a user
  • Client credentials — client identifier and secret used to identify requests from the client to the service
  • Client ID — a public unique identifier under which the client is known to the service. It is used to determine whether authorization requests received by the service belong to the client
  • Client secret — a private key used for encryption and authentication of messages transmitted between the service and the client
  • Code — a code issued to the client for initial token generation after successful authorization of the user in the system
  • Receiving page (Redirect URI) — client's own resource to which the service will redirect the user in case of successful authorization in the system
  • Refresh token — long-term token used to refresh the Access token
  • Resource — an object or a set of data, access to which is regulated by the security and access control policies of the service
  • Scope — an access right that regulates both the ability to interact with a resource and the manner of that interaction
  • Service — an OAuth 2.0 service providing client registration, user authorization and subsequent provision of access to the system
  • System — a server storing resources protected by the service
  • User — a person who has access rights to the resource
  • User credentials — login and password under which the user is known to the system.

It should be kept in mind that these definitions are conditional and intended for general understanding of the article only. For example, the system does not consist of only one resource server, but in the context of this article such clarifications may be unnecessary.

Operational logic​

For a general understanding of how this mechanism works, the authorization process can be described in the following steps:

  1. The user wants to use the client to access a resource
  2. The client redirects the user to the service to authorize him in the system with the user credentials
  3. The service asks the user for the list of permissions he agrees to grant to the client
  4. Once the list is approved, the service redirects the user to the redirect page and attaching a code to the transmitted response
  5. The client without user's participation accesses the service with the code received earlier to receive authorization tokens
  6. The service returns access and refresh tokens to the client
  7. The client on behalf of the user (more precisely, the user using the client) accesses the system resources using the access token obtained
    • Access token expired — the client asks the service for a new access token using refresh token
    • Refresh token expired — the process starts from the beginning

Like the list of terms, this description of the operational logic is also very tentative. It should be remembered that behind each step conceals a lot of additional actions, which is no sense to describe in this article.

note

Although the tokens issued to the client are similar to those that the user can request from the service manually, they still have a significant difference in the lifetime of the refresh token:

  • Issued to the user - 1 year
  • Issued to the client - 1 month

The lifetime of the access token is the same in both cases and is equal to 30 minutes.

Implementation​

Since this article aims to provide a general description of this authorization method, it will not provide detailed instructions on how to create OAuth clients for different platforms and types of applications. For those who want such information we recommend to read the OAuth documentation. However, a description of some of the basic steps required to implement OAuth 2.0 is available below.

Get client credentials​

For successful interaction with the service, the client application must have its own Client ID and Client Secret. To get them, the application must be registered in the developer account:

  1. Log in to an existing or create a new developer account
  2. Go to the My Apps page and click Add.
  3. Set the name and Redirect URL of your application.
  4. Press Create

Keep in mind that:

  • The application may have any name. The name is needed only to identify it in the list
  • The Redirect URL must be the address of the receiving page to which the browser will redirect the user after authorization and provisioning. Depending on the location of the receiving page, either a local or external address can be specified
  • The address must be set in full, including the connection protocol prefix
  • The receiving page must be accessible via HTTPS. Redirect URL with prefix http:// will be discarded by the service as insecure

In case of successful addition, the service will create an application card on the same page and generate Client ID and Client Secret for it, by which this application will be identified in future.

  • Client ID — public unique identifier under which the application is known to the service. It is used to determine whether authorization requests received by the service belong to this particular application
  • Client Secret — an application private key used to encrypt and authenticate messages transmitted between the service and the application

When Client ID does not contain sensitive information and can be transmitted publicly, disclosure of Client Secret to an unrestricted audience (e.g., when transmitted in a code-request) may result in compromise of user accounts and unauthorized access to protected resources.

In case of inadvertent disclosure of Client Secret, the application card has a Update Client Secret button. Clicking it asks the service to generate a new secret for the same identifier.

Getting the code​

To get the code required for subsequent token creation, the client must redirect the user to the service as part of the corresponding authorization request and be able to process the response returned in case of successful authorization.

Request​

A detailed description of the authorization request is available in OAuth documentation, so let's just briefly look at an example of what data the service expects to receive from the client.

Example of GET request for authorization
https://oauth.alor.ru/authorize?
  client_id= 394...6ff
  &scope= trades
  &response_type= code
  &redirect_uri= https://example.com/callback
  &state= rtq...gew

Where:

  • https://oauth.alor.ru is the address of authorization service for production system environment
  • client_id is the identifier obtained during client registration
  • scope is the list of permissions for access to certain groups of system resources. If you need to specify several permissions, list them with a space (scope=trades ordersread personal).
  • response_type is the requested object. Accepts only one of two values: code and token. Use code
  • redirect_uri is the address of receiving page to which the service should redirect the user together with the requested code after successful authorization
  • state is the client-generated connection identifier, which the server will return unchanged
tip

The request may also contain the client_secret parameter, where the secret obtained during application registration is passed. However, it is not recommended to pass it when obtaining code in single-page, native and mobile applications, since in these cases the secret is passed in a public form and its leakage will lead to application compromise.

Although the scope parameter is listed as optional in the OAuth documentation, in the case of the discussed OAuth service, this parameter is mandatory.

  • OrdersRead — reading of previously placed orders
  • OrdersCreate — placing, modifying and withdrawing orders
  • Trades — reading of transactions made by the user
  • Personal — reading user's personal information: name, mail, etc.
  • Stats — reading user statistics: profit, average prices, etc.
tip

The permissions requested in scope may be rejected by the user at the authorization stage. For example, the application requesting ordersread orderscreate trades but received trades only as the user declined other options. Consider the possibility of such situation and be able to handle options other than requested.

note

The service does not support PKCE, so the code_challenge and code_challenge_mode request parameters described in the OAuth documentation will be silently discarded.

Reply​

A detailed description of the response to the request is also available in the OAuth documentation, so here again is just an example response.

Sample code response
https://example.com/callback?
  code= eyJ...xPCg
  &state= rtq...gew

Where:

  • code is the code needed for token generation
  • state is the connection identifier passed earlier

If state was not specified in the query, the response will still contain this field, but its value will be undefined.

Receiving tokens​

The previously obtained code is needed to create access and refresh tokens.

Request​

A description of the request is available in OAuth documentation.

To obtain tokens from the OAuth service, make a POST request with the URL https://oauth.alor.ru/token (address for production environment), passing all required values in the request body, encoded as application/x-www-form-urlencoded.

Example POST request for tokens
grant_type= authorization_code
&code= eyJ...xPCg
&redirect_uri= https://example.com/callback
&client_id= 394...6ff
&client_secret= SjO...pRM

Where:

  • grant_type is the requested access type (always authorization_code)
  • code is the code received earlier
  • redirect_uri is the address of receiving page
  • client_id is the client public unique identifier
  • client_secret is the client private key
tip

At this stage, the client application interacts with the service without the user's participation. Thus, it becomes possible to transfer the secret without the risk of its direct disclosure to each user.

note

The service does not support PKCE, so the code_verifier request parameter will be discarded on receipt.

Reply​

If the request is successfully processed, the service will return in response a json object containing the tokens and their lifetime:

Example of token response
{
  "access_token": "eyJ...sOA",
  "refresh_token": "fe5...73d",
  "token_type": "bearer",
  "expires_in": 1799,
  "refresh_token_expires_in": 5183999
}

Where:

  • access_token is the short-term token used to authorize requests to resources
  • refresh_token is the long-term token used to refresh the Access token
  • token_type is the type of received token
  • expires_in is the remaining lifetime of access token in seconds
  • refresh_token_expires_in is the remaining lifetime of refresh token in seconds

Token update​

When using the code, the service returns both access and refresh tokens within the same message. Each of them has its own lifetime:

  • 30 minutes for access token
  • 1 month for refresh token

The system will discard any requests to resources accompanied by a token with expired lifetime, therefore, it is necessary to provide a mechanism for timely updating tokens in the client.

To get a new access token, use the refresh token in the corresponding HTTP request. But to get a new refresh token, the user must re-authorize.

Use of tokens​

The usability of tokens received from the OAuth service is completely identical to those received manually: the update token is used to create access tokens, which in turn are used to authorize requests to HTTP, WebSocket and GraphQl interfaces.

Test environment​

Although the user manually accesses the OAuth service of this environment (https://oauthdev.alor.ru) when retrieving test env tokens, connecting applications to it is meaningless for a few reasons:

  • You cannot register an application in the test environment, which makes it impossible to get your own Client ID and Client Secret
  • Due to the inability to register an application, you cannot specify your own Redirect URI
  • Authorization of users in the test environment requires corresponding accounts
  • Steps with code generation and its subsequent use to create tokens are performed without the client's participation, so the user receives tokens immediately after authorization

Thus, even though the OAuth service exists in the test environment, applications can only access it with some generic Client ID and cannot receive any messages once the user is authorized.

Application Examples​

As examples that can help in implementing OAuth 2.0 in your application, we can recommend the following options: