Gluu Blog

Follow us:
Back to Blog

How to centrally issue OAuth tokens for API access management

Mike S. November 9, 2015

Centralized API Security with UMA profile of OAuth2

So you want to use OAuth2 bearer tokens to protect your API’s to avoid putting credentials in each request. Great idea! But if you have lots of API’s, you may want to build a central service that takes care of registering clients, and issuing tokens. A good way to do this is to use the OpenID Connect profile of OAuth2 for registering your clients, and the User Managed Access (UMA) profile of OAuth2 for centralizing token issuance.

The diagram above is not a comprehensive overview of UMA, which has lots of neat features. But for the purpose of this blog it should suffice! Let’s review some of the key points about how the design works.

  • Client Registration: Both the UMA client and the UMA Resource Server (RS) are clients–they both need to call API’s on the Authorization Server (AS). Therefore, both should use OpenID Connect dynamic client registration to obtain either API secret, or to register a public key for subsequent private key client authentication.
  • Resource Registration: The Resource Server has API’s that it wants to protect. In REST jargon, resources are URI’s. The RS needs uses a protocol called OAuth2 Resource Registration to tell the AS what API’s it has, and what scopes should be required to allow access. Note: the AS will determine what policies are required to grant access to a given scope–the RS doesn’t know about the policies.
  • Client Calls API (first time): UMA starts when the client calls and API. Note the client is software acting on behalf of a person. It could be a mobile applicaiton or a website. On the first API call, the UMA Client has no token. In UMA this token is called an “RPT”–Resource Protection Token. Without an RPT, the RS returns 403 (not authorized). This isn’t very helpful to the client! Here is one of the coolest UMA tricks: before it returns the 403, the RS obtains a permission ticket from the AS, so the AS can remember what Resources Set was being requested. This permission ticket is returned to the UMA Client with the 403.
  • UMA Client obtains RPT: Now the frustrated UMA client has some work to do. If it wants access to this API, its going to need to obtain an RPT from the AS. That’s the job of the AS RPT endpoint. The client uses that permission ticket to request an RPT. The AS remembers the associated resource set, and looks up all the scopes required to grant access. Each scope can be associated with different policies–for example which person, using which client, from which network, during what time of day, with what fraud score (etc, etc, etc) can access this API? Let’s just say all the policies are ok, and the AS returns a token.
  • UMA Client Calls API (second time): The client takes this token, and uses it like a standard OAuth2 bearer token–inserting in the header Authorization: Bearer c2186be6-120b-49c8-b530-4617ddc01ea6
  • Resource Server validates token: How does the RS know that this token is valid if it didn’t issue it? There are two possible ways: (1) the UMA protocol specifies that the RS should call the token introspection endpoint, and trade the bearer token for a JWT that would contain information about whether the token is expired (or even whether any of the associated permissions are expired). (2) The AS can encrypt the RPT, and use this as the bearer token. The RS could then decrypt it, and validate the contents. This method is not specified by the UMA protocol, but it should work fine.
  • Resource server returns application data: With a valid RPT token, the RS knows that the AS has successfully evaluated all the policies, and the RS should execute the request.
  • OAuth2 Client Credentail Grant: The AS itself uses OAuth2 so the client doesn’t have to put client credentials in every request. For this, the OAuth2 Client Credential Grant is used. This can be accomplished with either API secret, or with private key via a JWKS that was registered as part of OpenID Connect client registration. Note: both the RS and UMA Client use such client credential tokens, referred to as the “AAT” and “PAT” tokens in the UMA specification.

One of the advantages of the UMA design is that developers don’t need to know the scopes, so you won’t have to publish a long list like Google. One could argue that exposing the scopes is more security info than the client really needs to know. Also, if Google changes its mind about what scopes should be required to access a certain API, they would need to communicate this change to application developers, leading to a tighter bundling of the security infrastructure to the application code.

Are you ready to get started? The good news is that you can use the free open source Gluu Server to get the job done! Its easy to install Community Edition: just install the package, run the setup program, and you’re off to the races!

If you’re a large organization that needs support, please check our pricing page or contact us to see a demo.[:ja]Centralized API Security with UMA profile of OAuth2

So you want to use OAuth2 bearer tokens to protect your API’s to avoid putting credentials in each request. Great idea! But if you have lots of API’s, you may want to build a central service that takes care of registering clients, and issuing tokens. A good way to do this is to use the OpenID Connect profile of OAuth2 for registering your clients, and the User Managed Access (UMA) profile of OAuth2 for centralizing token issuance.

The diagram above is not a comprehensive overview of UMA, which has lots of neat features. But for the purpose of this blog it should suffice! Let’s review some of the key points about how the design works.

  • Client Registration: Both the UMA client and the UMA Resource Server (RS) are clients–they both need to call API’s on the Authorization Server (AS). Therefore, both should use OpenID Connect dynamic client registration to obtain either API secret, or to register a public key for subsequent private key client authentication.
  • Resource Registration: The Resource Server has API’s that it wants to protect. In REST jargon, resources are URI’s. The RS needs uses a protocol called OAuth2 Resource Registration to tell the AS what API’s it has, and what scopes should be required to allow access. Note: the AS will determine what policies are required to grant access to a given scope–the RS doesn’t know about the policies.
  • Client Calls API (first time): UMA starts when the client calls and API. Note the client is software acting on behalf of a person. It could be a mobile applicaiton or a website. On the first API call, the UMA Client has no token. In UMA this token is called an “RPT”–Resource Protection Token. Without an RPT, the RS returns 403 (not authorized). This isn’t very helpful to the client! Here is one of the coolest UMA tricks: before it returns the 403, the RS obtains a permission ticket from the AS, so the AS can remember what Resources Set was being requested. This permission ticket is returned to the UMA Client with the 403.
  • UMA Client obtains RPT: Now the frustrated UMA client has some work to do. If it wants access to this API, its going to need to obtain an RPT from the AS. That’s the job of the AS RPT endpoint. The client uses that permission ticket to request an RPT. The AS remembers the associated resource set, and looks up all the scopes required to grant access. Each scope can be associated with different policies–for example which person, using which client, from which network, during what time of day, with what fraud score (etc, etc, etc) can access this API? Let’s just say all the policies are ok, and the AS returns a token.
  • UMA Client Calls API (second time): The client takes this token, and uses it like a standard OAuth2 bearer token–inserting in the header Authorization: Bearer c2186be6-120b-49c8-b530-4617ddc01ea6
  • Resource Server validates token: How does the RS know that this token is valid if it didn’t issue it? There are two possible ways: (1) the UMA protocol specifies that the RS should call the token introspection endpoint, and trade the bearer token for a JWT that would contain information about whether the token is expired (or even whether any of the associated permissions are expired). (2) The AS can encrypt the RPT, and use this as the bearer token. The RS could then decrypt it, and validate the contents. This method is not specified by the UMA protocol, but it should work fine.
  • Resource server returns application data: With a valid RPT token, the RS knows that the AS has successfully evaluated all the policies, and the RS should execute the request.
  • OAuth2 Client Credentail Grant: The AS itself uses OAuth2 so the client doesn’t have to put client credentials in every request. For this, the OAuth2 Client Credential Grant is used. This can be accomplished with either API secret, or with private key via a JWKS that was registered as part of OpenID Connect client registration. Note: both the RS and UMA Client use such client credential tokens, referred to as the “AAT” and “PAT” tokens in the UMA specification.

One of the advantages of the UMA design is that developers don’t need to know the scopes, so you won’t have to publish a long list like Google. One could argue that exposing the scopes is more security info than the client really needs to know. Also, if Google changes its mind about what scopes should be required to access a certain API, they would need to communicate this change to application developers, leading to a tighter bundling of the security infrastructure to the application code.

Are you ready to get started? The good news is that you can use the free open source Gluu Server to get the job done! Its easy to install Community Edition: just install the package, run the setup program, and you’re off to the races!

If you’re a large organization that needs support, please check our pricing page or contact us to see a demo.[:es]Centralized API Security with UMA profile of OAuth2

So you want to use OAuth2 bearer tokens to protect your API’s to avoid putting credentials in each request. Great idea! But if you have lots of API’s, you may want to build a central service that takes care of registering clients, and issuing tokens. A good way to do this is to use the OpenID Connect profile of OAuth2 for registering your clients, and the User Managed Access (UMA) profile of OAuth2 for centralizing token issuance.

The diagram above is not a comprehensive overview of UMA, which has lots of neat features. But for the purpose of this blog it should suffice! Let’s review some of the key points about how the design works.

  • Client Registration: Both the UMA client and the UMA Resource Server (RS) are clients–they both need to call API’s on the Authorization Server (AS). Therefore, both should use OpenID Connect dynamic client registration to obtain either API secret, or to register a public key for subsequent private key client authentication.
  • Resource Registration: The Resource Server has API’s that it wants to protect. In REST jargon, resources are URI’s. The RS needs uses a protocol called OAuth2 Resource Registration to tell the AS what API’s it has, and what scopes should be required to allow access. Note: the AS will determine what policies are required to grant access to a given scope–the RS doesn’t know about the policies.
  • Client Calls API (first time): UMA starts when the client calls and API. Note the client is software acting on behalf of a person. It could be a mobile applicaiton or a website. On the first API call, the UMA Client has no token. In UMA this token is called an “RPT”–Resource Protection Token. Without an RPT, the RS returns 403 (not authorized). This isn’t very helpful to the client! Here is one of the coolest UMA tricks: before it returns the 403, the RS obtains a permission ticket from the AS, so the AS can remember what Resources Set was being requested. This permission ticket is returned to the UMA Client with the 403.
  • UMA Client obtains RPT: Now the frustrated UMA client has some work to do. If it wants access to this API, its going to need to obtain an RPT from the AS. That’s the job of the AS RPT endpoint. The client uses that permission ticket to request an RPT. The AS remembers the associated resource set, and looks up all the scopes required to grant access. Each scope can be associated with different policies–for example which person, using which client, from which network, during what time of day, with what fraud score (etc, etc, etc) can access this API? Let’s just say all the policies are ok, and the AS returns a token.
  • UMA Client Calls API (second time): The client takes this token, and uses it like a standard OAuth2 bearer token–inserting in the header Authorization: Bearer c2186be6-120b-49c8-b530-4617ddc01ea6
  • Resource Server validates token: How does the RS know that this token is valid if it didn’t issue it? There are two possible ways: (1) the UMA protocol specifies that the RS should call the token introspection endpoint, and trade the bearer token for a JWT that would contain information about whether the token is expired (or even whether any of the associated permissions are expired). (2) The AS can encrypt the RPT, and use this as the bearer token. The RS could then decrypt it, and validate the contents. This method is not specified by the UMA protocol, but it should work fine.
  • Resource server returns application data: With a valid RPT token, the RS knows that the AS has successfully evaluated all the policies, and the RS should execute the request.
  • OAuth2 Client Credentail Grant: The AS itself uses OAuth2 so the client doesn’t have to put client credentials in every request. For this, the OAuth2 Client Credential Grant is used. This can be accomplished with either API secret, or with private key via a JWKS that was registered as part of OpenID Connect client registration. Note: both the RS and UMA Client use such client credential tokens, referred to as the “AAT” and “PAT” tokens in the UMA specification.

One of the advantages of the UMA design is that developers don’t need to know the scopes, so you won’t have to publish a long list like Google. One could argue that exposing the scopes is more security info than the client really needs to know. Also, if Google changes its mind about what scopes should be required to access a certain API, they would need to communicate this change to application developers, leading to a tighter bundling of the security infrastructure to the application code.

Are you ready to get started? The good news is that you can use the free open source Gluu Server to get the job done! Its easy to install Community Edition: just install the package, run the setup program, and you’re off to the races!

If you’re a large organization that needs support, please check our pricing page or contact us to see a demo.

Be sure to subscibe to
our RSS Feed

Mike Schwartz

Mike has been an entrepreneur and identity specialist for more than two decades. He is the technical and business visionary behind Gluu. Mike is an application security expert and has been a featured speaker at RSA Conference, Gartner Catalyst, Cloud Identity Summity (now "Identiverse") and many other security conferences around the world.