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.
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
<Flow name="generate-access-token"> <Description/> <Request> <Step> <FaultRules/> <Name>GenerateAccessToken</Name> </Step> </Request> <Response/> <Condition>(proxy.pathsuffix MatchesPath "/token") and (request.verb = "POST")</Condition> </Flow>
For more information about conditional flows, see 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'
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.
- Log in to your Apigee Edge account.
- Select APIs > API Proxies from the main menu.
- 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.
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.