API OAuth vs customer account and grant types for beginners

[GCPexplorer]

Hi all,

I'm just beginning my journey with Apigee and in this OAuth tutorial:

https://docs.apigee.com/api-platform/tutorials/secure-calls-your-api-through-oauth-20-client-credent...

I'm trying to understand the grant types and authentication

<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>  

I understand that in this tutorial we use the App Key and Secret to generate the token. So the access is bound to the developer/product/App. 

What I don't understand is the grant type as explained in the <SupportedGrantTypes> comment "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".

1. How would I use the grant type if I wanted to use it with user authentication?

2. Can this be used on the customer account level? E.g. to provide access to each individual customers account (not developer/product/app) so only they can access their details securely. 

Many thanks and hope this makes sense.

[dchiesa1 · Accepted solution]

I'll provide a brief summary, and also, I encourage you to Google around and read more about OAuth.

OAuth 2.0 is a framework for Authorization over HTTP.

The framework is defined in the IETF Specification RFC 6749, which I encourage you to read. I probably sound like your primary school teacher, but yes, you should read it. Specifications can be dry reading, but it's really. helpful to do the reading to understand the motivations and mechanisms within OAuth 2.0.

The abstract in that spec says:

   The OAuth 2.0 authorization framework enables a third-party application to obtain limited 
   access to an HTTP service, either on behalf of a resource owner by orchestrating an approval 
   interaction between the resource owner and the HTTP service, or by allowing the third-party 
   application to obtain access on its own behalf. 

It's not written as clearly as I would like. Let me try to break that down.

1. It allows a third-party app to obtain limited access. "Third party" means it applies to an app that is not built by the API provider. The three parties implicit in that statement are: the API provider or service provider, aka resource manager; the app developer or publisher; and the user (aka resource owner).
   OAuth is designed for that three-party model. If the photo sharing service published its own app, it wouldn't need OAuth! Or ... It could use OAuth, but OAuth 2.0 was not designed for that use case.
2. "...on behalf of a resource owner...or....on its own behalf".
   This means that OAuth addresses two cases: one in which the app is working on behalf of a user, and the other in which the app is acting on its own. No user context!

Imagine a photo sharing service that exposes an API. The product manager at the photo sharing service wants third party developers to build their own apps that post photos and retrieve photos form the photo sharing service. The USER is the resource OWNER. They're MY photos. Or YOUR photos. The photo service is the resource MANAGER. That service manages my photos for me. The app is the third party. OAuth provides a way to authenticate the app itself - the client - as well as the user. In OAuth, both the application and the user can be identified and authenticated. The resource provider (photo service) can make authorization decisions based on BOTH of those authenticated identities. This is case 1: the app is working on behalf of a user.

Case 2 might be a separate app that peruses the photos that have been posted publicly. They're available for anonymous (no user context) access. But the photo service might want to rate limit the API, or provide other governance. So the photo service wants to identify the APP, even if there is no user. This is the case of the app acting on its own behalf.

In either case, OAuth 2.0 depends on the idea of a token: the client (app) will obtain a token, and then present that token when asking for service - for example, when asking to retrieve a list of photos from the photo service. The resource manager can validate the token and then make a decision whether to grant service. If the token is expired, or if the token belongs to a different user... then the RM can reject the request for service.

OAuth2.0 defines various "grant types" to support these two cases - an app acting on behalf of a user, and an app acting on its own. The grant types are just definitions of the different ways that the app obtains a token.

• client_credentials is for an app acting on its own
• authorization_code and password are for an app acting on behalf of a user
• implicit grant type has been deprecated, you should ignore it.

Now, to your specific questions.

1. How would I use the grant type if I wanted to use it with user authentication?

You would use password or authorization_code grant types.

2. Can this be used on the customer account level? E.g. to provide access to each individual customers account (not developer/product/app) so only they can access their details securely.

Yes, that is the purpose of the password or authorization_code grant types. The idea is to authorize BOTH the user and the app (and implicitly the developer, the owner of the app), before granting service.

It sounds like you're starting off on your journey exploring OAuth. I'd encourage you to read up on it. There are some Apigee platform samples available on github that show various proxies that use OAuth to grant tokens or validate tokens. Exploring those might give you some more context to understand how to use OAuth with Apigee. 

---

Also, here are some Apigee-published 4-minute videos that explain OAuth, grant types, and how Apigee can help. These are a few years old, but still apply today!

• S24E01 - Why do you need OAuth 2.0?
• S24E02 - OAuth 2.0 explained
• S24E03 - Apigee as OAuth Server
• S24E04 - OAuth 2.0 grant types

There are lots of other materials out there, too.

[dchiesa1 · Accepted solution]

I'll provide a brief summary, and also, I encourage you to Google around and read more about OAuth.

OAuth 2.0 is a framework for Authorization over HTTP.

The framework is defined in the IETF Specification RFC 6749, which I encourage you to read. I probably sound like your primary school teacher, but yes, you should read it. Specifications can be dry reading, but it's really. helpful to do the reading to understand the motivations and mechanisms within OAuth 2.0.

The abstract in that spec says:

   The OAuth 2.0 authorization framework enables a third-party application to obtain limited 
   access to an HTTP service, either on behalf of a resource owner by orchestrating an approval 
   interaction between the resource owner and the HTTP service, or by allowing the third-party 
   application to obtain access on its own behalf. 

It's not written as clearly as I would like. Let me try to break that down.

1. It allows a third-party app to obtain limited access. "Third party" means it applies to an app that is not built by the API provider. The three parties implicit in that statement are: the API provider or service provider, aka resource manager; the app developer or publisher; and the user (aka resource owner).
   OAuth is designed for that three-party model. If the photo sharing service published its own app, it wouldn't need OAuth! Or ... It could use OAuth, but OAuth 2.0 was not designed for that use case.
2. "...on behalf of a resource owner...or....on its own behalf".
   This means that OAuth addresses two cases: one in which the app is working on behalf of a user, and the other in which the app is acting on its own. No user context!

Imagine a photo sharing service that exposes an API. The product manager at the photo sharing service wants third party developers to build their own apps that post photos and retrieve photos form the photo sharing service. The USER is the resource OWNER. They're MY photos. Or YOUR photos. The photo service is the resource MANAGER. That service manages my photos for me. The app is the third party. OAuth provides a way to authenticate the app itself - the client - as well as the user. In OAuth, both the application and the user can be identified and authenticated. The resource provider (photo service) can make authorization decisions based on BOTH of those authenticated identities. This is case 1: the app is working on behalf of a user.

Case 2 might be a separate app that peruses the photos that have been posted publicly. They're available for anonymous (no user context) access. But the photo service might want to rate limit the API, or provide other governance. So the photo service wants to identify the APP, even if there is no user. This is the case of the app acting on its own behalf.

In either case, OAuth 2.0 depends on the idea of a token: the client (app) will obtain a token, and then present that token when asking for service - for example, when asking to retrieve a list of photos from the photo service. The resource manager can validate the token and then make a decision whether to grant service. If the token is expired, or if the token belongs to a different user... then the RM can reject the request for service.

OAuth2.0 defines various "grant types" to support these two cases - an app acting on behalf of a user, and an app acting on its own. The grant types are just definitions of the different ways that the app obtains a token.

• client_credentials is for an app acting on its own
• authorization_code and password are for an app acting on behalf of a user
• implicit grant type has been deprecated, you should ignore it.

Now, to your specific questions.

1. How would I use the grant type if I wanted to use it with user authentication?

You would use password or authorization_code grant types.

2. Can this be used on the customer account level? E.g. to provide access to each individual customers account (not developer/product/app) so only they can access their details securely.

Yes, that is the purpose of the password or authorization_code grant types. The idea is to authorize BOTH the user and the app (and implicitly the developer, the owner of the app), before granting service.

It sounds like you're starting off on your journey exploring OAuth. I'd encourage you to read up on it. There are some Apigee platform samples available on github that show various proxies that use OAuth to grant tokens or validate tokens. Exploring those might give you some more context to understand how to use OAuth with Apigee. 

---

Also, here are some Apigee-published 4-minute videos that explain OAuth, grant types, and how Apigee can help. These are a few years old, but still apply today!

• S24E01 - Why do you need OAuth 2.0?
• S24E02 - OAuth 2.0 explained
• S24E03 - Apigee as OAuth Server
• S24E04 - OAuth 2.0 grant types

There are lots of other materials out there, too.

[GCPexplorer · Accepted solution]

Hi,

Thanks for the answer, yes I found the samples being the explanation that I needed, especially https://github.com/apigee/api-platform-samples/tree/master/sample-proxies/oauth-validate-key-secret despite it being outdated and not importing because of errors it's a useful reference, also https://docs.apigee.com/api-platform/security/oauth/implementing-password-grant-type was very useful. 

Thanks

[dchiesa1]

I'm glad that worked. I'll get that sample fixed, too, so that it imports.