StreetCarts: Implementing authorization across Edge and API BaaS

[straut]

Apigee Edge and Apigee API BaaS both provide support for implementing authorization to protect your backend resources. When you're using API BaaS as a backend data store for an Edge application, you might wonder where the heavy lifting for authorization should occur.

This article describes one way to combine authorization features in both products so that they work together in a complementary way. You can use OAuth2 scopes in Edge to reduce unauthorized traffic to the backend, then use specific verb/endpoint access control to prevent unauthorized access to individual resources.

Note: This article is one in a series that uses the StreetCarts sample application to illustrate implementing authentication and authorization where Apigee Edge and Apigee API BaaS are combined in a single application. The series includes Authentication and authorization with Apigee Edge and API BaaS, Registering and authenticating new users with Edge and API BaaS, and Updating API BaaS permissions at runtime. By @Floyd Jones, @Steve Traut, @wwitman.

Authorizing for categories of requests using OAuth2 scopes

By setting up OAuth2 scopes to filter out categories of requests that a user wouldn't possible be permitted to do, you can reduce traffic to the backend.

When using OAuth2 scopes, you can:

• Verify that a client app user is allowed to access protected resources generally.
• Use custom attributes to store (for later use) the API BaaS access token in the OAuth2 bearer token.
• Prevent requests by unauthorized users from reaching the backend target.

In StreetCarts, for example, OAuth2 scopes define the ability to edit food carts generally, but don't prohibit access to a particular food cart. Each OAuth2 scope value defines a category that pairs a user type with an allowed action. For example, a user attempting to delete a food cart must have the owner.delete scope value in order for their request to reach API BaaS.

(See the "Authorizing for each verb/resource pair using API BaaS permissions" section below for info on defining access to specific verb/resource combinations.)

As described in "Registering and authenticating new users with Edge and API BaaS", you set scope values for a user when authenticating, inserting them in the OAuth2 token generated by the OAuth2 policy. You do this by putting the scope value in the <Scope> element when generating the token.

Here's how StreetCarts verifies scope values when authorizing at runtime:

1. The user authenticates and sends their access token with a request for a protected resource.
2. The authenticated user makes a request for a protected verb/resource pair. For example, they request to DELETE /foodcarts/:cartID.
3. In the proxy receiving the request, an OAuth2 policy with a VerifyAccessToken operation (such as Validate-Token-Owner-Access ) checks to see if any of the scope values in the user's access token match any of the values in the policy's <Scope> element.
4. If any of the user's scope values matches, the request is allowed to proceed to the backend, where it is authorized again, as described below.

Authorizing for each verb/resource pair using API BaaS permissions

API BaaS user groups, roles, and permissions provide a way to set up specific access for any verb/resource pair defined in the data store. If your backend data store is API BaaS, you can use those features to set up fine-grained access control.

By using API BaaS security, you can:

• Group users by roles.
• Define specific access to verb/endpoint pairs in roles, which apply to users associated with the roles.
• Prevent unauthorized users from accessing specific verb/endpoint combinations.

In general, here's how to set up API BaaS to authorize requests for specific verb/resource pairs:

1. You create user groups that represent categories of users, such as "Owners" and "Managers". You can do this when you set up the application or at run time. (StreetCarts includes a script for setting up groups, roles, and permissions.)
2. Add users to your API BaaS user groups. You can do this with code when they register for an account, as described above in "Register users".
3. Create roles that contain permissions authorizing GET, PUT, POST, or DELETE access for specific resources.
4. Associate the roles with the groups. This applies permissions defined in the roles to every user account in the group.

With API BaaS permissions configured, here's how StreetCarts authorizes requests for protected verb/resource pairs:

1. The user authenticates and sends their access token with a request for a protected resource such as DELETE /foodcarts/:cartID.
2. The proxy uses an OAuth2 policy with a VerifyAccessToken operation (such as Validate-Token-Owner-Access ) to confirm that at least one the scope values in the user's access token match one of the values in the policy's <Scope> element.
3. If authorized by scope, the request proceeds to the GetDataManagerKey policy, which retrieves the data-manager API key value from a key/value map.
4. Using the data-manager API key to authenticate, the foodcarts proxy calls out to the data-manager proxy to forward the request to the data store.
5. The data-manager proxy's data-manager.js translates the original request into a request for the protected resource in the data store ( such as to delete the specified food cart ), with the result being a call to the API BaaS API. The new request for API BaaS includes the access token generated when the requesting user authenticated.
6. Internally, API BaaS confirms that the user has permission to perform the specified verb with the specified resource. To do this, it determines:
   • Which user groups a user is in.
   • Whether any of those groups is associated with a role that permits the requested action.
   • If the requested action is permitted for the user, the request is allowed to continue.
7. API BaaS returns the response through the data-manager proxy to the foodcarts proxy and the client.

For example, if a user making a request to delete a food cart carries the owner.delete scope, their request must also be authorized for the specific food cart they want to delete. Imagine they want to delete the cart whose ID is 9e82599a-bf80-11e5-87ec-29bc7103e627. For their request to succeed, their user account must be associated with a role that allows the following:

DELETE /foodcarts/9e82599a-bf80-11e5-87ec-29bc7103e627