Secure an API with OAuth

This tutorial shows you how to secure an API with OAuth 2.0.

OAuth is an authorization protocol that enables apps to access information on behalf of users without requiring users to divulge their username and password.

With OAuth, security credentials (such as username/password or key/secret) are exchanged for an access token. For example:

joe:joes_password (username:password) or
Nf2moHOASMJeUmXVdDhlMbPaXm2U7eMc:unUOXYpPe74ZfLEb (key:secret)

becomes something like:

b0uiYwjRZLEo4lEu7ky2GGxHkanN

The access token is a random string of characters and is temporary (it should expire after a relatively short time), so passing it around to authenticate a user in an app workflow is much more secure than passing around actual credentials.

The OAuth 2.0 specification defines different mechanisms, called "grant types," for distributing access tokens for apps. The most basic grant type defined by OAuth 2.0 is called "client credentials." In this grant type, OAuth access tokens are generated in exchange for client credentials, which are consumer key/consumer secret pairs, like the example above.

The client credentials grant type in Edge is implemented using policies in API proxies. A typical OAuth flow in involves two steps:

• Call API proxy 1 to generate an OAuth access token from client credentials. An OAuth v2.0 policy on the API proxy handles this.
• Call API proxy 2 to send the OAuth access token in an API call. The API proxy verifies the access token using an OAuth v2.0 policy.

What you'll need

• An Apigee Edge account. If you don't have one yet, you can sign up with the directions at Creating an Apigee Edge account.
• cURL installed on your machine to make API calls from the command line.

Download and deploy a token-generating API proxy

In this step, you'll create the API proxy that generates an OAuth access token from a consumer key and consumer secret sent in an API call. Apigee provides a sample API proxy that does this. You'll download and deploy the proxy now, then use it later in the tutorial. (You could build this API proxy easily yourself. This download and deploy step is for convenience and to show you how easy it is to share proxies that have already been created.)

1. Download the 'oauth' sample API proxy ZIP file to any directory on your file system.
2. Go to https://apigee.com/edge and sign in.
3. Select Develop > API Proxies in the left navigation bar.
4. Click + Proxy.
   
5. In the Create Proxy wizard, click Upload proxy bundle.
6. Choose the oauth.zip file you downloaded, and click Next.
7. Click Create.
8. After the build completes, click Edit proxy to view the new proxy in the API proxy editor.
9. On the API Proxy editor Overview page, click the Deployment drop-down and select test. This is the test environment in your organization.
   
   At the confirmation prompt, click Deploy.
   When you click the Deployment drop-down again, a green icon indicates that the proxy is deployed to the test environment.
   

Way to go! You've successfully downloaded and deployed an access token-generating API proxy to your Edge organization.

View the OAuth flow and policy

Let's take a closer look at what the API proxy contains.

1. In the API proxy editor, click the Develop tab. In the left Navigator pane, you'll see two policies. You'll also see two POST flows in the Proxy Endpoints section.

2. Click AccessTokenClientCredential under Proxy Endpoints.
   

   In the XML code view, you'll see a Flow called AccessTokenClientCredential:

   <Flow name="AccessTokenClientCredential">
       <Description/>
       <Request>
           <Step>
               <Name>GenerateAccessTokenClient</Name>
           </Step>
       </Request>
       <Response/>
       <Condition>(proxy.pathsuffix MatchesPath "/accesstoken") and (request.verb = "POST")</Condition>
   </Flow>

   A flow is a processing step in an API proxy. In this case, the flow is triggered when a certain condition is met (it's called a conditional flow). The condition, defined in the <Condition> element, says that if the API proxy call is made to the /accesstoken resource, and the request verb is POST, then execute the GenerateAccessTokenClient policy, which generates the access token.

3. Now let's look at the policy the conditional flow will trigger. Click the GenerateAccessTokenClient policy icon in the flow diagram.
   
   The following XML configuration is loaded into the code view:

   <OAuthV2 name="GenerateAccessTokenClient">
       <!-- This policy generates an OAuth 2.0 access token using the client_credentials grant type -->
       <Operation>GenerateAccessToken</Operation>
       <!-- This is in millseconds, so expire in an hour -->
       <ExpiresIn>3600000</ExpiresIn>
       <SupportedGrantTypes>
           <!-- This part is very important: most real OAuth 2.0 apps will want to use other
            grant types. In this case it is important to NOT include the "client_credentials"
            type because it allows a client to get access to a token with no user authentication -->
           <GrantType>client_credentials</GrantType>
       </SupportedGrantTypes>
       <GrantType>request.queryparam.grant_type</GrantType>
       <GenerateResponse/>
   </OAuthV2>

   The configuration includes the following:

   • The <Operation>, which can be one of several predefined values, defines what the policy is going to do. In this case, it's going to generate an access token.
   • The token will expire 1 hour (3600000 milliseconds) after being generated.
   • In <SupportedGrantTypes>, the OAuth <GrantType> expected to be used is client_credentials (exchanging a consumer key and secret for an OAuth token).
   • The second <GrantType> element tells the policy where to look in the API call for the grant type parameter, as required by the OAuth 2.0 specification. (You'll see this in the API call later). The grant type could also be sent in the HTTP header (request.header.grant_type) or as a form parameter (request.formparam.grant_type).

You don't need to do anything else with the API proxy at the moment. In later steps, you'll use this API proxy to generate an OAuth access token. But first, you need to do a few more things:

• Create the API proxy you actually want to secure with OAuth.
• Create a few more artifacts that will result in the consumer key and consumer secret you need to exchange for an access token.

Create the OAuth-protected API proxy

Now you're going to create the API proxy you want to protect. This is the API call that returns something you want. In this case, the API proxy will call Apigee's mocktarget service to return your IP address. BUT, you'll get to see it only if you pass a valid OAuth access token with your API call.

The API proxy you create here will include a policy that checks for an OAuth token in the request.

1. Select Develop > API Proxies in the left navigation bar.
2. Click + Proxy.
   
3. In the Build a Proxy wizard, select Reverse proxy (most common), and click Next.
4. Configure the proxy with the following:
   

   In this field	do this
   Proxy Name	Enter: helloworld_oauth2
   Project Base Path	Change to: /hellooauth2 The Project Base Path is part of the URL used to make requests to the API proxy.
   Existing API	Enter: https://mocktarget.apigee.net/ip This defines the target URL that Apigee Edge invokes on a request to the API proxy.
   Description	Enter: hello world protected by OAuth

5. Click Next.
6. On the Common policies page:

   In this field	do this
   Security: Authorization	Select: OAuth 2.0

7. Click Next.
8. On the Virtual Hosts page, click Next.
9. On the Build page, make sure the test environment is selected, and click Create and Deploy.
10. On the Summary page, you see an acknowledgment that your new API proxy was created successfully, and that the API proxy was deployed to your test environment.
11. Click Edit proxy to display the Overview page for the API proxy.
    Notice that this time the API proxy is automatically deployed. Click the Deployment drop-down to make sure there's a green deployment dot next to the "test" environment.