Authorize requests using OAuth 1.0a

Was this helpful?

APIs are relatively easy to develop and expose, but can be a significant challenge to secure and to manage access to over time. Apigee's OAuth 1.0a offering is highly integrated, easy to deploy, and inexpensive to get up and running, and it has a primary focus of providing support for apps and API developers.

OAuth 1.0a defines a standard protocol that enables applications to access protected resources from a web service via an API, without requiring users to disclose their passwords. To access the resources, the user must obtain an access token from the resource owner. Rather than relying on a single password as the master key for every app that accesses an API, OAuth uses this token to provide “delegated authentication” between web apps. The resource owner can issue access tokens with restricted scope and limited lifetime, and revoke them independently.

Apigee OAuth 1.0a is also designed to deliver the same service to Apigee customers through policies and related resources. When you configure OAuth for your API, the system automatically verifies access tokens for all incoming messages. If a message contains an invalid access token, the system throws an authentication failed error.

Back to top

Configuring an OAuth 1.0a policy

The OAuth 1.0a policy enables the user to specify which API calls to secure with OAuth 1.0a. The OAuth policy exposes configuration variables that enable the user to configure the behavior of the policy. Apigee supports OAuth policies for generating request tokens, generating access tokens, and verifying access tokens based on the OAuth 1.0a specification.

Back to top

Generating a request token

A request token is used by the consumer to obtain authorization from the user, and exchanged for an access token. A request token is generated from a valid key. Here are examples of the simple and comprehensive forms for generating request tokens.

Simple form

<OAuthV1 name="{policy_name}">
     <Operation>GenerateRequestToken</Operation>
</OAuthV1>

Comprehensive form

<OAuthV1 name="{policy_name}">
     <OAuthConfig>{config_name}</OAuthConfig>
     <Operation>GenerateRequestToken</Operation>
     <GenerateResponse enabled="true">
           <Format>FORM_PARAM or XML</Format>
     </GenerateResponse>
     <GenerateErrorResponse enabled="true">
           <Format>formparam or xml</Format>
           <Realm>http://oauth.apigee.com/oauth/1/</Realm>
     </GenerateErrorResponse>
</OAuthV1>

The policy enforces the following OAuth semantics:

  • The consumer key is valid.
  • The signature is valid.

A successful request returns the following responses:

  • Generates a request token and its attributes in the flow oauth_token, oauth_token_secret, oauth_callback_confirmed, oauth_response
  • Also makes a consumer token and its attributes available in the flow oauth_consumer_key, oauth_consumer_secret

On failure, a request returns the appropriate response status code with an error message.

Back to top

Generating an access token

An access token is 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. An access token is created with a valid key, request token, and verifier combination. Here are examples of the simple and comprehensive forms for generating access tokens.

Simple form

<OAuthV1 name="{policy_name}">
     <Operation>GenerateAccessToken</Operation>
</OAuthV1>

Comprehensive form

<OAuthV1 name="{policy_name}">
     <OAuthConfig>{config_name}</OAuthConfig>
     <Operation>GenerateAccessToken</Operation>
     <GenerateResponse enabled="true">
           <Format>formparam or xml</Format>
     </GenerateResponse>
     <GenerateErrorResponse enabled="true">
           <Format>FORM_PARAM or XML</Format>
           <Realm>http://oauth.apigee.com/oauth/1/</Realm>
     <GenerateErrorResponse>
</OAuthV1>

The policy enforces the following OAuth semantics:

  • The consumer key is valid.
  • The request token is valid.
  • The verifier is valid.
  • The signature is valid.

A successful request returns the following responses:

  • Generates an access token and its attributes in the flow oauth_token, oauth_token_secret, oauth_response
  • Also makes a consumer token and its attributes available in the flow oauth_consumer_key, oauth_consumer_secret

On failure, a request returns the appropriate response status code with an error message.

Back to top

Verifying an access token

Here are examples of the simple and comprehensive forms for verifying access tokens.

Simple form

<OAuthV1 name="{policy_name}">
     <Operation>VerifyAccessToken</Operation>
</OAuthV1>

Comprehensive form

<OAuthV1 name="{policy_name}">
     <OAuthConfig>{config_name}</OAuthConfig>
     <Operation>VerifyAccessToken</Operation>
     <GenerateErrorResponse enabled="true">
           <Format>FORM_PARAM or XML</Format>
           <Realm>http://oauth.apigee.com/oauth/1/</Realm>
     <GenerateErrorResponse>
</OAuthV1>

The policy enforces the following OAuth semantics:

  • The consumer key is valid.
  • The access token is valid.
  • The signature is valid.

A successful validation returns the following responses:

  • Makes an access token and its attributes available in the flow oauth_token, oauth_token_secret, oauth_response
  • Also makes a consumer token and its attributes available in the flow oauth_consumer_key, oauth_consumer_secret

If the request fails verification, the server responds with the appropriate response status code with an error message.

Back to top

Policy schema

Each policy must conform to a policy schema. All policy constructs such as elements and attributes mentioned above are defined in a schema. To download the schema, click here.

Back to top