Screencast: Issuing OAuth tokens in Apigee Edge using Password Grant, and verifying same

[dchiesa1]

Why Password Grant?

As you probably know, "password grant" is one of the grant types described in the OAuthV2.0 specification, also known as IETF RFC 6749. Password grant token issuance makes the most sense when both Apigee Edge and the client app (aka client) are trusted to handle user credentials.

Imagine an employer app collecting employee credentials to allow signin . That's a case where password grant would make sense. Or, imagine a consumer mobile app produced by the same company that has the service - like the branded store app that connects to your store loyalty account. In these cases a user won't mind keying in their user credentials to the trusted app, and transmitting those credentials to Apigee Edge is ok.

When is password grant NOT appropriate? Third party apps using common services. For example imagine a retailer (Retailer X) that wants to expose some of its capability, let's say a photo printer, to third party applications. The apps themselves are not branded by the retailer, and they are not vetted by the retailer. In this case the user would not (should not!) approve of the app requesting user credentials for his or her Retailer X loyalty account. The app has no business handling that information. The app is untrusted. In that case, a password grant is inappropriate, and something like the Authorization code grant type should be used. That alternative allows verification of user credentials, without sharing those credentials with the untrusted app.

Grant Types and User vs App Identity

The above mentioned the password and authorization code grant types. Both of these grant types verify the client (app) credentials as well as the user (human) credentials, though in different ways. Tokens issued with either of these grant types can be associated with a user context - some information about the user. Maybe the user name, the user account number, the user email, user id, and so on. These data can be implicitly associated to tokens in Apigee Edge via "Custom Attributes" on tokens.

There are other grant types - for examine, the client credentials grant type verifies only application credentials. There is no user information presented, and so the token does not store a user name, or any other user data.

How does Grant Type affect Token Verification?

In Apigee Edge, all tokens can be verified at runtime in the same way, with the OAuthV2/VerifyAccessToken policy, regardless of the grant type used to issue them. BUT, you as proxy designer can optionally check the grant type, to insure that there is a user context associated to the token. As an example of when this would be relevant: placing an item into a shopping cart (via an API call) might be a thing that is possible without a specific user context. An app could allow an "anonymous" shopping cart. But "checking out" ought to require a user context - because you want to update the user profile. So your API proxy might check to see if the user context is available, and if not, send back a response to the app to upgrade the token (require the user to login).

Let's see it working

Here is a quick screencast, about 12 minutes long, giving an overview of how to configure Apigee Edge to issue OAuth tokens via the password grant. There is code available supporting this example, on this repo.