OAuth 2.0 is simple and straightforward.

On Habré already wrote about OAuth 1.0 , but there was no clear explanation of what OAuth 2.0 was. Below I will explain the differences and advantages of OAuth 2.0 and how it is better to use it on websites, in mobile and desktop applications.

What is OAuth 2.0?

OAuth 2.0 is an authorization protocol that allows you to give one service (application) the right to access user resources on another service. The protocol eliminates the need to trust the application username and password, and also allows you to issue a limited set of rights, but not all at once.

')

What is the difference between OpenID and OAuth?

Despite the fact that there were already many explanations on this topic, it still causes some confusion.



OpenID is intended for authentication - that is, in order to understand that this particular user is who he is. For example, with the help of OpenID, a certain Ololo service can understand that a user who has gone there is Roma Novikov with Mail.Ru. With the next authentication, Ololo will be able to recognize him again and understand that this is the same Roma as last time.



OAuth is an authorization protocol, that is, it allows you to issue rights to actions that Ololo himself can perform in Mail.Ru on behalf of Roma. At the same time, Roma, after logging in, may not participate at all in the process of performing actions, for example, Ololo will be able to independently upload photos to the Romin account.

How OAuth 2.0 works

Like the first version, OAuth 2.0 is based on the use of basic web technologies: HTTP requests, redirects, etc. Therefore, using OAuth is possible on any platform with access to the Internet and browser: on websites, mobile and desktop applications, plug-ins for browsers ...



The key difference from OAuth 1.0 is simplicity. In the new version there are no bulky signature schemes, the number of requests required for authorization has been reduced.



The general operation of an application using OAuth is:

1. obtaining authorization
2. access to protected resources

The result of the authorization is access token — a key (usually just a set of characters), the presentation of which is a pass to protected resources. In the simplest case, access to them occurs via HTTPS with indication in the headers or as one of the parameters of the received access token 'a.



The protocol describes several authorization options suitable for different situations:

• authorization for server-side applications (most often, these are websites and web applications)
• authorization for fully client applications (mobile and desktop applications)
• login and password authentication
• restore previous authorization

Authorization for applications with server side

1. Redirect to the login page
2. On the authorization page the user is asked to confirm the issuance of rights
3. If the user agrees, the browser will redirect to the URL specified when opening the authorization page, with the addition of a special key to the GET parameters - authorization code
4. The application server performs a POST request with the received authorization code as a parameter. This request returns access token.

This is the most difficult authorization option, but only it allows the service to unambiguously install the application requesting authorization (this happens during communication between the servers in the last step). In all other cases, authorization takes place entirely on the client and for obvious reasons it is possible to disguise one application as another. This should be taken into account when implementing OAuth authentication in the services API.

Example

Here and further examples are given for the Mail.Ru API, but the logic is the same for all services, only the addresses of the authorization pages change. Please note that requests must be made over HTTPS .



Redirect user's browser to the login page:

 > GET / oauth / authorize? Response_type = code & client_id = 464119 &
       redirect_uri = http% 3A% 2F% 2Fexample.com% 2Fcb% 2F123 HTTP / 1.1
 > Host: connect.mail.ru

Hereinafter, client_id and client_secret are the values ​​obtained when registering the application on the platform.



After the user issues the rights, a redirect occurs to the specified redirect_uri :

 <HTTP / 1.1 302 Found
 <Location: http://example.com/cb/123?code=DoRieb0y

Please note that if you implement a login on the site using OAuth, then it is recommended to add a unique identifier for each user in redirect_uri to prevent CSRF attacks (in the example, this is 123). When receiving the code, you need to check that this identifier has not changed and corresponds to the current user.



Use the received code to get the access_token by executing the request from the server:

 > POST / oauth / token HTTP / 1.1
 > Host: connect.mail.ru
 > Content-Type: application / x-www-form-urlencoded
 > 
 > grant_type = authorization_code & client_id = 464119 & client_secret = deadbeef & code = DoRieb0y &
   redirect_uri = http% 3A% 2F% 2Fexample.com% 2Fcb% 2F123

 <HTTP / 1.1 200 OK
 <Content-Type: application / json
 <
 <{
 <"access_token": "SlAV32hkKG",
 <"token_type": "bearer",
 <"expires_in": 86400,
 <"refresh_token": "8xLOxBtZp8",
 <}

Please note that the last request uses client_secret, which in this case is stored on the application server, and confirms that the request is not forged.



As a result of the last request, we get the access key itself ( access_token ), its “fading” time ( expires_in ), the key type that determines how it should be used ( token_type ) and refresh_token , which will be described in more detail below. Further, the data obtained can be used to access protected resources, for example, the Mail.Ru API:

 > GET /platform/api?oauth_token=SlAV32hkKG&client_id=464119&format=json&method=users.getInfo&
       sig = ... http / 1.1
 > Host: appsmail.ru

Description in the specification

Authorize fully client applications

1. Opening the built-in browser with the authorization page
2. The user is asked to confirm the issuance of rights
3. If the user agrees, the browser will redirect to the stub page in the fragment (after #) the URL of which is added access token
4. The application intercepts the redirect and gets access token from the page address

This option requires raising the browser window in the application, but does not require the server part and an additional server-server call for the exchange of authorization code for access token .

Example

Open the browser with the authorization page:

 > GET / oauth / authorize? Response_type = token & client_id = 464119 HTTP / 1.1
 > Host: connect.mail.ru

After the user issues the rights, a redirect to the standard stub page occurs, for Mail.Ru this is connect.mail.ru/oauth/success.html :

 <HTTP / 1.1 302 Found
 <Location: http://connect.mail.ru/oauth/success.html#access_token=FJQbwq9&token_type=bearer&
             expires_in = 86400 & refresh_token = yaeFa0gu

The application should intercept the last redirect, get from the address acess_token and use it to access protected resources.



Description in the specification

Login and password authentication

Login and password authorization is a simple POST request, which results in an access token being returned. Such a scheme is nothing new, but is inserted into the standard for generality and is recommended for use only when other authorization options are not available.

Example

 > POST / oauth / token HTTP / 1.1
 > Host: connect.mail.ru
 > Content-Type: application / x-www-form-urlencoded
 > 
 > grant_type=password&client_id=31337&client_secret=deadbeef&username=api@corp.mail.ru&
   password = qwerty

 <HTTP / 1.1 200 OK
 <Content-Type: application / json
 <
 <{
 <"access_token": "SlAV32hkKG",
 <"token_type": "bearer",
 <"expires_in": 86400,
 <"refresh_token": "8xLOxBtZp8",
 <}

Description in the specification

Restore previous authorization

Usually, access token has a limited shelf life. This can be useful, for example, if it is transmitted over open channels. In order not to force the user to pass authorization after the access token 'a has expired, in all of the above options, in addition to the access token ', another refresh token can be returned. According to it, you can get access token using an HTTP request, similar to authorization by login and password.

Example

 > POST / oauth / token HTTP / 1.1
 > Host: connect.mail.ru
 > Content-Type: application / x-www-form-urlencoded
 > 
 > grant_type = refresh_token & client_id = 31337 & client_secret = deadbeef & refresh_token = 8xLOxBtZp8

 <HTTP / 1.1 200 OK
 <Content-Type: application / json
 <
 <{
 <"access_token": "Uu8oor1i",
 <"token_type": "bearer",
 <"expires_in": 86400,
 <"refresh_token": "ohWo1ohr",
 <}

Description in the specification

Cons OAuth 2.0

In all this beauty there is a fly in the ointment, where without it?



OAuth 2.0 is an evolving standard. This means that the specification is not yet established and is constantly changing, sometimes quite noticeably. So, if you decide to support the standard right now, be prepared for the fact that its support will have to be filed as the specification changes. On the other hand, it also means that you can participate in the process of writing a standard and contribute your own ideas to it.



OAuth 2.0 security is largely SSL based. This greatly simplifies the life of developers, but requires additional computational resources and administration. This can be a significant issue in highly loaded projects.

Conclusion

OAuth is a simple authorization standard based on the basic principles of the Internet, which makes it possible to use authorization on almost any platform. The standard has the support of the largest sites and it is obvious that its popularity will only grow. If you are thinking about the API for your service, then authorization using OAuth 2.0 is a good choice.



For our part, we implemented OAuth 2.0 into the Mail.Ru API and, now, you can use the protocol capabilities to implement any clients and services integrated with Mail.Ru.

Links

• The current version of the draft standard OAuth 2.0
• OAuth official website
• Standard Development Working Group ( archives )
• Documentation on the implementation of OAuth 2.0 in Mail.Ru

Dmitry Bitman - Platform@Mail.Ru manager