PDF

Browser-Based Authentication

Last updated on October 11, 2019

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:

1. The Consumer (your application) requests and obtains an unauthorized request token
2. Authorize the user
3. Request an access token
4. Access protected resources with the access token

1. Requesting and Obtaining an Unauthorized Request Token

The client application (consumer) 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).

The sub-steps are:

1.1: Client application sends a POST request to https://sso.openx.com/api/index/initiate including the parameters listed below.
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.

1.1 Client application sends a POST request for a request token

The first step requests a request token using the following 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). Note: This parameter cannot contain a `/` even if it is encoded because the OpenX SSO cannot handle a `/` . If so, an `Invalid Request: Missing nonce` error occurs for the `https://sso.openx.com/api/index/initiate` step.
`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. This parameter supports up to 512 characters. For programmatic authentication, use oob (out of band).

1.2 Service Provider 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.

2. Authorizing 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.

The sub-steps are:

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).
2.2: User grants access to the client application by entering a valid username and password. The OpenX authorization server generates an authorized request token.
2.3: 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.

2.1 Consumer directs the user to service provider

The Consumer (your app) redirects the User to the Service Provider by constructing an HTTP GET request to the Service Provider’s (OpenX) User Authorization URL with the following 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.

2.2 Service provider obtains the user’s credentials

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

2.3 Service provider redirects the user back to the consumer site

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. 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:

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

3. Requesting 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:

3.1: Consumer (your application) requests an access token
3.2: The Service Provider (OpenX) grants an access token

3.1 Consumer 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:

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 is re-directed. This parameter supports up to 512 characters. 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

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:

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

4. Accessing Protected Resources with the Access Token

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