Understanding OAuth endpoints

You're viewing Apigee Edge documentation.
Go to the Apigee X documentation. info

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. Access the API Proxies page, as described below.

   Edge

   To access the API Proxies page using the Edge UI:

   1. Sign in to apigee.com/edge.
   2. Select Develop > API Proxies in the left navigation bar.
   3. Click +Proxy

   Classic Edge (Private Cloud)

   To access the API Proxies page using the Classic Edge UI:

   1. Sign in to http://ms-ip:9000, where ms-ip is the IP address or DNS name of the Management Server node.
   2. Select APIs > API Proxies in the top navigation bar.
2. In the list of proxies, select the one called oauth.
3. 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