StreetCarts: Registering and authenticating new users with Edge and API BaaS

[straut]

You can use Apigee API BaaS as a user account data store behind Apigee Edge proxies. If your application combines Edge with API BaaS, (which both include support for OAuth2), you can use features of each to support OAuth across the application.

This article describes one way to combine Edge and API BaaS features to register and authenticate users. You can collect and store user account information, then use that information when generating a single Edge-generated OAuth2 access token that embeds a token representing the user at the backend.

This article is the first in a series that suggests one way to implement a complementary relationship between the two products. This article describes how to implement the most permissive category of requests -- those available to anonymous users -- where "authentication" requires merely a valid API key. Other articles in this series describe implementing more restrictive kinds of access.

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, Implementing authorization across Edge and API BaaS, and Updating API BaaS permissions at runtime. By @Floyd Jones, @Steve Traut, @wwitman.

Register new users

When you want to protect backend resources so that only certain users can access them, you can require users to authenticate before making requests. Before authenticating, you'll need to get them registered.

In StreetCarts, most verb/endpoint pairs represent access to resources that should be protected. For example, it wouldn't do to allow just anyone to delete a food cart or add new menu items.

To make any request other than a GET, a user must create an account. Any resource can be protected so that only certain users can perform certain actions with it -- as long as the app knows who the user is.

Here's how user registration works:

1. Client sends an anonymous POST request to create an account. the request goes to the /users proxy Create User endpoint. The request body includes information such as username and password.
2. The proxy uses a Verify-API-Key policy to check for an API key in a request header. If a valid API key is included, the request continues.
3. The request proceeds to the target endpoint , where a GetDataManagerKey policy retrieves the API key value from a key/value map.
4. The request uses the data-manager API key to authenticate with the data-manager proxy .
5. The data-manager.js registerUser function verifies that required data was included.
6. The registerUser function in data-manager.js POSTs a new user account to the API BaaS /users endpoint.
7. Once the new account is created, data-manager.js registerUser function adds the user to either a Members or Owners user group , depending on whether the original request specified that the user is a food cart owner.
8. Return user account response to the client.

Authenticate registered users

Registered users can authenticate to get access to protected resources. For example, in StreetCarts a food cart owner can make a request to POST /foodcarts to create a food cart, or a DELETE /foodcarts/:cartID request to remove it. Both of these actions are allowed only for registered owners.

In StreetCarts, a registered user must provide a valid username and password to log in. Edge asks the data-manager proxy to validate these credentials with the identity provider, which is the API BaaS data store. If the username and password are valid, they are exchanged for an OAuth2 access token, which is sent back to the client app. From there, the app can make protected API calls on behalf of the user. That means that application logic sends the username and password from the client back to the data store to validate, then generates an access token if validation is successful.

Here's how StreetCarts does authentication for registered users:

1. The authentication request goes to the /accesstoken proxy's GenerateAccessToken endpoint. The request body includes information such as username and password, with a header that includes an API key.
2. The proxy uses a Verify-API-Key policy to check for an API key in the request header.
3. 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 accesstoken proxy's Authenticate policy calls out to the data-manager proxy to forward the authenticate request to the data store.
5. In the data-manager proxy, the data-manager.js authenticateUser function uses the API BaaS /token endpoint to authenticate at the backend, generating an API BaaS OAuth2 token.
6. If the user successfully authenticates, the authenticateUser function retrieves from API BaaS the list of user groups in which the user is a member.
7. The API BaaS-generated access token and group list are returned to the /accesstoken proxy, where they are copied into variables by the Parse-Authentication-Response policy .
8. The group list is translated by SetScope.js into scope values predefined by the Edge product. The scope values are copied into an Edge variable .
9. In the GenerateToken policy , an OAuth2 GenerateAccessToken operation , scope values are copied from the variable into the Edge-generated token's <Scope> element so they're included in the access token. The BaaS-generated access token is also copied into the Edge-generated access token as a custom attribute for use in later requests to API BaaS.
10. The completed access token is returned to the client.

Note that authentication is a two-part process. In the end, the access token generated in an Edge proxy includes another access token generated by API BaaS. By using an API BaaS-generated access later returned by a client, StreetCarts can lean on the BaaS permissions framework for authorizing access to specific resources. For more, see "Authorize for each verb/resource pair using API BaaS permissions".