Understanding OAuth endpoints

To do its job as an OAuth2 authorization server, Apigee Edge needs to expose endpoints where clients can request tokens and auth codes. This topic offers a quick introduction to these endpoints, and shows you how to set them up in Edge.

What is an OAuth2 endpoint?

An OAuth2 endpoint is a URL that clients call to request OAuth tokens (or auth codes). Here's an example request for an access token:

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

In your Apigee Edge environment, a policy is required to handle this kind of request. As you can infer from the request, the policy must support the "client credentials" grant type, and the policy must execute on the path /oauth/client_credentials/accesstoken.

The correct policy in this case is an OAuthV2 policy, configured to execute in a flow such as the following example illustrates (where the policy name is GenerateAccessTokenClient):

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

If the client provides the correct credentials, the policy generates and returns a token; otherwise, it returns an error.

Locating the default endpoints

Apigee adds an example OAuth2 endpoint proxy, by default, to every new organization that it creates. If you look, you'll find a proxy called oauth in your organization.

To find this proxy:

  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.
  4. In the proxy overview page, select the Develop tab to bring up the proxy editor, and examine the policies and flows in the proxy.

Best practice: Create your own OAuth2 endpoint proxy

The default oauth proxy is limited: it only supports the client credentials grant type. This proxy is meant to be an example only. For production, you will want to create a proxy that configures the OAuth2 endpoints that meet your requirements.

One important note: a proxy that defines OAuth2 endpoints is typically a No Target proxy. The proxy acts as a service that executes in the ProxyEndpoint and returns directly back to the client.

Related topics

Requesting access tokens and authorization codes