Skip to end of metadata
Go to start of metadata
Possible outdated information

PLEASE NOTE: This page may be out of date and could contain inaccuracies. In future it may be significantly revised or removed altogether. Current product documentation for endpoints is available from: http://docs.forgerock.org/en/openam/11.0.0/reference/index/chap-endpoints.html#oauth-jsp-endpoints

All about OAuth

OAuth is a simple mechanism for a user to allow a consumer application to access a service provider using a secure token. This token, authorized by a user, grants access to private resources from the user's account on one service provider site to a second, consumer site. The key benefit of OAuth is that the users credentials are not known to the consumer website. The OpenAM implementation provides a mechanism to issue and validate OAuth tokens.

The early access version of the OpenAM OAuth Token Service (available as a new feature of OpenAM Release 9) supports the OAuth Core 1.0 Specifications including consumer site registration, Request Token requests, Request Token authorizations, and Access Token requests. The OpenAM OAuth implementation is designed to be deployed as a service provider site.

For more information on OAuth refer to the specification.

OAuth Token Flow

The first step in using OAuth is to register the consumer with the service provider. It is important to understand that OAuth should be transparent to the end user. The end user is just trying to make some of their personal data hosted on the service provider available on the consumer in a secure manner. The diagram below shows the user initiating the first stage of the OAuth flow.

  1. The user (using their browser) requests the service they want to access on the consumer.
  2. The consumer website contact the service provider requesting a request token. The service provider generates a request token (using the OpenAM OAuth implementation) and returns this to the consumer website.
  3. The consumer website redirects the user to the service provider website to authenticate (to the service provider) and to authorise access for the consumer website.

The next stage is vital for OAuth, but doesn't not actually have anything specifically to do with OAuth.

  1. The user authenticates to the service provider (in this case the user would be authenticating to OpenAM)
  2. The user authorises the consumer to access their personal data on the service provider. The service provider application could be using OpenAM entitlements to manage this authorisation functionality.
  3. The service provider redirects the user back to the consumer web site.
    The final stage of the OAuth flow is for the consumer web site to upgrade their request token to an access token and use said access token to retrieve the users private data from the service provider.

  1. The user follows the redirect back to the consumer web site from the service provider.
  2. The consumer web site contacts the service provide requesting the access token.
  3. The service provider checks the user has authorise the access (they have) and returns the access token.
  4. The consumer web site uses the access token in its communications with the service provider when requesting the users private data.

Using the OpenAM OAuth Token Service

OpenAM OAuth Endpoints

The OpenAM OAuth implementation has the following endpoints for allowing access to the implementation.

Endpoint

URL

Description

Consumer Registration

http://hostname:domainname/openam/oauth/index.jsp

Using a browser, consumer registrations can be created and deleted.

Request Token

http://hostname:domainname/openam/resources/1/oauth/get_request_token

A RESTful interface used by the consumer application to fetch a request token

Request Token Authorization
Console

http://hostname:domainname/openam/oauth/userconsole.jsp

Using a browser, the service provider redirects the client to this URL to ask
the user to authorise the request token.

Access Token

http://hostname:domainname/openam/resources/1/oauth/get_access_token

A RESTful interface used by the consumer application to fetch an access token

Registering Consumers

Before OpenAM can start issuing tokens there must exist a trust relationship between the consumer and service provider web sites. This trust relationship can be based on a simple username and password or on the more secure public key certificates. The registration page looks like this:

Fetching the Request Token

The consumer site must first fetch a Request Token from the Service Provider to get approval from a user to access resources from the user's service provider account. A registered consumer site can request a Request Token using a RESTful web service. The RESTful call must contain the following parameters:

Parameter Name

Description

oauth_consumer_key

The consumer key is the consumer site identifier generated when the consumer was originally registered with the OAuth service provider.

oauth_signature_method

The signature method used by the consumer site to sign the request. All Request Token requests must be signed by the consumer site and verified by the service provider. OAuth supported signature methods are HMAC-SHA1, RSA-SHA1, and PLAINTEXT.

oauth_signature

The generated signature generated using the method described above. Used by the service provider to validate the request.

oauth_timestamp

The timestamp of the request. Unless otherwise specified, the timestamp is expressed in the number of seconds since January 1, 1970 00:00:00 GMT. It must be a positive integer and equal or greater than the timestamp used in previous requests.

oauth_nonce

The nonce is a random string guaranteed unique for all requests generated by the consumer site with a particular timestamp.

oauth_version

This is an optional parameter that defines the OAuth specification version being used. If defined, the value must be 1.0

The response to the Request Token request will contain the following parameters:

Parameter Name

Description

oauth_token

The Request Token.

oauth_token_secret

The Token Secret used for verification by the consumer.

For more information on these parameters, see the OAuth Core 1.0 Specifications . The next stage is for the consumer web site to redirect the client to the service provider to authorise the token.

Request Token Authorisation

The client is sent to the service provider to authorise the request token. The OpenAM has basic starter page for authorisation, but most customers will want to customise the page. The basic page does the following:

  • Checks the user is authenticated to OpenAM, if not the user will be redirected to the OpenAM authentication interface. Once authenticated they will be redirected back to the authorisation page.
  • The user then gets to authorise the request. This will flag the request token allowing it to become an Access Token.

The request should use HTTP GET and should contain the following parameters:

Parameter Name

Description

oauth_token

The Request Token to be authorized

oauth_callback

This is the URL that the client will be redirected to on the consumer site after user authorization is complete.

Following a successful OAuth authorization, the OAuth Token Service redirects the user to the oauth_callback URL with the authorized Request Token as the value of oauth_token.

Fetching the Access Token

The consumer site must now fetch the Access Token from the Service Provider. A registered consumer site can request an Access Token using a RESTful web service. The RESTful call must contain the following parameters:

Parameter Name

Description

oauth_consumer_key

The consumer key is the consumer site identifier generated when the consumer was originally registered with the OAuth service provider.

oauth_token

This is the Request Token.

oauth_signature_method

The signature method used by the consumer site to sign the request. All Request Token requests must be signed by the consumer site and verified by the service provider. OAuth supported signature methods are HMAC-SHA1, RSA-SHA1, and PLAINTEXT.

oauth_signature

The generated signature generated using the method described above. Used by the service provider to validate the request.

oauth_timestamp

The timestamp of the request. Unless otherwise specified, the timestamp is expressed in the number of seconds since January 1, 1970 00:00:00 GMT. It must be a positive integer and equal or greater than the timestamp used in previous requests.

oauth_nonce

The nonce is a random string guaranteed unique for all requests generated by the consumer site with a particular timestamp.

oauth_version

This is an optional parameter that defines the OAuth specification version being used. If defined, the value must be 1.0

The response to the Access Token request should contain the following parameters:

Parameter Name

Description

oauth_token

The Access Token

oauth_token_secret

The token secret used by verification on the consumer

De-Register a Consumer

To de-register a consumer from the service provider is simple. Go to the registration page and enter the consumer registration key into the delete consumer field.The OpenAM OAuth Sample Application

Using OAuth Demo

There is a simple OAuth demo available for download with installation instructions.

Labels
  • None