—Rate this article—
 

Part 1: Deploy OAuth token endpoint

This tutorial shows you how to use the Apigee Edge management UI to the secure your API by using OAuth access tokens.

About OAuth

OAuth is an authorization protocol that enables apps to access information on behalf of users without requiring users to divulge their username and password.

An access token is a string representing an authorization issued to the client. It is used in OAuth to provide limited access to protected resources. For this reason, OAuth access tokens are often compared to 'valet keys'.

The OAuth 2.0 specification defines different ways of creating access tokens for apps. The various mechanisms for distributing access tokens are referred to as grant types. The most basic grant type defined by OAuth 2.0 is client credentials. In this grant type, OAuth access tokens are generated in exchange for client credentials, which are consumer key-consumer secret pairs.

You configure the client credentials grant type by applying OAuth v2.0 policies to your API and adding conditional flows that dynamically enforce these policies. The policies protect your API in the following ways:

  • To obtain the access token, the app must first  supply valid customer credentials.
  • Whenever an app makes a call to your API, it must supply a valid access token.
  • Edge policies validate that the access token presented is valid for the API product, and only then grants access to the protected requested resources.

A conditional flow is a flow whose processing steps are based on a conditional statement, such as the content type specified in the HTTP request header is "text/xml". If the statement is true, the processing step specified in the flow is implemented — for example, a policy is enforced or the message is routed to a specified endpoint. If the conditional statement is false, the processing step is not implemented. In this way, you can add dynamic behavior to your API proxy.

Learn more

What you’ll do in this tutorial

This tutorial shows you how to configure OAuth 2.0 client credentials using the Apigee Edge management UI*. This tutorial implements what is sometime called "two legged" OAuth.

(* You can also do this by directly calling the Apigee management API, as described in OAuth.)

Prerequisites

This tutorial builds on previous tutorials and uses an API proxy for the Yahoo! Weather API as a basis of instruction. If you haven’t already done so, please review the tutorial Part 1: Create a secure API.

When you log in to Apigee Edge for the first time at https://enterprise.apigee.com, you will see the predefined resources used in this tutorial, including:

  • weatherapi - an API proxy that you use to access the Yahoo! Weather API.
  • oauth - an API proxy that you use to generate an access token from customer credentials.
  • Premium Weather API - an API product definition.
  • Nikolai Tesla - a developer.
  • Weather App - a developer app.

The oauth API proxy provides free, out-of-the-box OAuth token endpoints that support the client credentials grant type. Each organization (even a free trial org) on Apigee Edge is provisioned with the oauth access token token endpoint. You can begin using the token endpoint as soon as you create an account on Apigee Edge.

The default oauth API proxy exposes the following endpoint URLs:

https://{org-name}-{env}.apigee.net/oauth/client_credential/accesstoken
https://{org-name}-{env}.apigee.net/oauth/client_credential/refresh_accesstoken

Note: Refreshing access tokens is not supported with two-legged OAuth, so it is not used in this tutorial. However, the policy and conditional flow are described.

Publish these URLs to developers who need to obtain access tokens. App developers configure their apps to call the first endpoint, presenting their consumer key and secret pairs to obtain access tokens. Call the second endpoint to refresh an expired access token.

Step 1: Deploy the API proxies

This tutorial predefines the weatherapi and oauth proxies for you. However, you must deploy these API proxies.

  1. Login to https://enterprise.apigee.com.
  2. In the management UI, select the APIs tab.
  3. On the API Proxies page, select oauth.
  4. Select the Deployment button, and then select test from the dropdown menu. The API proxy will be deployed to the test environment.
  5. Select Deploy in the pop up window to deploy the API proxy.
  6. In the management UI, select the APIs tab.
  7. On the API Proxies page, select weatherapi.
  8. Select the Deployment button, and then select test from the dropdown menu. The API proxy will be deployed to the test environment.
  9. Select Deploy in the pop up window to deploy the API proxy.

Step 2: Examine the policies in the OAuth token endpoint

The oauth token endpoint defines two policies and two conditional flows that control the generation of access tokens. Examine these policies and flows before generating a token.

  1. In the management UI, select the APIs tab.
  2. On the API Proxies page, select oauth.
  3. Open the API Proxy Editor by clicking the Develop button in the details page for the oauth API proxy.

    Notice that two policies have been added to your API proxy’s request message flow:

    Policy Name Policy Type     Description
    GenerateAccessTokenClient Oauth v2.0 Generates an access token from a customer key and customer secret. The access token has a duration of one hour.
    RefreshAccessToken Oauth v2.0 Refreshes an expired access token (three-legged OAuth only and is not used in this tutorial).

    Also notice that two conditional flows have been added:

    Flow Name Description
    RefreshAccessToken The flow that implements the RefreshAccessToken policy (three-legged OAuth only and is not used in this tutorial).
    AccessTokenClientCredential The flow that implements the GenerateAccessTokenClient policy.

The GenerateAccessTokenClient Policy

The GenerateAccessTokenClient policy is a policy of type OAuth v2.0 that generates an access token from a customer key and customer secret. You can view the XML for the policy in the Code view area of the API Proxy Editor. The XML for the policy should look like this:

<OAuthV2 name="GenerateAccessTokenClient">
  <!-- This policy generates an OAuth 2.0 access token 
       using the client_credentials grant type -->
  <Operation>GenerateAccessToken</Operation>
  <!-- This is in millseconds, so expire in an hour -->
  <ExpiresIn>3600000</ExpiresIn>
  <SupportedGrantTypes>
    <!-- This part is very important: most real OAuth 2.0 apps will want to use other
         grant types. In this case it is important to NOT include the "client_credentials"
         type because it allows a client to get access to a token with 
         no user authentication -->
      <GrantType>client_credentials</GrantType>
  </SupportedGrantTypes>
  <GrantType>request.queryparam.grant_type</GrantType>
  <GenerateResponse/>
</OAuthV2>

Where:

Policy setting value Description
<Operation>GenerateAccessToken</Operation> The operation to be executed by the OAuth v2.0 policy. By specifying GenerateAccessToken, you configure the policy to generate access tokens for apps.
<ExpiresIn>3600000</ExpiresIn> Specifies the time in milliseconds for which access tokens are valid. In this case, the value specifies 3600000 milliseconds, which means a generated access token is valid for one hour.
<SupportedGrantTypes>
  <GrantType>client_credentials</GrantType>
</SupportedGrantTypes>
Defines the grant types that this token endpoint supports. A token endpoint can be configured to support more than one grant type. For a list of supported grant types, see Authorize requests using OAuth 2.0.
<GrantType>request.queryparam.grant_type
</GrantType>
Specifies the location in the request message where the app indicates the desired grant type. The location can be the HTTP header, a query parameter, or a form parameter. The value request.queryparam.grant_type specifies that the desired grant type is specified in a query parameter named grant_type.

The RefreshAccessToken Policy

The RefreshAccessToken policy is a policy of type OAuth v2.0 that refreshes an expired access token for three-legged OAuth and is not used in this tutorial.

The AccessTokenClientCredential flow

The AccessTokenClientCredential conditional flow enforces the GenerateAccessTokenClient policy when a POST request URI ends with /accesstoken.

The XML for the flow looks like this:

<Flow name="AccessTokenClientCredential">
    <Description/>
    <Request>
      <Step>
        <FaultRules/>
        <Name>GenerateAccessTokenClient</Name>
      </Step>
    </Request>
    <Response/>
    <Condition>(proxy.pathsuffix MatchesPath &quot;/accesstoken&quot;) 
       and (request.verb = &quot;POST&quot;)</Condition>
</Flow>

The condition proxy.pathsuffix MatchesPath &quot;/accesstoken&quot;) and (request.verb = &quot;POST&quot; specifies the following:

  • The variable: proxy.pathsuffix. Apigee Edge sets the proxy.pathsuffix variable with the fragment of a request URI that follows the URI base path.
  • The operator: MatchesPath
  • The value: &quot;/accesstoken&quot;) and (request.verb = &quot;POST&quot;

    Note: The value uses the HTML &quot; code for " (double quote character). You do not have to use the HTML code, but can insert " directly.

How it works at runtime
To request an access token, an app makes the following POST request:
http(s)://{org}-{env}.apigee.net/{base_path}/accesstoken?grant_type=client_credentials
where:
  • {org} is your organization.
  • {env} is the environment, such as test.
  • accesstoken is the fragment of the URI that follows the URI base path in these access token requests.
  • grant_type specifies the grant type of the access token.
When the value of proxy.pathsuffix matches /accesstoken for a POST request, the GenerateAccessTokenClient policy is applied. (Because the proxy.pathsuffix value for all requests to obtain an access token is /accesstoken, the GenerateAccessTokenClient policy is applied for all requests.)

The RefreshAccessToken flow

The RefreshAccesslToken flow enforces the RefreshAccessToken policy when a POST request URI ends with /refresh_accesstoken for three-legged OAuth and is not used in this tutorial.

Step 3: Where to next?

Now that you have deployed and examined the OAuth API proxy and policies, you can add OAuth support to an API proxy.

Continue on to Part 2: Apply OAuth policies to your API to add OAuth support to an API proxy.

Help or comments?

  • Something's not working: See Apigee Support
  • Something's wrong with the docs: Click Send Feedback in the lower right.
    (Incorrect? Unclear? Broken link? Typo?)