As the authorization server, Apigee Edge needs to have appropriate OAuth endpoints set up so that clients can request authorization codes and access tokens. This topic explains how to set up these endpoints. For details on setting up endpoints and policies for specific grant types, see Configuring specific grant types below.

What is an OAuth endpoint?

An OAuth endpoint is a URL that is exposed by Apigee Edge in your organization. OAuth defines token endpoints, authorization endpoints, and refresh endpoints. Apps call these endpoints to get access tokens, to refresh access tokens, and, in some cases, to get authorization codes. Apigee Edge makes it easy to set up OAuth endpoints simply by configuring policies.

For example, this API call is requesting an access token from the /accesstoken endpoint on Apigee Edge. The path /accesstoken is the endpoint URI, and when a request is made to that endpoint, a GenerateAccessToken policy executes:

$ curl -i -H 'ContentType: x-www-form-urlencoded' -X POST 'https://docs-test.apigee.net/oauth/accesstoken' -d 'grant_type=client_credentials' -H 'Authorization: Basic c3FIOG9vSGV4VHo4QzAySVg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ'

After reading this topic, you'll have a good sense of how these OAuth endpoints and policies are set up. 

Default endpoints

The quickest way to see how endpoints are set up is to examine the default "oauth" proxy. This proxy is installed for you when you create a new Apigee Edge organization. It sets up OAuth endpoints that support the client credentials grant type. Let's take a look.

If for some reason you can't locate this proxy, you find a version that you can deploy on GitHub.

  1. Log in to your Apigee Edge account.
  2. Select APIs > API Proxies from the main menu.
  3. In the list of proxies, select the one called oauth. The overview page appears, as shown below.

The oauth proxy overview page

Select the Develop view.

The oauth proxy Develop view

You'll see in this view the policies and flows that are configured to support this OAuth grant type flow.

Policies

For OAuth 2.0 flows, use the OAuthV2 policy on endpoints. This policy can be configured to handle access token, refresh token, and authorization code endpoints. For the default oauth proxy, these two OAuthV2 policies are configured:

  • RefreshAccessToken: This OAuthV2 policy exchanges access tokens for refresh tokens.
  • GenerateAccessTokenClient: This OAuthV2 policy (a) validates consumer key/secret pairs and (b) generates access tokens.

Here's the XML for the GenerateAccessTokenClient policy. It specifies a GenerateAccessToken operation, expiration time, and grant type. In addition, it specifies that the grant type will be retrieved from a query parameter.

<OAuthV2 name="GenerateAccessTokenClient">
  <!-- This policy generates an OAuth 2.0 access token using the client_credentials grant type -->
  <Operation>GenerateAccessToken</Operation>
  <!-- This is in milliseconds, so expire in an hour -->
  <ExpiresIn>3600000</ExpiresIn>
    <GrantType>client_credentials</GrantType>
  </SupportedGrantTypes>
  <GrantType>request.queryparam.grant_type</GrantType>
  <GenerateResponse/>
</OAuthV2>

The settings for the OAuthV2 Policy type are documented in Authorize requests using OAuth 2.0.

Conditional flows

The oauth proxy has these two conditional flows for handling refresh tokens and access tokens:

  • RefreshAccessToken: This flow is entered when the request path matches /refresh_accesstoken. The RefreshAccessToken Policy is attached to this flow.
  • AccessTokenClientCredential: This flow is entered when the request path matches /accesstoken. The GenerateAccessTokenClient Policy is attached to this Flow.

Here's the XML of the RefreshAccessToken flow. Note that it is triggered when the proxy path matches /accesstoken.

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

For more information about conditional flows, see Flows.

Summary

You configure OAuth 2.0 endpoints in an API proxy that's deployed on Apigee Edge. The proxy performs as a service for returning OAuth tokens and codes. The proxy has conditional flows (endpoints) that handle OAuth 2.0 requests (for access tokens, refresh tokens, and in some scenarios authorization codes). The flows have OAuthV2 policies attached that perform tasks like validation, minting access tokens, and so on.

Best practice: Create your own OAuth proxy

The default oauth proxy is only supports the client credentials grant type, and is mainly provisioned to support examples. For your OAuth 2.0 implementation, it's a common practice to create your own OAuth endpoint proxy where you define your specific set of conditional flows and attach OAuthV2 policies.

The OAuth proxy that you create does not make any backend calls. Instead, the OAuth proxy acts as a standalone service. Once you have set up the conditional flows and attached the policies, app developers can call the URLs exposed by your API proxy to get access tokens, refresh access tokens, and, in the case of the authorization code grant type, authorization codes.

Configuring specific grant types

We provide implementation topics and samples for each of the OAuth 2.0 grant types. There, you'll find more detailed information on setting up proxies to support each implementation. Go to the OAuth home page for a complete list and links under "Implementing the grant types".

For a quick summary, here's a list of the grant types, the OAuthV2 operations (policies) associated with each, and the typical endpoints clients use to call them:

Authorization code grant type

This grant type uses these endpoints on Apigee Edge:

  • Login page redirect -- (required) OAuth requires that the use be directed to a login page for the protected resource server. This is often implemented on Edge with a RaiseFault or AssignMessage policy, and simply issues a redirect to the login page's URL. Typically attached to an endpoint called /authorize.
  • GenerateAuthorizationCode -- (required) Required to generate an auth code that he client app then uses to obtain an access token. Typically attached to an endpoint called /authorizationcode.
  • GenerateAccessToken -- (required) Generates and returns an access code to the client app. Typically attached to an endpoint called /token or /accesstoken.
  • RefreshAccessToken -- (optional, recommended) Generates an access token when presented with a valid refresh token. Typically attached to an endpoint called /refreshtoken.

Implicit grant type

This grant type uses these endpoints on Apigee Edge:

  • Login page redirect -- (required) OAuth requires that the use be directed to a login page for the protected resource server. This is often implemented on Edge with a RaiseFault or AssignMessage policy, and simply issues a redirect to the login page's URL. Typically attached to an endpoint called /authorize.
  • GenerateAccessToken -- (required) Generates and returns an access code to the client app. Typically attached to an endpoint called /token or /accesstoken.
  • RefreshAccessToken -- (optional, recommended) Generates an access token when presented with a valid refresh token. Typically attached to an endpoint called /refreshtoken.

Resource owner password grant type

This grant type uses these endpoints on Apigee Edge:

  • GenerateAccessToken -- (required) Generates and returns an access code to the client app. Typically attached to an endpoint called /token or /accesstoken.
  • RefreshAccessToken -- (optional, recommended) Generates an access token when presented with a valid refresh token. Typically attached to an endpoint called /refreshtoken.

Client credentials grant type

This grant type uses these endpoints on Apigee Edge:

  • GenerateAccessToken -- (required) Generates and returns an access code to the client app. Typically attached to an endpoint called /token or /accesstoken.
  • RefreshAccessToken -- (optional, recommended) Generates an access token when presented with a valid refresh token. Typically attached to an endpoint called /refreshtoken.

 

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?)