OAuth 2.0Technical Overview For Common Flows

info@gooddoglabs.com

www.gooddoglabs.com

Internet Security - Identity & Access Management

OAuth 2.0

Is first and foremost a framework

May be reviewed here : http://tools.ietf.org/html/rfc6749

Is primarily an authorization framework

Which separates the role of client from the resource owner, and how resources are accessed

Basically, the client obtains an access token (scope, lifespan, and access attributes) from an authorization server, after authorized from the resource owner to access protected resources on a resource server

And; It is NOT Compatible with OAuth 1.0 and shares few details with OAuth 1.0; but OAuth 2.0 forms the baseline for OpenID Connect, more on this later

Example use case from the IETF OAuth 2.0 Working Group;

“An end-user (resource owner) can grant a printing service (client) access to her protected photos stored at a photo sharing service (resource server), without sharing her username and password with the printing service. Instead, she authenticates directly with a server trusted by the photo sharing service (authorization server), which issues the printing service delegation- specific credentials (access token).”

A bit more about OAuth 2.0

Is very susceptible to attacks, reference this attack in 2013

Has quite a large attack surface due to it’s usage of URI redirects, query parameters, and loose guidance; you can see a sample vulnerability in this message

Framework dropped signature and encryption in favor of bearer tokens; from version 1.0 to version 2.0, see some criticisms from Eran Hammer (previous lead author)

With this said, it’s NOT ALL bad and it serves as a foundation for a new Identity Layer protocol (OpenID Connect), which allows clients to identify the end user based on authentication performed by an authorization server and share profile information in a REST based manner.

OpenID Connect also augments OAuth 2.0 by providing endpoint discovery, dynamic client registration, session management, new response types, and a different way of sharing authorization response parameters.

There are several IETF internet drafts today to address signatures and encryption using JSON profiles. Reference protocol underpinnings here: http://openid.net/connect/

IETF Informational RFC 6819

RFC 6819 is an informational RFC which provides additional security details and considerations for OAuth and It is highly recommended to review and understand this RFC before a mass production deployment of the framework. You may also consult with the team at Good Dog Labs, Inc. for a thorough review and assessment for your OAuth / OpenID Connect implementations.

Let’s start with roles (RRCA)

Resource Owner – Someone or something which owns a resource and grants access to a resource. Think back to the photo sharing example. Owner can be an end user or company. Another example is you giving authorization to an employer to your LinkedIn profile as part of an application for employment.

Resource Server – Server hosting the protected resource or API. For example, LinkedIn API’s providing profile information to clients.

Client – An client component (i.e. application, desktop, device) making requests for protected resources or API interfaces. In general, a client wants to consume information but needs authorization by owner first.

Authorization Server – Server issuing access token to client after successful resource owner authentication and authorization.

OAuth 2.0 High Level Protocol FlowAuthorization Grant Type Agnostic

Let’s clarify some things about the flow

The previous slide describes the “authorization grant agnostic” flow and is not specific to client types or authentication schemes. You will learn about the different grant types and associated flows in the coming slides.

It’s preferred for the client to send an authorization request through the authorization server (known as intermediary)

The client may receive an authorization grant (grant can be any of the four grant types – see next slide) or use an extension grant

Client must authenticate to authorization server in order to receive an access token for the requested resource

Client also must have a valid authorization grant as it’s checked by the authorization server before it sends the access token. No authorization grant, no token. This changes for implicit grants.

Finally, the resource server has final say for resource access by validating the access token provided by client; and if valid, serves the resource to the client (i.e. end user, browser, device)

Access TokensAccess tokens are Credentials used to access protected resources and contain the following:

Scope & Duration – Scope identifies what the client specifically wants and duration is how long the access token is valid. Scope and duration is granted by resource owner and enforced by authorization and resource servers.To retrieve or contain – Token may be used to retrieve authorization information or contain this information inherently.More Restrictive than authorization grants – Removes need for resource server to understand a variety of authentication methods. The resource server’s job is to ensure the access token is valid. Can have different formats and structures – Resource server establishes requirements for token formats.Refresh Tokens – Issued by authorization server to obtain new and fresh access tokens after access token expiration or invalidation. If supported by authorization server, it is usually issued at the same time as the access token. They are only used by authorization servers.

Now, about Client ProfilesThe OAuth 2.0 framework calls for three types:

Web Application – Typically a confidential client running on a web/application server. Resource owner interacts with application. Client credentials and access tokens are stored on the server and used by the application. User – Agent Based Application – A public client in which client code such as java script is running within a user-agent such as a web browser running on a device used by the resource owner. Protocol credentials are easily accessible and visible to the resource owner. A security vulnerability assessment is highly recommended and security considerations MUST be taken into account.Native Application – A public native application such as an iOS or Android application running on a device used by the resource owner. The assumption unless implemented otherwise is that the client credentials are stored locally on the device and can be easily extracted If not encrypted by native application. It’s highly recommended to encrypt client metadata stored locally on device.

What about client registration?This is out of Scope for the OAuth 2.0 Framework, but the following applies:

Client Type – Client types may either be confidential or public; confidential types maintain credential confidentiality by adhering to authentication requirements set by authorization server. It’s important to understand your assurance or exposure levels for credentials and apply the appropriate strength. Also refer to slide 3 and 4.Redirection URI – Redirection URI the authorization server sets in the resource owner’s user-agent in order to redirect back to the client.Other Client Properties – Client registrant may provide application name, logo, and terms and conditions.Client Identifier – Authorization server issues a unique identifier (see the Google sample in next slide) to each client that MUST not be used to authenticate the client. It’s well known and available to resource owners. Also, the size of the identifier is undefined in the RFC. This may provide some challenges when creating client identifier schemes for your implementation.

OpenID Connect Dynamic Client RegistrationThis specification defines how an OpenID Connect Relying Party (Client) can dynamically register with the End-User's OpenID Provider (Authorization Server), providing information about itself to the OpenID Provider, and obtaining information needed to use it, including the OAuth 2.0 Client ID for this Relying Party.

Client AuthenticationThe OAuth 2.0 framework calls for you to decide :

Confidential Clients – In this case, the authorization server and the client agree on an authentication mechanism. This has to be supported by both parties. User name and password (i.e. HTTP Basic Authentication) combination is very popular today just like any other protected resource. Public Clients – Authentication scheme’s and agreements with authorization servers are optional. Request Body (not recommended) – Optionally, a client may send authentication data in HTTP request body to authorization server. This must be supported by both the client and the authorization server. Client_id and client secret may be sent in request body to authenticate client. See Google sample meta-data in slide 14.

Note: TLS and other standard security considerations must be taken into account when performing client – authorization server request/response interactions. The framework doesn’t account for unregistered clients for example. Special security testing and penetration testing MUST be performed before providing access to sensitive resource owner information.

Protocol Endpoints

Authorization – Used to interact with resource owner and obtain an authorization grant; but not before authentication. Authentication scheme must be known to both client and authorization server.

The core OAuth 2.0 framework does not specify how you would discover the authorization endpoint. OpenID Connect changes this by providing a discovery mechanism for it’s OpenID Provider. The OpenID Provider meta-data provides location of OAuth 2.0 authorization endpoint.

Redirection – After resource owner interacts with authorization server, the server sends the resource owner to the client’s redirection endpoint via a user-agent redirection. The client’s endpoint is known to the server due to the pre-requisite client registration with authorization server.

All public and confidential client types using the implicit grant type MUST register.

Protocol Endpoints Continued

It’s good practice to register ALL clients with the authorization server before use.

Multiple redirection URI’s may be registered by client

The redirection URI may be dynamically provided and authorization server may support query strings. In such a case, the authorization server must compare against registered URIs.

Token – Used by clients to obtain an access token. Client presents authorization grant or refresh token. For OpenID, the OpenID Provider meta-data provides location of OAuth 2.0 authorization endpoint.

Access TokensAuthorization & Token endpoints allow the client to set the scope of the access token; in turn the endpoint uses the response parameter to let the client know the scope of the access token issued.

Scope – This is expressed as a space or comma delimited strings; which are defined by the authorization server. Think of the facebook example, in which scope may be limited to just your list of friends.

The authorization server may choose to ignore scope requested by client. Interesting huh? Well, think about it, should the authorization server authorize the scope just because the client asked for it? Thankfully you can set policy for this on the authorization server or let the resource owner him/herself decide. If the scope differs from what client requested, then server must issue a scope response with the actual scope authorized.

You must make an implementation decision to create a default scope and how you want to handle exceptions when clients make a request for a token but does not specify a scope.

Google OAuth2 JSON output - Endpoints, Client Info, and Consent screen

{"web":{"auth_uri":"https://accounts.google.com/o/oauth2/auth","client_secret":"ATX1LGjJCD-acURsf","token_uri":"https://accounts.google.com/o/oauth2/token","client_email":”00000000000@developer.gserviceaccount.com","client_x509_cert_url":"https://www.googleapis.com/robot/v1/metadata/x509/00000000000@developer.gserviceaccount.com","client_id":”00000000000.apps.googleusercontent.com","auth_provider_x509_cert_url":"https://www.googleapis.com/oauth2/v1/certs"}}

Google OAuth 2.0 Client Example

Now, let’s chat about authorization grant typesA grant is a credential based on four possible types:

Authorization Code Grant – Obtained through the intermediary between client and resource owner. Client directs resource owner to authorization server and is directed back to client with authorization code. Authorization server authenticates resource owner before directing back with grant. Client never knows about resource owner’s credentials. Primarily used for web based applications.Implicit Grant – Simplified authorization code primarily for java script clients. The client is issued an access token directly without authentication. Not Recommended if security is a major concern.Resource owner password credentials – Resource owner’s username/password can be used to obtain an access token. Recommended when there is trust between resource owner and client. Credentials are replaced by an access token by the client.Client Credentials – Can be used as authorization grant in it of itself. Common in cases where resource owner is also the client. Also may be used for a previous authorization arrangement from authorization server to client.Custom Grant – You may extend with a type of your own

Authorization Grants

Authorization Code Grant Flow

Authorization RequestConstructs the request URI and instructs the resource owner’s user-agent to redirect to the authorization server. The constructed URI defines:

response type – required, this must be set to “code” for this grant type. The authorization server returns an authorization code for requesting an access token.client_id – required, this is the id registered with the authorization server as part of the registration process. Look at slide 15, for the Google example.redirect_uri – although optional, you may want to always include this for best practice and to not make any assumptions.scope – although optional, it is a good idea to restrict scope to just the items you are requesting authorization for (i.e. user’s profile attributes on LinkedIn)state – highly recommended to guard against cross site request forgery

Example with required parameters only:GET /authorize?response_type=code&client_id=s6BhdRkqt3&state=xyz &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb HTTP/1.1 Host: server.example.com

Authorization ResponseIf the resource owner authenticates successfully and authorizes access and associated scope, the authorization server sends a response to client via the resource owner’s user-agent. The URI defines the following:

code – required, this is the authorization code generated by server. This is a short lived code and usually expires within 10 minutes. The client must not use the code more than once.state – highly recommended to guard against cross site request forgery and required if the request contained the state parameter.Once client receives this code, it may then proceed to make an access token request from the token endpoint.

Example without state:

HTTP/1.1 302 Found Location: https://client.example.com/cb code=SplxlOBeZQQYbYS6WxSbIA &state=xyz

For error responses, review section 4.1.2.1 of RFC 6749.

Access Token RequestAfter getting a valid authorization grant, client makes HTTP request to token endpoint including the following in the request body:

grant_type – required, this must be set to “password”, You may also use “client_credentials” if your client was issued credentials and can be identified by authorization server.username – required, this is the resource owner’s user name.Password - required, this is the resource owner’s password.scope – although optional, it is a good idea to restrict scope to just the items you are requesting authorization for (i.e. user’s profile attributes on LinkedIn)If client type is confidential and has been issued credentials (e.g. password or public/private key pair) or there is another authentication scheme in use, authorization server must support this scheme before proceeding and request body will look different. See parameters in Google example in slide 15.

Example of access token request with the resource owner’s credentials:

POST /token HTTP/1.1 Host: server.example.com Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW Content-Type: application/x-www-form-urlencoded grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb

Access Token ResponseIf the access token request is valid and authorized, the server issues an access token and an optional refresh token. Once client receives this token, it may proceed to make requests for the protected resources.

An example response below:

HTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8 Cache-Control: no-store Pragma: no-cache { "access_token":"2YotnFZFEjr1zCsicMWpAA", "token_type":"example", "expires_in":3600, "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA", "example_parameter":"example_value" } Example without state:

For error responses, review section 5.2 of RFC 6749.

Implicit Grant Flow

Authorization RequestClient constructs the request URI and instructs the resource owner’s user-agent to redirect to the authorization server. URI defines:

response type – required, this must be set to “token”client_id – required, this is the id registered with the authorization server as part of the registration process.redirect_uri – although optional, you may want to always include this for best practice and to not make any assumptions or have the authorization server define it for you.scope – although optional, it is a good idea to restrict scope to just the items you are requesting authorization for (i.e. user’s profile attributes on LinkedIn)state – highly recommended to guard against cross site request forgery

Example with required parameters only:

GET /authorize?response_type=token&client_id=s6BhdRkqt3&state=xyz &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom %2Fcb HTTP/1.1 Host: server.example.com

Access Token ResponseIf the resource owner grants the access request, the authorization server issues an access token and delivers it to the client by adding the following parameters to the fragment component of the redirection URI. An example response below:

access_token – required, this is the access token issued by authorization servertoken_type – the type of token issued (e.g., Bearer, MAC). See RFC 6750 and OAuth-HTTP-MAC specifications.Expires_in – recommended, this is the lifetime of the token in seconds.scope – optional, only if the scope is identical to the scope provided as part of the client’s request, otherwise it is a required parameter.state – required, if it was originally in the client's request.

There is no refresh token issued as this is and implicit grant type and it calls for an access token to be delivered as a response.

Example:

HTTP/1.1 302 Found Location: http://example.com/cb#access_token=2YotnFZFEjr1zCsicMWpAA &state=xyz&token_type=example&expires_in=3600

For error responses, review section 4.2.2.1 of RFC 6749.

Not Exactly, OAuth 2.0 alone will yield multiple implementation variations, refer to section 1.8 of RFC 6749 which states that the framework is “likely to produce a wide range of non-interoperable implementations”.

The Web vs. Enterprise divide. Ever changing systems and access flows vs. stagnant enterprise systems favoring only one protocol (SAML). In addition, the lack of provider discovery and dynamic client registration make it difficult to scale.

The Enterprise calls for extensibility and requires solutions for complex scenarios.

Enter Connect .. Stay Tuned for the OpenID Connect overview deck.

Sounds good so far right?

Where does OpenID Connect Come In? Interoperability

For additional discussion, contact the team @ GoodDogLabs. info@gooddoglabs.com