OAuth v1.0a policy

What

OAuth 1.0a defines a standard protocol that enables app users to authorize apps to consume APIs on their behalf, without requiring app users to disclose their passwords to the app in the process. Apigee Edge enables you to protect APIs in a way that ensures that an app uses has authorized the app to consume an API. Edge also provides policy-based functionality for configuring the endpoints that app developers can use to obtain access tokens.

Where

This policy can be attached in the following locations, but see the notes following the table for specific guidance.

Usage notes

Apigee Edge provides an OAuth v1.0a policy type that enables you to authorize apps with OAuth 1.0a. The OAuthV1 policy type is responsible for generating request tokens, generating access tokens, and verifying access tokens based on the OAuth 1.0a specification.

Once you have configured OAuth policies on your API, apps must obtain access tokens to consume them. To do so, the app must exchange a request token for an access token. 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 APIs and apps. The resource owner can issue access tokens with restricted scope and limited lifetime, and revoke them independently.

The name attribute for this policy is restricted to these characters: A-Z0-9._\-$ %. However, the Management UI enforces additional restrictions, such as automatically removing characters that are not alphanumeric.

Generating a request token

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

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

The <URL> element allows proper OAuthV1 signature calculation when running behind Elastic Load Balancers (ELBs). The ref attribute takes precedence when both the ref attribute and a text value are specified. If ref is not provided, or if the flow variable given in ref is NULL, then the text value will be considered for generating the signature. For example:

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

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.

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

The <URL> element allows proper OAuthV1 signature calculation when running behind Elastic Load Balancers (ELBs). The ref attribute takes precedence when both the ref attribute and a text value are specified. If ref is not provided, or if the flow variable given in ref is NULL, then the text value will be considered for generating the signature. For example:

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

Associating a token verification code with a request token

The following policy associates a token verification code with a request token. To receive an access token, both a verification code and a request token are required.

To use this policy, a verification code must be generated as a separate step outside of Apigee Edge. The verifier value must be a unique, random string.

The verification code fits into the basic OAuth flow as follows: After an app user's credentials are authenticated by a service provider, the service provider must inform the consumer app that the credentials were accepted, implying that the request token can be exchanged for an access token. This is usually done via a 302 redirect. Separately, the service provider must send a verification code to Apigee Edge, and Apigee Edge internally associates this verifier to the request token.

Later, when the app exchanges the request token for an access token, it must pass both the request token and the verifier code. Apigee Edge then checks that the verifier code is correct, ensuring that the user who authenticated and granted access to the service is the same user who is asking the app to retrieve an access token. For detailed information on this message flow, see the OAuth 1.0a specification.

Parameters

(Required) Specifies the request token with which to associate the verifier.

AppUserId

(Required) Specifies the ID of the application user.

VerifierCode

(Required) Specifies the verifier code. This code must be generated outside of Apigee as a separate step.

Attributes

(Optional) Allows you to attach arbitrary values to the access token. It is also possible to attach attributes to the request token. Any attributes that are attached to the request token get "promoted" to the access token at the time the app exchanges the request token for the access token. If the policy specifies custom attributes to associate to the access token that have the same name as custom attributes already associated to the request token, the values of the custom attributes specified here take precedence. See also "Customizing access tokens" later in this topic.

When this policy executes, the following flow variables are populated:

Request Token: oauthtoken.{policy_name}.oauth_token

Verifier Code: authtoken.{policy_name}.verifier_code

App User Id: oauthtoken.{policy_name}.app_user_id

Sample response

If GenerateReponse is enabled, then the verifier is returned in the response along with the other attributes. This is an example response when Format is set to XML.

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

The <URL> element allows proper OAuthV1 signature calculation when running behind Elastic Load Balancers (ELBs). The ref attribute takes precedence when both the ref attribute and a text value are specified. If ref is not provided, or if the flow variable given in ref is NULL, then the text value will be considered for generating the signature. For example: