OAuth Roles<\/h2>\n
OAuth defines four roles:<\/p>\n
- \n
- Resource Owner<\/li>\n
- Client<\/li>\n
- Resource Server<\/li>\n
- Authorization Server<\/li>\n<\/ul>\n
We will detail each role in the following subsections.<\/p>\n
Resource Owner:\u00a0User<\/em><\/h3>\n
The resource owner is the\u00a0user<\/em>\u00a0who authorizes an\u00a0application<\/em>\u00a0to access their account. The application’s access to the user’s account is limited to the “scope” of the authorization granted (e.g. read or write access).<\/p>\n
Resource \/ Authorization Server:\u00a0API<\/em><\/h3>\n
The resource server hosts the protected user accounts, and the authorization server verifies the identity of the\u00a0user<\/em>\u00a0then issues access tokens to the\u00a0application<\/em>.<\/p>\n
From an application developer’s point of view, a service’s\u00a0API<\/strong>\u00a0fulfills both the resource and authorization server roles. We will refer to both of these roles combined, as the\u00a0Service<\/em>\u00a0or\u00a0API<\/em>\u00a0role.<\/p>\n
Client:\u00a0Application<\/em><\/h3>\n
The client is the\u00a0application<\/em>\u00a0that wants to access the\u00a0user<\/em>‘s account. Before it may do so, it must be authorized by the user, and the authorization must be validated by the API.<\/p>\n
<\/div>\nAbstract Protocol Flow<\/h2>\n
Now that you have an idea of what the OAuth roles are, let’s look at a diagram of how they generally interact with each other:<\/p>\n
![\"Abstract](\"https:\/\/assets.digitalocean.com\/articles\/oauth\/abstract_flow.png\")
<\/p>\nHere is a more detailed explanation of the steps in the diagram:<\/p>\n
- \n
- The\u00a0application<\/em>\u00a0requests authorization to access service resources from the\u00a0user<\/em><\/li>\n
- If the\u00a0user<\/em>\u00a0authorized the request, the\u00a0application<\/em>\u00a0receives an authorization grant<\/li>\n
- The\u00a0application<\/em>\u00a0requests an access token from the\u00a0authorization server<\/em>\u00a0(API) by presenting authentication of its own identity, and the authorization grant<\/li>\n
- If the application identity is authenticated and the authorization grant is valid, the\u00a0authorization server<\/em>\u00a0(API) issues an access token to the application. Authorization is complete.<\/li>\n
- The\u00a0application<\/em>\u00a0requests the resource from the\u00a0resource server<\/em>\u00a0(API) and presents the access token for authentication<\/li>\n
- If the access token is valid, the\u00a0resource server<\/em>\u00a0(API) serves the resource to the\u00a0application<\/em><\/li>\n<\/ol>\n
The actual flow of this process will differ depending on the authorization grant type in use, but this is the general idea. We will explore different grant types in a later section.<\/p>\n
<\/div>\nApplication Registration<\/h2>\n
Before using OAuth with your application, you must register your application with the service. This is done through a registration form in the “developer” or “API” portion of the service’s website, where you will provide the following information (and probably details about your application):<\/p>\n
- \n
- Application Name<\/li>\n
- Application Website<\/li>\n
- Redirect URI or Callback URL<\/li>\n<\/ul>\n
The redirect URI is where the service will redirect the user after they authorize (or deny) your application, and therefore the part of your application that will handle authorization codes or access tokens.<\/p>\n
Client ID and Client Secret<\/h3>\n
Once your application is registered, the service will issue “client credentials” in the form of a\u00a0client identifier<\/em>\u00a0and a\u00a0client secret<\/em>. The Client ID is a publicly exposed string that is used by the service API to identify the application, and is also used to build authorization URLs that are presented to users. The Client Secret is used to authenticate the identity of the application to the service API when the application requests to access a user’s account, and must be kept private between the application and the API.<\/p>\n
<\/div>\nAuthorization Grant<\/h2>\n
In the\u00a0Abstract Protocol Flow<\/em>\u00a0above, the first four steps cover obtaining an authorization grant and access token. The authorization grant type depends on the method used by the application to request authorization, and the grant types supported by the API. OAuth 2 defines four grant types, each of which is useful in different cases:<\/p>\n
- \n
- Authorization Code<\/strong>: used with server-side Applications<\/li>\n
- Implicit<\/strong>: used with Mobile Apps or Web Applications (applications that run on the user’s device)<\/li>\n
- Resource Owner Password Credentials<\/strong>: used with trusted Applications, such as those owned by the service itself<\/li>\n
- Client Credentials<\/strong>: used with Applications API access<\/li>\n<\/ul>\n
Now we will describe grant types in more detail, their use cases and flows, in the following sections.<\/p>\n
<\/div>\nGrant Type: Authorization Code<\/h2>\n
The\u00a0authorization code<\/strong>\u00a0grant type is the most commonly used because it is optimized for\u00a0server-side applications<\/em>, where source code is not publicly exposed, and\u00a0Client Secret<\/em>\u00a0confidentiality can be maintained. This is a redirection-based flow, which means that the application must be capable of interacting with the\u00a0user-agent<\/em>\u00a0(i.e. the user’s web browser) and receiving API authorization codes that are routed through the user-agent.<\/p>\n
Now we will describe the authorization code flow:<\/p>\n
![\"Authorization](\"https:\/\/assets.digitalocean.com\/articles\/oauth\/auth_code_flow.png\")
<\/p>\nStep 1: Authorization Code Link<\/h3>\n
First, the user is given an authorization code link that looks like the following:<\/p>\n
https:\/\/cloud.digitalocean.com\/v1\/oauth\/authorize?response_type=code&client_id=CLIENT_ID<\/span>&redirect_uri=CALLBACK_URL<\/span>&scope=read<\/span>\r\n<\/code><\/pre>\nHere is an explanation of the link components:<\/p>\n
- \n
- https:\/\/cloud.digitalocean.com\/v1\/oauth\/authorize<\/a><\/strong>: the API authorization endpoint<\/li>\n
- client_id=client_id<\/span><\/strong>: the application’s\u00a0client ID<\/em>\u00a0(how the API identifies the application)<\/li>\n
- redirect_uri=CALLBACK_URL<\/span><\/strong>: where the service redirects the user-agent after an authorization code is granted<\/li>\n
- response_type=code<\/span><\/strong>: specifies that your application is requesting an authorization code grant<\/li>\n
- scope=read<\/span><\/strong>: specifies the level of access that the application is requesting<\/li>\n<\/ul>\n
Step 2: User Authorizes Application<\/h3>\n
When the user clicks the link, they must first log in to the service, to authenticate their identity (unless they are already logged in). Then they will be prompted by the service to\u00a0authorize<\/em>\u00a0or\u00a0deny<\/em>\u00a0the application access to their account. Here is an example authorize application prompt:<\/p>\n
![\"Authorization](\"https:\/\/assets.digitalocean.com\/articles\/oauth\/authcode.png\")
<\/p>\nThis particular screenshot is of DigitalOcean’s authorization screen, and we can see that “Thedropletbook App” is requesting authorization for “read” access to the account of “manicas@digitalocean.com<\/a>“.<\/p>\n
Step 3: Application Receives Authorization Code<\/h3>\n
If the user clicks “Authorize Application”, the service redirects the user-agent to the application redirect URI, which was specified during the client registration, along with an\u00a0authorization code<\/em>. The redirect would look something like this (assuming the application is “dropletbook.com”):<\/p>\n
https:\/\/dropletbook.com\/callback?code=AUTHORIZATION_CODE<\/span>\r\n<\/code><\/pre>\nStep 4: Application Requests Access Token<\/h3>\n
The application requests an access token from the API, by passing the authorization code along with authentication details, including the\u00a0client secret<\/em>, to the API token endpoint. Here is an example POST request to DigitalOcean’s token endpoint:<\/p>\n
https:\/\/cloud.digitalocean.com\/v1\/oauth\/token?client_id=CLIENT_ID<\/span>&client_secret=CLIENT_SECRET<\/span>&grant_type=authorization_code&code=AUTHORIZATION_CODE<\/span>&redirect_uri=CALLBACK_URL<\/span>\r\n<\/code><\/pre>\nStep 5: Application Receives Access Token<\/h3>\n
If the authorization is valid, the API will send a response containing the access token (and optionally, a refresh token) to the application. The entire response will look something like this:<\/p>\n
{\"access_token\":\"ACCESS_TOKEN<\/span>\",\"token_type\":\"bearer\",\"expires_in\":2592000,\"refresh_token\":\"REFRESH_TOKEN<\/span>\",\"scope\":\"read\",\"uid\":100101,\"info\":{\"name\":\"Mark E. Mark\",\"email\":\"mark@thefunkybunch.com\"}}\r\n<\/code><\/pre>\nNow the application is authorized! It may use the token to access the user’s account via the service API, limited to the scope of access, until the token expires or is revoked. If a refresh token was issued, it may be used to request new access tokens if the original token has expired.<\/p>\n
<\/div>\nGrant Type: Implicit<\/h2>\n
The\u00a0implicit<\/strong>\u00a0grant type is used for mobile apps and web applications (i.e. applications that run in a web browser), where the\u00a0client secret<\/em>\u00a0confidentiality is not guaranteed. The implicit grant type is also a redirection-based flow but the access token is given to the user-agent to forward to the application, so it may be exposed to the user and other applications on the user’s device. Also, this flow does not authenticate the identity of the application, and relies on the redirect URI (that was registered with the service) to serve this purpose.<\/p>\n
The implicit grant type does not support refresh tokens.<\/p>\n
The implicit grant flow basically works as follows: the user is asked to authorize the application, then the authorization server passes the access token back to the user-agent, which passes it to the application. If you are curious about the details, read on.<\/p>\n
![\"Implicit](\"https:\/\/assets.digitalocean.com\/articles\/oauth\/implicit_flow.png\")
<\/p>\nStep 1: Implicit Authorization Link<\/h3>\n
With the implicit grant type, the user is presented with an authorization link, that requests a token from the API. This link looks just like the authorization code link, except it is requesting a\u00a0token<\/em>\u00a0instead of a code (note the\u00a0response type<\/em>\u00a0“token”):<\/p>\n
https:\/\/cloud.digitalocean.com\/v1\/oauth\/authorize?response_type=token&client_id=CLIENT_ID<\/span>&redirect_uri=CALLBACK_URL<\/span>&scope=read<\/span>\r\n<\/code><\/pre>\nStep 2: User Authorizes Application<\/h3>\n
When the user clicks the link, they must first log in to the service, to authenticate their identity (unless they are already logged in). Then they will be prompted by the service to\u00a0authorize<\/em>\u00a0or\u00a0deny<\/em>\u00a0the application access to their account. Here is an example authorize application prompt:<\/p>\n
<\/p>\nWe can see that “Thedropletbook App” is requesting authorization for “read” access to the account of “manicas@digitalocean.com<\/a>“.<\/p>\n
Step 3: User-agent Receives Access Token with Redirect URI<\/h3>\n
If the user clicks “Authorize Application”, the service redirects the user-agent to the application redirect URI, and includes a URI fragment containing the access token. It would look something like this:<\/p>\n
https:\/\/dropletbook.com\/callback#token=ACCESS_TOKEN<\/span>\r\n<\/code><\/pre>\nStep 4: User-agent Follows the Redirect URI<\/h3>\n
The user-agent follows the redirect URI but retains the access token.<\/p>\n
Step 5: Application Sends Access Token Extraction Script<\/h3>\n
The application returns a webpage that contains a script that can extract the access token from the full redirect URI that the user-agent has retained.<\/p>\n
Step 6: Access Token Passed to Application<\/h3>\n
The user-agent executes the provided script and passes the extracted access token to the application.<\/p>\n
Now the application is authorized! It may use the token to access the user’s account via the service API, limited to the scope of access, until the token expires or is revoked.<\/p>\n
<\/div>\nGrant Type: Resource Owner Password Credentials<\/h2>\n
With the\u00a0resource owner password credentials<\/strong>\u00a0grant type, the user provides their service credentials (username and password) directly to the application, which uses the credentials to obtain an access token from the service. This grant type should only be enabled on the authorization server if other flows are not viable. Also, it should only be used if the application is trusted by the user (e.g. it is owned by the service, or the user’s desktop OS).<\/p>\n
Password Credentials Flow<\/h3>\n
After the user gives their credentials to the application, the application will then request an access token from the authorization server. The POST request might look something like this:<\/p>\n
https:\/\/oauth.example.com\/token?grant_type=password&username=USERNAME<\/span>&password=PASSWORD<\/span>&client_id=CLIENT_ID<\/span>\r\n<\/code><\/pre>\nIf the user credentials check out, the authorization server returns an access token to the application. Now the application is authorized!<\/p>\n
Note:<\/strong>\u00a0DigitalOcean does not currently support the password credentials grant type, so the link points to an imaginary authorization server at “oauth.example.com”.<\/p>\n
<\/div>\nGrant Type: Client Credentials<\/h2>\n
The\u00a0client credentials<\/strong>\u00a0grant type provides an application a way to access its own service account. Examples of when this might be useful include if an application wants to update its registered description or redirect URI, or access other data stored in its service account via the API.<\/p>\n
Client Credentials Flow<\/h3>\n
The application requests an access token by sending its credentials, its client ID and client secret, to the authorization server. An example POST request might look like the following:<\/p>\n
https:\/\/oauth.example.com\/token?grant_type=client_credentials&client_id=CLIENT_ID&client_secret=CLIENT_SECRET\r\n<\/code><\/pre>\nIf the application credentials check out, the authorization server returns an access token to the application. Now the application is authorized to use its own account!<\/p>\n
Note:<\/strong>\u00a0DigitalOcean does not currently support the client credentials grant type, so the link points to an imaginary authorization server at “oauth.example.com”.<\/p>\n
<\/div>\nExample Access Token Usage<\/h2>\n
Once the application has an access token, it may use the token to access the user’s account via the API, limited to the scope of access, until the token expires or is revoked.<\/p>\n
Here is an example of an API request, using\u00a0
curl<\/code>. Note that it includes the access token:<\/p>\ncurl -X POST -H \"Authorization: Bearer ACCESS_TOKEN<\/span>\"\"https:\/\/api.digitalocean.com\/v2\/$OBJECT<\/span>\" \r\n<\/code><\/pre>\nAssuming the access token is valid, the API will process the request according to its API specifications. If the access token is expired or otherwise invalid, the API will return an “invalid_request” error.<\/p>\n
<\/div>\nRefresh Token Flow<\/h2>\n
After an access token expires, using it to make a request from the API will result in an “Invalid Token Error”. At this point, if a refresh token was included when the original access token was issued, it can be used to request a fresh access token from the authorization server.<\/p>\n
Here is an example POST request, using a refresh token to obtain a new access token:<\/p>\n
https:\/\/cloud.digitalocean.com\/v1\/oauth\/token?grant_type=refresh_token&client_id=CLIENT_ID<\/span>&client_secret=CLIENT_SECRET<\/span>&refresh_token=REFRESH_TOKEN<\/span>\r\n<\/code><\/pre>\n\u00a0source:\u00a0https:\/\/www.digitalocean.com\/community\/tutorials\/an-introduction-to-oauth-2<\/div>\n","protected":false},"excerpt":{"rendered":"Introduction OAuth 2 is an authorization framework that enables applications to obtain limited access to user accounts on an HTTP service, such as Facebook, GitHub, and DigitalOcean. It works by delegating user authentication to the service that hosts the user account, and authorizing third-party applications to access the user account. OAuth 2 provides authorization flows\u2026 Read More »<\/a><\/span><\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"closed","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[30],"tags":[],"class_list":["post-839","post","type-post","status-publish","format-standard","hentry","category-architecture"],"_links":{"self":[{"href":"https:\/\/adriangrigoras.com\/blog\/wp-json\/wp\/v2\/posts\/839","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/adriangrigoras.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/adriangrigoras.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/adriangrigoras.com\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/adriangrigoras.com\/blog\/wp-json\/wp\/v2\/comments?post=839"}],"version-history":[{"count":1,"href":"https:\/\/adriangrigoras.com\/blog\/wp-json\/wp\/v2\/posts\/839\/revisions"}],"predecessor-version":[{"id":840,"href":"https:\/\/adriangrigoras.com\/blog\/wp-json\/wp\/v2\/posts\/839\/revisions\/840"}],"wp:attachment":[{"href":"https:\/\/adriangrigoras.com\/blog\/wp-json\/wp\/v2\/media?parent=839"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/adriangrigoras.com\/blog\/wp-json\/wp\/v2\/categories?post=839"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/adriangrigoras.com\/blog\/wp-json\/wp\/v2\/tags?post=839"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}
- client_id=client_id<\/span><\/strong>: the application’s\u00a0client ID<\/em>\u00a0(how the API identifies the application)<\/li>\n
- Implicit<\/strong>: used with Mobile Apps or Web Applications (applications that run on the user’s device)<\/li>\n
- Authorization Code<\/strong>: used with server-side Applications<\/li>\n
- If the\u00a0user<\/em>\u00a0authorized the request, the\u00a0application<\/em>\u00a0receives an authorization grant<\/li>\n
- The\u00a0application<\/em>\u00a0requests authorization to access service resources from the\u00a0user<\/em><\/li>\n