oauth tutorial - OAuth 2.0 Tutorial - oauth2 tutorial - oauth authentication

• Service Provider:
• A web application that allows access via OAuth.
• User:
• An individual who has an account with the Service Provider.
• Consumer:
• A website or application that uses OAuth to access the Service Provider on behalf of the User.
• Protected Resource(s):
• Data controlled by the Service Provider, which the Consumer can access through authentication.
• Consumer Developer:
• An individual or organization that implements a Consumer.
• Consumer Key:
• A value used by the Consumer to identify itself to the Service Provider.
• Consumer Secret:
• A secret used by the Consumer to establish ownership of the Consumer Key.
• Request Token:
• A value used by the Consumer to obtain authorization from the User, and exchanged for an Access Token.
• Access Token:
• A value used by the Consumer to gain access to the Protected Resources on behalf of the User, instead of using the User’s Service Provider credentials.
• Token Secret:
• A secret used by the Consumer to establish ownership of a given Token.
• OAuth Protocol Parameters:
• Parameters with names beginning with oauth_.

Oauth Documentation and Registration

• OAuth includes a Consumer Key and matching Consumer Secret that together authenticate the Consumer (as opposed to the User) to the Service Provider.
• Consumer-specific identification allows the Service Provider to vary access levels to Consumers (such as un-throttled access to resources).
• Service Providers SHOULD NOT rely on the Consumer Secret as a method to verify the Consumer identity, unless the Consumer Secret is known to be inaccessible to anyone other than the Consumer and the Service Provider.
• The Consumer Secret MAY be an empty string (for example when no Consumer verification is needed, or when verification is achieved through other means such as RSA).

Request URLs

OAuth defines three request URLs:

• Request Token URL:
• The URL used to obtain an unauthorized Request Token
• User Authorization URL:
• The URL used to obtain User authorization for Consumer access
• Access Token URL:
• The URL used to exchange the User-authorized Request Token for an Access Token
• The three URLs MUST include scheme, authority, and path, and MAY include query and fragment. The request URL query MUST NOT contain any OAuth Protocol Parameters.
• For example:
http://sp.example.com/authorize

Service Providers

• The Service Provider’s responsibility is to enable Consumer Developers to establish a Consumer Key and Consumer Secret. The process and requirements for provisioning these are entirely up to the Service Providers.
• The Service Provider’s documentation includes:
• The URLs the Consumer will use when making OAuth requests, and the HTTP methods (i.e. GET, POST, etc.) used in the Request Token URL and Access Token URL.
• Signature methods supported by the Service Provider.
• Any additional request parameters that the Service Provider requires in order to obtain a Token. Service Provider specific parameters MUST NOT begin with oauth_.

Consumers

• The Consumer Developer MUST establish a Consumer Key and a Consumer Secret with the Service Provider. The Consumer Developer MAY also be required to provide additional information to the Service Provider upon registration.

Parameters

• OAuth Protocol Parameter names and values are case sensitive. Each OAuth Protocol Parameters MUST NOT appear more than once per request, and are REQUIRED unless otherwise noted.

Parameter Encoding

• All parameter names and values are escaped using the [RFC3986] percent-encoding (%xx) mechanism. Characters not in the unreserved character set ([RFC3986]) MUST be encoded.
• Characters in the unreserved character set MUST NOT be encoded. Hexadecimal characters in encodings MUST be upper case.
• Text names and values MUST be encoded as UTF-8 octets before percent-encoding them per [RFC3629].

unreserved = ALPHA, DIGIT, '-', '.', '_', '~'

Consumer Request Parameters

• OAuth Protocol Parameters are sent from the Consumer to the Service Provider in one of three methods, in order of decreasing preference:
• In the HTTP Authorization header as defined in OAuth HTTP Authorization Scheme.
• As the HTTP POST request body with a content-type of application/x-www-form-urlencoded. Added to the URLs in the query part.
• In addition to these defined methods, future extensions may describe alternate methods for sending the OAuth Protocol Parameters.
• The methods for sending other request parameters are left undefined, but SHOULD NOT use the OAuth HTTP Authorization Scheme header.

Service Provider Response Parameters

• Response parameters are sent by the Service Provider to return Tokens and other information to the Consumer in the HTTP response body.
• The parameter names and values are first encoded as per Parameter Encoding, and concatenated with the ‘&’ character (ASCII code 38) as defined in [RFC3986]. For example:

oauth_token=ab3cd9j4ks73hf7g&oauth_token_secret=xyz4992k83j47x0b

OAuth HTTP Authorization Scheme

• This section defines an [RFC2617] extension to support OAuth. It uses the standard HTTP Authorization and WWW-Authenticate headers to pass OAuth Protocol Parameters.
• It is RECOMMENDED that Service Providers accept the HTTP Authorization header. Consumers SHOULD be able to send OAuth Protocol Parameters in the OAuth Authorization header.
• The extension auth-scheme (as defined by [RFC2617]) is OAuth and is case-insensitive.

Authorization Header

• The OAuth Protocol Parameters are sent in the Authorization header the following way:
• Parameter names and values are encoded per Parameter Encoding. For each parameter, the name is immediately followed by an ‘=’ character (ASCII code 61), a ‘”’ character (ASCII code 34), the parameter value (MAY be empty), and another ‘”’ character (ASCII code 34).
• Parameters are separated by a comma character (ASCII code 44) and OPTIONAL linear whitespace per [RFC2617]. The OPTIONAL realm parameter is added and interpreted per [RFC2617], section 1.2.
• For example:

Authorization: OAuth realm="http://sp.example.com/",
                oauth_consumer_key="0685bd9184jfhq22",
                oauth_token="ad180jjd733klru7",
                oauth_signature_method="HMAC-SHA1",
                oauth_signature="wOJIO9A2W5mFwDgiDvZbTSMK%2FPY%3D",
                oauth_timestamp="137131200",
                oauth_nonce="4572616e48616d6d65724c61686176",
                oauth_version="1.0"

WWW-Authenticate Header

• Service Providers MAY indicate their support for the extension by returning the OAuth HTTP WWW-Authenticate header upon Consumer requests for Protected Resources. As per [RFC2617] such a response MAY include additional HTTP WWW-Authenticate headers:
• For example:
WWW-Authenticate: OAuth realm="http://sp.example.com/"
• Authenticating with OAuth
• OAuth authentication is the process in which Users grant access to their Protected Resources without sharing their credentials with the Consumer.
• OAuth uses Tokens generated by the Service Provider instead of the User's credentials in Protected Resources requests. The process uses two Token types:

Request Token:

• Used by the Consumer to ask the User to authorize access to the Protected Resources. The User-authorized Request Token is exchanged for an Access Token, MUST only be used once, and MUST NOT be used for any other purpose. It is RECOMMENDED that Request Tokens have a limited lifetime.

Access Token:

• Used by the Consumer to access the Protected Resources on behalf of the User. Access Tokens MAY limit access to certain Protected Resources, and MAY have a limited lifetime.
• Service Providers SHOULD allow Users to revoke Access Tokens. Only the Access Token SHALL be used to access the Protect Resources.
• OAuth Authentication is done in three steps:
• The Consumer obtains an unauthorized Request Token.
• The User authorizes the Request Token.
• The Consumer exchanges the Request Token for an Access Token.
• Obtaining an Unauthorized Request Token
• The Consumer obtains an unauthorized Request Token by asking the Service Provider to issue a Token. The Request Token's sole purpose is to receive User approval and can only be used to obtain an Access Token. The Request Token process goes as follows:
• Consumer Obtains a Request Token
• To obtain a Request Token, the Consumer sends an HTTP request to the Service Provider's Request Token URL. The Service Provider documentation specifies the HTTP method for this request, and HTTP POST is RECOMMENDED. The request MUST be signed and contains the following parameters:
• oauth_consumer_key:
• The Consumer Key.
• oauth_signature_method:
• The signature method the Consumer used to sign the request.
• oauth_signature:
• The signature as defined in Signing Requests.
• oauth_timestamp:
• As defined in Nonce and Timestamp.
• oauth_nonce:
• As defined in Nonce and Timestamp.
• oauth_version:
• OPTIONAL. If present, value MUST be 1.0 . Service Providers MUST assume the protocol version to be 1.0 if this parameter is not present. Service Providers' response to non-1.0 value is left undefined.
• oauth_callback:
• An absolute URL to which the Service Provider will redirect the User back when the Obtaining User Authorization step is completed. If the Consumer is unable to receive callbacks or a callback URL has been established via other means, the parameter value MUST be set to oob (case sensitive), to indicate an out-of-band configuration.
• Additional parameters:
• Any additional parameters, as defined by the Service Provider.

Obtaining an Unauthorized Request Token

• The Consumer obtains an unauthorized Request Token by asking the Service Provider to issue a Token. The Request Token's sole purpose is to receive User approval and can only be used to obtain an Access Token. The Request Token process goes as follows:

Consumer Obtains a Request Token

• To obtain a Request Token, the Consumer sends an HTTP request to the Service Provider's Request Token URL. The Service Provider documentation specifies the HTTP method for this request, and HTTP POST is RECOMMENDED. The request MUST be signed and contains the following parameters:
• oauth_consumer_key:
• The Consumer Key.
• oauth_signature_method:
• The signature method the Consumer used to sign the request.
• oauth_signature:
• The signature as defined in Signing Requests.
• oauth_timestamp:
• As defined in Nonce and Timestamp.
• oauth_nonce:
• As defined in Nonce and Timestamp.
• oauth_version:
• OPTIONAL. If present, value MUST be 1.0 . Service Providers MUST assume the protocol version to be 1.0 if this parameter is not present. Service Providers' response to non-1.0 value is left undefined.
• oauth_callback:
• An absolute URL to which the Service Provider will redirect the User back when the Obtaining User Authorization step is completed. If the Consumer is unable to receive callbacks or a callback URL has been established via other means, the parameter value MUST be set to oob (case sensitive), to indicate an out-of-band configuration.
• Additional parameters:
• Any additional parameters, as defined by the Service Provider.
• Service Provider Issues an Unauthorized Request Token
• The Service Provider verifies the signature and Consumer Key. If successful, it generates a Request Token and Token Secret and returns them to the Consumer in the HTTP response body as defined in Service Provider Response Parameters.
• The Service Provider MUST ensure the Request Token cannot be exchanged for an Access Token until the User successfully grants access in Obtaining User Authorization.
• The response contains the following parameters:
• oauth_token:
• The Request Token.
• oauth_token_secret:
• The Token Secret.
• oauth_callback_confirmed:
• MUST be present and set to true. The Consumer MAY use this to confirm that the Service Provider received the callback value.
• Additional parameters:
• Any additional parameters, as defined by the Service Provider.
• If the request fails verification or is rejected for other reasons, the Service Provider SHOULD respond with the appropriate response code as defined in HTTP Response Codes. The Service Provider MAY include some further details about why the request was rejected in the HTTP response body as defined in Service Provider Response Parameters.
• Obtaining User Authorization
• The Consumer cannot use the Request Token until it has been authorized by the User. Obtaining User authorization includes the following steps:

Consumer Directs the User to the Service Provider

• In order for the Consumer to be able to exchange the Request Token for an Access Token, the Consumer MUST obtain approval from the User by directing the User to the Service Provider. The Consumer constructs an HTTP GET request to the Service Provider's User Authorization URL with the following parameter:

oauth_token:

• OPTIONAL. The Request Token obtained in the previous step. The Service Provider MAY declare this parameter as REQUIRED, or accept requests to the User Authorization URL without it, in which case it will prompt the User to enter it manually. Additional parameters: Any additional parameters, as defined by the Service Provider.
• Once the request URL has been constructed the Consumer redirects the User to the URL via the User's web browser. If the Consumer is incapable of automatic HTTP redirection, the Consumer SHALL notify the User how to manually go to the constructed request URL.

Service Provider Authenticates the User and Obtains Consent

• The Service Provider verifies the User's identity and asks for consent as detailed. OAuth does not specify how the Service Provider authenticates the User. However, it does define a set of REQUIRED steps:
• The Service Provider MUST first verify the User's identity before asking for consent. It MAY prompt the User to sign in if the User has not already done so.
• The Service Provider presents to the User information about the Consumer requesting access (as registered by the Consumer Developer). The information includes the duration of the access and the Protected Resources provided. The information MAY include other details specific to the Service Provider.
• The User MUST grant or deny permission for the Service Provider to give the Consumer access to the Protected Resources on behalf of the User. If the User denies the Consumer access, the Service Provider MUST NOT allow access to the Protected Resources.
• When displaying any identifying information about the Consumer to the User based on the Consumer Key, the Service Provider MUST inform the User if it is unable to assure the Consumer's true identity. The method in which the Service Provider informs the User and the quality of the identity assurance is beyond the scope of this specification.

Service Provider Directs the User Back to the Consumer

• After the User authenticates with the Service Provider and grants permission for Consumer access, the Consumer MUST be notified that the Request Token has been authorized and ready to be exchanged for an Access Token. If the User denies access, the Consumer MAY be notified that the Request Token has been revoked.
• To make sure that the User granting access is the same User returning back to the Consumer to complete the process, the Service Provider MUST generate a verification code: an unguessable value passed to the Consumer via the User and REQUIRED to complete the process.
• If the Consumer provided a callback URL (using the oauth_callback parameter in Section 6.1.1 or by other means), the Service Provider uses it to constructs an HTTP request, and directs the User's web browser to that URL with the following parameters added:

• oauth_token:
• The Request Token the User authorized or denied.
• oauth_verifier:
• The verification code.
• The callback URL MAY include Consumer provided query parameters. The Service Provider MUST retain them unmodified and append the OAuth parameters to the existing query.
• If the Consumer did not provide a callback URL, the Service Provider SHOULD display the value of the verification code, and instruct the User to manually inform the Consumer that authorization is completed. If the Service Provider knows a Consumer to be running on a mobile device or set-top box, the Service Provider SHOULD ensure that the verifier value is suitable for manual entry.

Obtaining an Access Token

• The Consumer exchanges the Request Token for an Access Token capable of accessing the Protected Resources. Obtaining an Access Token includes the following steps:

Consumer Requests an Access Token

• The Request Token and Token Secret MUST be exchanged for an Access Token and Token Secret.
• To request an Access Token, the Consumer makes an HTTP request to the Service Provider's Access Token URL. The Service Provider documentation specifies the HTTP method for this request, and HTTP POST is RECOMMENDED. The request MUST be signed per Signing Requests, and contains the following parameters:

• oauth_consumer_key:
• The Consumer Key.
• oauth_token:
• The Request Token obtained previously.
• oauth_signature_method:
• The signature method the Consumer used to sign the request.
• oauth_signature:
• The signature as defined in Signing Requests.
• oauth_timestamp:
• As defined in Nonce and Timestamp.
• oauth_nonce:
• As defined in Nonce and Timestamp.
• oauth_version:
• OPTIONAL. If present, value MUST be 1.0 . Service Providers MUST assume the protocol version to be 1.0 if this parameter is not present. Service Providers' response to non-1.0 value is left undefined.
• oauth_verifier:
• The verification code received from the Service Provider in the Service Provider Directs the User Back to the Consumer step.
• No additional Service Provider specific parameters are allowed when requesting an Access Token to ensure all Token related information is present prior to seeking User approval.

Service Provider Grants an Access Token

• The Service Provider MUST ensure that:
• The request signature has been successfully verified.
• The Request Token has never been exchanged for an Access Token.
• The Request Token matches the Consumer Key.
• The verification code received from the Consumer has been successfully verified.
• If successful, the Service Provider generates an Access Token and Token Secret and returns them in the HTTP response body as defined in Service Provider Response Parameters. The Access Token and Token Secret are stored by the Consumer and used when signing Protected Resources requests. The response contains the following parameters:

• oauth_token:
• The Access Token.
• oauth_token_secret:
• The Token Secret.
• Additional parameters:
• Any additional parameters, as defined by the Service Provider.
• If the request fails verification or is rejected for other reasons, the Service Provider SHOULD respond with the appropriate response code as defined in HTTP Response Codes. The Service Provider MAY include some further details about why the request was rejected in the HTTP response body as defined in Service Provider Response Parameters.

Accessing Protected Resources

• After successfully receiving the Access Token and Token Secret, the Consumer is able to access the Protected Resources on behalf of the User. The request MUST be signed per Signing Requests, and contains the following parameters:
• oauth_consumer_key:
• The Consumer Key.
• oauth_token:
• The Access Token.
• oauth_signature_method:
• The signature method the Consumer used to sign the request.
• oauth_signature:
• The signature as defined in Signing Requests.
• oauth_timestamp:
• As defined in Nonce and Timestamp.
• oauth_nonce:
• As defined in Nonce and Timestamp.
• oauth_version:
• OPTIONAL. If present, value MUST be 1.0. Service Providers MUST assume the protocol version to be 1.0 if this parameter is not present. Service Providers' response to non-1.0 value is left undefined. Additional parameters: Any additional parameters, as defined by the Service Provider.