Understanding OAuth endpoints

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 offers a quick introduction to endpoints. For details on combining endpoints with policies to perform specific OAuth tasks, see Requesting access tokens and authorization codes.

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. These endpoints refer to specific OAuth 2.0 policies that execute when the endpoint is called.

Here's an example. In this flow, the GenerateAccessToken policy is executed when the proxy path matches /token.

        <Flow name="generate-access-token">
            <Condition>(proxy.pathsuffix MatchesPath &quot;/token&quot;) and (request.verb = &quot;POST&quot;)</Condition>

For more information about conditional flows, see Configuring flows.

Here's an example API call to the /token endpoint on Apigee Edge. For more examples, see Requesting access tokens and authorization codes.

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

Using the 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.

  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. You'll see in this tab the policies and flows that are configured to support this OAuth grant type flow.

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.

Related topics

Requesting access tokens and authorization codes