OAuth 2.
0 BasicsIshara KarunarathnaBlockedUnblockFollowFollowingApr 17In my previous article “Say Hello to OAuth 2.
0” I discussed about concepts and main actors behind OAuth 2.
0 framework.
Idea of this article is to get familiar remaining bits and pieces, mainly this article It’ll discuss different flows (grant types) that can be used to get an access token and recommendation on choosing grant types.
Quick Refresher — OAuth 2.
0 ConceptsResource ownerAn entity capable of granting access to a protected resource.
When the resource owner is a person, it is referred to as an end-user.
Resource serverThe server hosting the protected resources, capable of accepting and responding to protected resource requests using access tokens.
ClientAn application making protected resource requests on behalf of the resource owner and with his authorization.
The term “client” does not imply any particular implementation characteristics (e.
g.
, whether the application executes on a server, a desktop, or other devices).
Authorization serverThe server issuing access tokens to the client after successfully authenticating the resource owner and obtaining authorization.
Access tokensAccess tokens are credentials used to access protected resources.
An access token is a string representing an authorization issued to the client.
The string is usually opaque to the client.
Tokens represent specific scopes and duration of access, granted by the resource owner and enforced by the resource server and authorization server.
Refresh TokenRefresh tokens are the credentials used to obtain access tokens.
Refresh tokens are issued to the client by the authorization server and are used to obtain a new access token when the current access token becomes invalid or expires, or to obtain additional access tokens with identical or narrower scope.
ScopeThe level of access that the application is requesting.
The authorization server may fully or partially ignore the scope requested by the client, based on the authorization server policies or the resource owner’s instructions.
Register Client with Authorization serverPrior to get an access token, trust relationship should be established between client application and the Authorization server.
Client application has to be registered in the authorization server to initiate this trust relationship.
There are two common ways used to register an application.
Use dynamic client registration (DCR) APIManually create a client application in Authorization server (Using admin console or CLI tool)In general for registered clients, authorization server will issue, a client id and a client Secret.
Client id : String value that uniquely identify the client application in authorization server.
Client secret : This is a secret value that can be used with client id to authenticate with the authorization server.
(If client secret is used client application should be able to protect it in application end)OAuth 2.
0 Protocol EndpointsThere are two endpoints in the authorization server used in obtaining an access token.
Authorization endpoint — used by the client application to obtain authorization grant from the resource owner via user-agent redirection.
Token endpoint — used by the client application to exchange an authorization grant for an access token, typically with client authentication.
And there is a client endpoint:Redirection endpoint — used by the authorization server to return responses containing authorization grants to the client via the resource owner user-agent.
OAuth 2.
0 Grant TypesOAuth 2.
0 grant types define different flows how applications get access tokens from authorization server.
OAuth 2.
0 core specification defines four main grant typesAuthorization codeImplicitPasswordClient credentialsThese grant types are optimized based on different applications and their use cases.
Further there are several extended grant types for additional use cases.
Authorization CodeThe authorization code grant type is the most commonly used and secure way of delegating authorization grant.
This is a redirection based grant type hence client application should be able to interact with web browsers (user-agent).
Different client authentication mechanisms and flow extensions like PKCE, used with the authorization code grant to enhance the security.
The client application initiates the flow and redirect the browser to the authorization endpoint in the authorization server.
The authorization server authenticates the resource owner (via browser).
Authorization server redirect user back to the client application with an authorization code (code)Client application authenticates with the authorization server and requests an access token from the authorization server’s token endpoint by including the authorization code.
Authorization server validate the client credential, authorization code and redirection URI.
If valid responds back with an access token and refresh token.
Client application invoke the protected resources in Resource server with the access token.
Authorization Requesthttps://is.
wso2.
com/authorize?response_type=code&client_id=NHFJ8iff45P7Z0KXhBtVLv9NLsEa&scope=email profile view&state=xy25q6ghkz&redirect_uri=https://playground.
com/callbackresponse_type=code: Required, which is used to differentiate the grant type and indicate the credential type that authorization server returns.
client_id: Required, Application’s Client ID.
When the application is registered in the authorization it will issue the Client ID.
scope: Optional, Space separated strings which represents the level of access that the application requesting.
state: Recommended, An opaque value used by the client to maintain state between the request and callback.
This can be used to prevent security attacks.
redirect_uri: Optional, The URL to which authorization server will redirect the browser after authorization granted.
Authorization ResponseHTTP/1.
1 302 FoundLocation: https://playground.
com/callback?code=SplxlOBeZQQYbYS6WxSbIA&state=xy25q6ghkzcode: Short living token which represent the authorization grant.
Available in the URL parameters.
Client must not use this more than once.
state: Exact value received from the client in authorization request.
Access Token RequestPOST /token HTTP/1.
1 Host: is.
wso2.
com Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW Content-Type: application/x-www-form-urlencodedgrant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA&redirect_uri=https%3A%2F%2Fplayground.
com%2Fcallbackgrant_type=authorization_code: Required, This value must be authorization_code.
client_id: Application’s Client ID.
Required, if the client is not authenticating with the Authorizationcode: Required, The Authorization Code received from the authorization server.
redirect_uri: Required, If this was available in the authorization code request values must be identical.
Access Token ResponseIn a successful authorization grant response contains both access token and refresh token.
The entire response looks something like this:HTTP/1.
1 200 OK Content-Type: application/json;charset=UTF-8 Cache-Control: no-store Pragma: no-cache { “access_token”:”2YotnFZFEjr1zCsicMWpAA”, “token_type”:”bearer”, “expires_in”:3600, “refresh_token”:”tGzv3JOkF0XG5Qx2TlKWIA”}ImplicitThe implicit grant type was initially designed for the applications such as SPA (Single page application where source code resides in the browser) or mobile applications which can’t securely store the client secret within the applications or if its unable to do a cross origin requests.
Compared to authorization code flow access token will be shared as a URL fragment in the initial authorization request eliminating intermediate step of exchanging code with a token.
Further it wont issues a refresh token if required to extend the validity of the access token client has to use different methods such as silent refresh.
With modern browser technologies and security threats this grant type is no longer recommended and authorization code is used with modifications over implicit grant type.
The client application initiates the flow and redirect the browser to the authorization endpoint in the authorization server.
The authorization server authenticates the resource owner (via browser).
Authorization server redirect user back to the client application with the access token in the URI fragment.
Client application invoke the protected resources in Resource server with the access token.
Authorization RequestGET https://is.
wso2.
com/authorize?response_type=token&client_id=s6BhdRkqt3&state=xyz&redirect_uri=redirect_uri=https%3A%2F%2Fplayground.
com%2Fcallback HTTP/1.
1response_type=token: Required, which is used to differentiate the grant type and indicate the credential type that authorization server returns.
client_id: Required, Application’s Client ID.
When the application is registered in the authorization it will issue the Client ID.
scope: Optional, Space separated strings which represents the level of access that the application requesting.
state: Recommended, An opaque value used by the client to maintain state between the request and callback.
This can be used to prevent security attacks.
redirect_uri: Optional, The URL to which authorization server will redirect the browser after authorization granted.
Access Token ResponseIn a successful authorization grant response contains the access token in the URI fragment The entire response looks something like this:HTTP/1.
1 302 FoundLocation: https://playground.
com/callback#access_token=2YotnFZFEjr1zCsicMWpAA&state=xyz&token_type=bearer&expires_in=3600PasswordIn the resource owner password credentials grant type, client application directly get the end users credentials (username and password) to the client applications, then pass these credentials to the authorization server in request of access token.
In this flow its not possible to enforce any other authentication mechanisms such as multi factor authentication (MFA) to verify the actual user, and application can get the full access privileges since application has user’s credentials.
Hence this grant type is discouraging to use and it should only be used if and only if other flows are not viable.
Also, it should only be used if the application is trusted by the end user.
Resource owner provides the client with its username and password.
The client requests an access token from the authorization server’s token endpoint by including the credentials received from the resource owner.
Authorization server authenticate the client and resource owner and issues an access token and refresh token.
Client application invoke the protected resources in Resource server with the access token.
Access Token RequestPOST /token HTTP/1.
1 Host: is.
wso2.
com Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW Content-Type: application/x-www-form-urlencoded grant_type=password &username=ishara &password=A3ddj3wgrant_type=password: Required, which is used to differentiate the grant typeclient_id: Required, Application’s Client ID.
When the application is registered in the authorization it will issue the Client ID.
username: Required, resource owner user namepassword: Required, resource owner passwordscope: Optional, Space separated strings which represents the level of access that the application requesting.
state: Recommended, An opaque value used by the client to maintain state between the request and callback.
This can be used to prevent security attacks.
Access Token ResponseIn a successful authorization grant response contains both access token and a refresh token.
The entire response looks something like this:HTTP/1.
1 200 OK Content-Type: application/json;charset=UTF-8 Cache-Control: no-store Pragma: no-cache{ “access_token”:”2YotnFZFEjr1zCsicMWpAA”, “token_type”:”bearer”, “expires_in”:3600, “refresh_token”:”tGzv3JOkF0XG5Qx2TlKWIA” }Client CredentialsIn the case of end user (resource owner) and client application are same, client credentials grant type is used.
Since application is the resource owner, no end user authorization required, only client credentials are used to authenticate with the authorization server.
In the machine to machine communications this grant type is mostly used.
The client authenticates with the authorization server and requests an access token from the token endpoint.
The authorization server authenticates the client, and issues an access token.
Client application invoke the protected resources in Resource server with the access token.
Access Token RequestPOST /token HTTP/1.
1 Host: is.
wso2.
com Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW Content-Type: application/x-www-form-urlencoded grant_type=client_credentialsThe authorization server MUST authenticate the client.
grant_type=client_credentials: Required, which is used to differentiate the grant typeclient_id: Required, Application’s Client ID.
When the application is registered in the authorization it will issue the Client ID.
scope: Optional, Space separated strings which represents the level of access that the application requesting.
state: Recommended, An opaque value used by the client to maintain state between the request and callback.
This can be used to prevent security attacks.
Access Token ResponseIn a successful authorization grant response contains the access token .
The entire response looks something like this:HTTP/1.
1 200 OK Content-Type: application/json;charset=UTF-8 Cache-Control: no-store Pragma: no-cache{ “access_token”:”2YotnFZFEjr1zCsicMWpAA”, “token_type”:”bearer”, “expires_in”:3600 }Refresh Token FlowWith the authorization code grant type or client credentials grant type refresh token is issued.
If the access token is expired, or to get a new access token with reduced scope refresh token grant can be used.
In this flow without end users interaction, authorization server will validate the refresh token and issue a new access token.
The client authenticates with the authorization server and requests an access token from the token endpoint.
The authorization server authenticates the client, and issues an access token.
Client application invoke the protected resources in Resource server with the access token.
RequestPOST /token HTTP/1.
1 Host: is.
wso2.
com Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW Content-Type: application/x-www-form-urlencoded grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIAgrant_type=refresh_token: Required, which is used to differentiate the grant type.
refresh_token: Required, refresh token received from the authorization serverscope: Optional, Originally access granted scopes or limited access compared to originally granted scope.
state: Recommended, An opaque value used by the client to maintain state between the request and callback.
This can be used to prevent security attacks.
ResponseIn a successful authorization grant response contains both access token and a refresh token.
The entire response looks something like this:HTTP/1.
1 200 OK Content-Type: application/json;charset=UTF-8 Cache-Control: no-store Pragma: no-cache{ “access_token”:”2YotnFZFEjr1zCsicMWpAA”, “token_type”:”bearer”, “expires_in”:3600, “refresh_token”:”tGzv3JOkF0XG5Qx2TlKWIA” }Which OAuth 2.
0 Grant to UseGrant types define different flows that can be used to get an access token in different use cases.
There are pros and cones in each grant type so based on our need we need to evaluate the trade-offs and select the best grant type.
Future I’ll discuss how these grant types best fit with different application types and use cases in advance.
Until that here I have listed the general recommendation of using grant types.
Resource owner and client application are same / Machine to machine communicationClient credentials grant type is recommended in this use case.
No end user interaction hence client credentials are used to authenticate client into the authorization server when requesting access token.
Web / SPA (single page application) / Mobile applicationsAuthorization code grant type is the recommended grant type for all of these applications.
There are different extensions like PKCE and application specific recommendations on using authorization code flow in each of these applications types.
If there are no limitations application developers should retain from using implicit and password grant types for these use-cases.
In future I’ll will discuss separately on each application type.
Other Use-casesBased on different use cases OAuth 2.
0 framework had been extended and implement different grant types such as, SAML 2.
0 bearer grant type, JWT bearer grant types etc.
Hence based on use cases, evaluating security considerations developers should use each of these extensions.
ResourcesRFC 6749 — The OAuth 2.
0 Authorization Framework : https://tools.
ietf.
org/html/rfc6749.