You are here: Developers > OpenX Platform API > Authentication reference > Browser-based authentication

Browser-Based Authentication

Use Case: You would use browser-based authentication if you are providing an interactive web-based login form for users other than yourself.

Browser-based SSO logins redirect the User back to their application and pass oauth_token and oauth_verifier onto the end of the specified callbackUrl.

Authenticating a User using OAuth involves the following steps:

  • Step 1 - The Consumer (your application) requests and obtains an unauthorized request token

  • Step 2 - Authorize the User

  • Step 3 - Request an access token

  • Step 4 - Use the access token to access protected resources

These steps are described in detail below.

Step 1 - The Consumer (your application) requests and obtains an unauthorized request token

The client application requests and obtains a request token from the OAuth server (https://sso.openx.com/api/index/initiate). The request command also passes in the value of the callbackUrl parameter (the URL to which the OAuth server will redirect the User upon successful authentication).

Sub-step Overview

  • Sub-step 1.1: The client application sends a POST request to https://sso.openx.com/api/index/initiate including the parameters listed below.

  • Sub-step 1.2: When OpenX receives the request, it verifies the request using its copy of the Consumer secret and returns a response to the client application, including the request token

Each sub-step is explained below.

Sub-step 1.1 The client application sends a POST request for a request token

The first step requests a request token using the parameters listed below.

Request parameters

Parameter Description
oauth_realm The realm value is a string, generally assigned by the origin server. The realm parameter allows the protected resources on a server to be partitioned. For example, oauth realm="http://server.example.com/".
oauth_consumer_key The Consumer Key, supplied to you by OpenX.
oauth_signature_method The signature method the Consumer used to sign the request.
oauth_signature The signature is created using the signature process which encodes the Consumer Secret and Token Secret into a verifiable value which is included with the request. For the first request (for the request token), no Token Secret yet exists. So, the signature creation process uses the Consumer Secret and an empty Token Secret.
oauth_timestamp The timestamp is expressed in the number of seconds since January 1, 1970 00:00:00 GMT. The timestamp value MUST be a positive integer and MUST be equal or greater than the timestamp used in previous requests.
oauth_nonce The Consumer must generate a Nonce value that is unique for all requests with the timestamp. A nonce is a random string, uniquely generated for each request. The nonce allows the Service Provider to verify that a request has never been made before and helps prevent replay attacks when requests are made over a non-secure channel (such as HTTP).
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 For browser-based authentication, use this parameter to specify to which URL the User will be re-directed. For programmatic authentication, use oob (out of band).

Sub-step 1.2 Service Provider (OpenX) returns an unauthorized request token

The result of step one provides your client application (the Consumer) with an unauthorized request token and oauth_token_secret. The next step allows your User to authorize the request token. To do so, the client application redirects the User to the authorization server (OpenX) login page.

Step 2 - Authorize the User

The User can now authenticate to SSO using the Authorize URL (https://sso.openx.com/login/login), passing in the request token. If successful, the SSO server redirects the User to the callbackUrl (with the oauth_token and oauth_verifier query string parameters appended).

Sub-step Overview

  • Sub-step 2.1: For browser-based authentication, the client application (Consumer) should redirect the User to a login page using a POST request using the url: https://sso.openx.com/login/login. The POST request also passes in the unauthorized request token (oauth_token).

  • Sub-step 2.2: The User grants access to the client application by entering a valid username and password. The OpenX authorization server generates an authorized request token.

  • Sub-step 2.3: The Service Provider redirects the User to the URL specified by the callback URL (callbackUrl). The response includes both the oath_token and the oath_verifier.

Each sub-step is explained below.

Sub-step 2.1 Consumer directs the User to Service Provider (OpenX)

The Consumer (your app) redirects the User to the Service Provider by constructing an HTTP GET request to the Service Provider's User Authorization URL with the following parameters:

Parameters

Parameter Description
oauth_token The unauthorized request token obtained in the previous step.
oauth_callback The Consumer should specify a URL the Service Provider will use to redirect the User back to the Consumer when Obtaining User Authorization is complete.

Sub-step 2.2 The Service Provider obtains the User's user name and password

The Service Provider verifies the User's identity by obtaining the User's username and password.

Sub-step 2.3 The Service Provider redirects the User back to the Consumer siteAn OpenX component that represents top-level domains or sub-domains and is used to organize ad units. Sites enable you to target and report on inventory performance.

After the User authenticates with the Service Provider and grants permission for Consumer access, the Service Provider notifies the Consumer that the Request Token has been authorized by doing the following: The Service Provider constructs an HTTP GET request URL using the provided oauth_callback, and redirects the User's web browser back to that URL with the following parameters:

Parameters

Parameter Description
oauth_token The Request Token the User authorized or denied.
oauth_verifier The verification code.

Step 3 - Request an access token

After the User has been authenticated in Step 2, in Step 3, the client application exchanges the authorized request token for an access token. The client application makes a POST request to https://sso.openx.com/api/index/token while passing the required parameters including oath_token and oath_verifier. The OpenX authorization server verifies the parameters and returns the access token in the response.

The Consumer exchanges the (temporary) Request Token for a (permanent) Access Token capable of accessing the Protected Resources. Obtaining an Access Token includes the following sub-steps:

Sub-step Overview

  • Sub-step 3.1: Consumer (your application) requests an access token

  • Sub-step 3.2: The Service Provider (OpenX) grants an access token

Each step is explained below.

3.1. The Consumer (Your application) requests an access token

The Request Token and Token Secret are 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, an HTTP POST is recommended. The request MUST be signed per Signing Requests, and contains the following parameters:

Request parameters

Parameter Description
oauth_consumer_key The Consumer Key, supplied to you by OpenX.
oauth_token The Request Token obtained previously.
oauth_signature_method The signature method the Consumer used to sign the request.
oauth_signature The signature is created using the signature process which encodes the Consumer Secret and Token Secret into a verifiable value which is included with the request.
oauth_timestamp The timestamp. See previous description.
oauth_nonce The Consumer must generate a Nonce value that is unique for all requests with the timestamp. See previous description.
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 For browser-based authentication, use this parameter to specify to which URL the User will be re-directed. For programmatic authentication, use oob (out of band).

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.

3.2. Service Provider Grants an Access Token (Response)

The Service Provider generates an Access Token and Token Secret and returns them in the HTTP response body. Your application must store the Access Token and Token Secret and use them when signing Protected Resources requests. The response contains the following parameters:

Parameters

Parameter Description
oauth_token The Access Token.
oauth_token_secret The Token Secret.

Step 4 - Use the access token to access protected resources

The client application uses the access token to perform OpenX API operations.

Feedback form