© Prabath Siriwardena 2020
P. SiriwardenaAdvanced API Securityhttps://doi.org/10.1007/978-1-4842-2050-4_19

UMA Evolution

Prabath Siriwardena1 
(1)
San Jose, CA, USA
 

User-Managed Access (UMA, pronounced “OOH-mah”) is an OAuth 2.0 profile. OAuth 2.0 decouples the resource server from the authorization server. UMA takes one step forward: it lets you control a distributed set of resource servers from a centralized authorization server. It also enables the resource owner to define a set of policies at the authorization server, which can be evaluated at the time a client is granted access to a protected resource. This eliminates the need for the resource owner’s presence to approve access requests from arbitrary clients or requesting parties. The authorization server can make the decision based on the policies defined by the resource owner.

ProtectServe

UMA has its roots in the Kantara Initiative. The Kantara Initiative is a nonprofit professional association focused on building digital identity management standards. The first meeting of the UMA working group was held on August 6, 2009. There were two driving forces behind UMA: ProtectServe and vendor relationship management (VRM). ProtectServe is a standard that was heavily influenced by VRM. The goal of ProtectServe was to build a permission-based data-sharing model that was simple, secure, efficient, RESTful, powerful, OAuth-based, and system identity agnostic. ProtectServe defines four parties in its protocol flow: the user, the authorization manager, the service provider, and the consumer.

The service provider (SP) manages the user’s resources and exposes them to the rest of the world. The authorization manager (AM) keeps track of all service providers associated with a given user. The user is the resource owner, who introduces all the service providers (or the applications he or she works with) to the authorization manager and builds access control policies that define the basis on which to share resources with others. The consumer consumes the user’s resources via the SP. Before consuming any services or resources, the consumer must request an access grant from the AM. The requested access grant is evaluated against the policies defined on the associated service by its owner, at the AM. ProtectServe uses OAuth 1.0 (see Appendix B) as the protocol for access delegation.

The steps in the ProtectServe protocol flow are as follows:

Step 1: The user or the resource owner introduces the SP to the AM (see Figure D-1).
  1. 1.

    The user provides the metadata URL of the AM to the SP.

     
  2. 2.

    The SP talks to the metadata endpoint of the AM and gets details related to the consumer key issuer, the request token issuer, the access token issuer, and the associated policies (OAuth 1.0 specification defines consumer key, request token, and access token).

     
  3. 3.

    The SP initiates an OAuth 1.0 flow by requesting an OAuth request token from the request token issuer (which could be the same AM).

     
  4. 4.

    The AM generates an authorization request token and sends it back to the SP along with other parameters defined under OAuth 1.0 specification.

     
  5. 5.

    The SP redirects the user to the AM with a token reference along with other parameters defined under OAuth 1.0 specification, to get it authorized.

     
  6. 6.

    Once authorized by the user, the authorization manager returns the authorized request token along with other parameters defined under OAuth 1.0 specification to the SP.

     
  7. 7.

    To complete the OAuth 1.0 flow, the SP exchanges the authorized request token for an access token, with the AM.

     
  8. 8.

    Once the OAuth flow is completed, the SP talks to the AM endpoint (which is secured with OAuth 1.0) to get an SP handle.

     
  9. 9.

    The AM validates the OAuth signature and, once verified, issues an SP handle to the SP. An SP handle is a unique identifier generated by the AM to identify the SP in future communications.

     
That completes the initial step in the ProtectServe protocol flow.
../images/323855_2_En_19_Chapter/323855_2_En_19_Fig1_HTML.jpg
Figure D-1

The service provider bootstraps trust with the authorization manager

Note

The service provider handle is a key that uniquely identifies the service provider at the authorization manager. This information is publicly available. A given service provider can have multiple service provider handles—one for each associated authorization manager.

Step 2: Each consumer who wants to get access to protected resources must be provisioned with corresponding consumer keys:
  1. 1.

    The consumer tries to access a protected resource hosted in an SP.

     
  2. 2.
    The SP detects the unauthenticated access attempt and returns an HTTP 401 status code with required details to get the SP metadata (see Figure D-2).
    ../images/323855_2_En_19_Chapter/323855_2_En_19_Fig2_HTML.jpg
    Figure D-2

    The consumer is rejected by the service provider with a 401 response. R1 represents a resource

     
  3. 3.

    With the details in the 401 response, the consumer talks to the SP’s metadata endpoint (see Figure D-2).

     
  4. 4.

    The SP metadata endpoint returns the SP handle (which is registered at the AM) and the corresponding AM endpoint.

     
  5. 5.

    The consumer talks to the AM endpoint to obtain a consumer key and a consumer secret (see Figure D-3).

     
  6. 6.

    The consumer requests an access token from the AM, with its consumer key and the SP handle. The request must be digitally signed by the corresponding consumer secret.

     
  7. 7.

    The AM validates the parameters in the access token request and issues an access token and a token secret to the consumer.

     
../images/323855_2_En_19_Chapter/323855_2_En_19_Fig3_HTML.jpg
Figure D-3

The consumer gets an access token from the authorization manager

Step 3: A consumer with a valid access token can access the protected resource hosted in the SP (see Figure D-4):
  1. 1.

    The consumer tries to access the protected resource in the SP with its access token, signed with the access token secret.

     
  2. 2.

    The SP talks to the AM and gets the secret key corresponding to the consumer’s access token. If required, the SP can store it locally.

     
  3. 3.

    The SP validates the signature of the request using the access token secret.

     
  4. 4.

    If the signature is valid, the SP talks to the policy decision endpoint of the AM, passing the access token and the SP handle. The request must be digitally signed by the corresponding access token secret.

     
  5. 5.

    The AM first validates the request, next evaluates the corresponding policies set by the user or the resource owner, and then sends the decision to the SP.

     
  6. 6.

    If the decision is a Deny, the location of the terms is returned to the SP, and the SP returns the location to the consumer with a 403 HTTP status code.

     
  7. 7.

    The consumer requests the terms by talking to the terms endpoint hosted in the AM. The request includes the consumer key, signed with the consumer secret.

     
  8. 8.

    When the consumer receives the terms, it evaluates them and talks to the AM with additional information to prove its legitimacy. This request includes the consumer key and is signed with the consumer secret.

     
  9. 9.

    The AM evaluates the additional information and claims provided by the consumer. If those meet the required criteria, the AM creates an agreement resource and sends the location of the agreement resource to the consumer.

     
  10. 10.

    If this requires the user’s consent, the AM must send it for the user’s approval before sending the location of the agreement resource.

     
  11. 11.

    Once the consumer receives the location of the agreement resource, it can talk to the corresponding endpoint hosted in the AM and get the agreement resource to see the status.

     
../images/323855_2_En_19_Chapter/323855_2_En_19_Fig4_HTML.jpg
Figure D-4

The consumer accesses a resource hosted at the service provider with valid OAuth credentials, but with limited privileges

Step 4: Once approved by the authorization manager, the consumer can access the protected resource with its access token and the corresponding secret key (see Figure D-5):
  1. 1.

    The consumer tries to access the protected resource at the SP with its access token, signed with the access token secret.

     
  2. 2.

    The SP talks to the AM and gets the secret key corresponding to the consumer’s access token. If required, the SP can store it locally.

     
  3. 3.

    The SP validates the signature of the request using the access token secret.

     
  4. 4.

    If the signature is valid, the SP talks to the policy decision endpoint of the AM, passing the access token and SP handle, signed with the corresponding access token secret.

     
  5. 5.

    The AM first validates the request, next evaluates the corresponding policies set by the user or the resource owner, and then sends the decision to the SP.

     
  6. 6.

    If the decision is an Allow from the AM, the SP returns the requested resource to the corresponding consumer.

     
  7. 7.
    The SP can cache the decision from the AM. Subsequent calls by the same consumer for the resource can utilize the cache instead of going to the AM.
    ../images/323855_2_En_19_Chapter/323855_2_En_19_Fig5_HTML.jpg
    Figure D-5

    The consumer accesses a resource hosted at the SP with valid OAuth credentials and with required privileges

     

UMA and OAuth

Over the years, ProtectServe evolved into UMA. ProtectServe used OAuth 1.0 to protect its APIs, and UMA moved from OAuth 1.0 to OAuth WRAP to OAuth 2.0. The UMA specification, which was developed under the Kantara Initiative for almost three years, was submitted to the IETF OAuth working group on July 9, 2011, as a draft recommendation for a user-managed data access protocol.

UMA 1.0 Architecture

The UMA architecture has five main components (see Figure D-6): the resource owner (analogous to the user in ProtectServe), the resource server (analogous to the service provider in ProtectServe), the authorization server (analogous to the authorization manager in ProtectServe), the client (analogous to the consumer in ProtectServe), and the requesting party. These five components interact with each other during the three phases as defined in the UMA core specification.
../images/323855_2_En_19_Chapter/323855_2_En_19_Fig6_HTML.jpg
Figure D-6

UMA high-level architecture

UMA 1.0 Phases

The first phase of UMA1 is to protect the resource. The resource owner initiates this phase by introducing the resource servers associated with him or her to a centralized authorization server.

The client initiates the second phase when it wants to access a protected resource. The client talks to the authorization server and obtains the required level of authorization to access the protected resource that’s hosted in the resource server. Finally, in the third phase, the client directly accesses the protected resource.

UMA Phase 1: Protecting a Resource

Resources are owned by the resource owner and may be at different resource servers. Let’s look at an example. Suppose my photos are with Flickr, my calendar is with Google, and my friend list is with Facebook. How can I protect all these resources, which are distributed across different resource servers, with a centralized authorization server? The first step is to introduce the centralized authorization server to Flickr, Google, and Facebook—to all the resource servers. The resource owner must do this. The resource owner can log in to each resource server and provide the authorization server configuration endpoint to each of them. The authorization server must provide its configuration data in JSON format.

The following is a set of sample configuration data related to the authorization server. The data in this JSON format should be understood by any of the resource servers that support UMA. This section digs into the details of each configuration element as you proceed:
{
   "version":"1.0",
   "issuer":"https://auth.server.com",
   "pat_profiles_supported":["bearer"],
   "aat_profiles_supported":["bearer"],
   "rpt_profiles_supported":["bearer"],
   "pat_grant_types_supported":["authorization_code"],
   "aat_grant_types_supported":["authorization_code"],
   "claim_profiles_supported":["openid"],
   "dynamic_client_endpoint":"https://auth.server.com/dyn_client_reg_uri",
   "token_endpoint":"https://auth.server.com/token_uri",
   "user_endpoint":"https://auth.server.com/user_uri",
   "resource_set_registration_endpoint":"https://auth.server.com/rs/rsrc_uri",
   "introspection_endpoint":"https://auth.server.com/rs/status_uri",
   "permission_registration_endpoint":"https://auth.server.com/perm_uri",
   "rpt_endpoint":"https://auth.server.com/rpt",
   "authorization_request_endpoint":"https://auth.server.com/authorize"
}

Once the resource server is introduced to the authorization server via its configuration data endpoint, the resource server can talk to the dynamic client registration (RFC 7591) endpoint (dynamic_client_endpoint) to register it at the authorization server.

The client registration endpoint exposed by the authorization server can be secured or not. It can be secured with OAuth, HTTP Basic authentication, Mutual TLS, or any other security protocol as desired by the authorization server. Even if the Dynamic Client Registration profile (RFC 7591) doesn’t enforce any authentication protocols over the registration endpoint, it must be secured with TLS. If the authorization server decides to allow the endpoint to be public and let anyone be registered, it can do so. To register a client, you have to pass all its metadata to the registration endpoint. Here’s a sample JSON message for client registration:
POST /register HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: authz.server.com
{
   "redirect_uris":["https://client.org/callback","https://client.org/callback2"],
   "token_endpoint_auth_method":"client_secret_basic",
   "grant_types": ["authorization_code" , "implicit"],
   "response_types": ["code" , "token"],
}
A successful client registration results in the following JSON response, which includes the client identifier and the client secret to be used by the resource server:
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache
{
   "client_id":"iuyiSgfgfhffgfh",
   "client_secret": "hkjhkiiu89hknhkjhuyjhk",
   "client_id_issued_at":2343276600,
   "client_secret_expires_at":2503286900,
   "redirect_uris":["https://client.org/callback","https://client.org/callback2"],
   "grant_types": "authorization_code",
   "token_endpoint_auth_method": "client_secret_basic",
}

Note

You aren’t required to use the Dynamic Client Registration API. Resource servers can use any method they prefer to register at the authorization server. The registration at the authorization server is one-time operation, not per resource owner. If a given resource server has already been registered with a given authorization server, then it doesn’t need to register again at the authorization server when the same authorization server is introduced by a different resource owner.

Once the initial resource server registration process is complete, the next step in the first phase is for the resource server to obtain a Protection API token (PAT) to access the Protection API exposed by the authorization server. (You learn more on PAT in the section “Protection API,” later in the appendix.) PAT is issued per resource server, per resource owner. In other words, each resource owner must authorize a PAT so the resource server can use it to protect resources with the centralized authorization server. The authorization server configuration file declares the types of PATs it supports. In the previous example, the authorization server supports OAuth 2.0 bearer tokens:
pat_profiles_supported":["bearer"]
In addition to the PAT token type, the authorization server configuration file also declares the way to obtain the PAT. In this case, it should be via the OAuth 2.0 authorization code grant type. The resource server must initiate an OAuth flow with the authorization code grant type to obtain the PAT in bearer format:
"pat_grant_types_supported":["authorization_code"]

Note

The scope of the PAT token must be http://docs.kantarainitiative.org/uma/scopes/prot.json. This must be included in the scope value of the authorization code grant request.

The following is a sample authorization code grant request to obtain a PAT:
GET /authorize?response_type=code
   &client_id=dsdasDdsdsdsdsdas
   &state=xyz
   &redirect_uri=https://flickr.com/callback
   &scope=http://docs.kantarainitiative.org/uma/scopes/prot.json
HTTP/1.1 Host: auth.server.com
Once the resource server gets the PAT, it can be used to access the Resource Set Registration API exposed by the authorization server, to register a set of resources that needs to be protected by the given authorization server. The endpoint of the Resource Set Registration API is defined under the authorization server configuration file (you learn more about the Resource Set Registration API in the section “Protection API”):
"resource_set_registration_endpoint":"https://auth.server.com/rs/rsrc_uri",

UMA Phase 2: Getting Authorization

According to the UMA specification, phase 2 begins after a failed access attempt by the client. The client tries to access a resource hosted in the resource server and gets an HTTP 403 status code (see Figure D-7). In addition to the 403 response, the resource server includes the endpoint (as_uri) of the corresponding authorization server where the client can obtain a requesting party token (RPT):
HTTP/1.1 403 Forbidden
WWW-Authenticate: UMA realm="my-realm",
                      host_id="photos.flickr.com",
                      as_uri=https://auth.server.com
According to UMA, to access a protected resource, the client must present a valid RPT. (You learn more about RPT in the section “Authorization API.") The RPT endpoint that must be included in the 403 response is declared in the authorization server configuration file:
"rpt_endpoint":"https://auth.server.com/rpt”
Once rejected by the resource server with a 403, the client has to talk to the RPT endpoint of the authorization server. To do so, the client must have an Authorization API token (AAT) . To get an AAT, the client must be registered at the corresponding authorization server. The client can use the OAuth Dynamic Client Registration API or any other way it prefers to register. After it’s registered with the authorization server, the client gets a client key and a client secret. The requesting party can be a different entity from the client. For example, the client can be a mobile application or a web application, whereas the requesting party could be a human user who uses either the mobile application or the web application. The ultimate goal is for the requesting party to access an API owned by a resource owner, hosted in a resource server, via a client application. To achieve this, the requesting party should get an RPT from an authorization server trusted by the resource server. To get an RPT, the requesting party should first get an AAT via the client application. To get an AAT, the client must follow an OAuth grant type supported by the authorization server to issue AATs. That is declared in the authorization server’s configuration file. In this case, the authorization server supports the authorization code grant type to issue AATs:
"aat_grant_types_supported":["authorization_code"]
../images/323855_2_En_19_Chapter/323855_2_En_19_Fig7_HTML.jpg
Figure D-7

The resource server rejects any request without an RPT

Once the client is registered at the authorization server, to get an AAT on behalf of the requesting party, it must initiate the OAuth authorization code grant type flow, with the scope: http://docs.kantarainitiative.org/uma/scopes/authz.json. The following is a sample authorization code grant request to obtain an AAT:
GET /authorize?response_type=code
   &client_id=dsdasDdsdsdsdsdas
   &state=xyz
   &redirect_uri=https://flickr.com/callback
   &scope=http://docs.kantarainitiative.org/uma/scopes/authz.json
HTTP/1.1 Host: auth.server.com

Note

You aren’t required to use the Dynamic Client Registration API. The client can use any method it prefers to register at the authorization server. The registration at the authorization server is one-time operation and not per resource server or per requesting party. If a given client has already been registered with a given authorization server, then it doesn’t need to register again when a different requesting party uses the same authorization server. The AAT is per client per requesting party per authorization server and is independent from the resource server.

Once you have the AAT, upon the 403 response from the resource server, the client can talk to the authorization server’s RPT endpoint and get the corresponding RPT (see Figure D-8). To get an RPT, the client must authenticate with the AAT. In the following example, the AAT is used in the HTTP Authorization header as an OAuth 2.0 bearer token:
POST /rpt HTTP/1.1
Host: as.example.com
Authorization: Bearer GghgjhsuyuE8heweds

Note

The RPT endpoint is defined under the rpt_endpoint attribute of the authorization server’s configuration.

The following shows a sample response from the RPT endpoint of the authorization server. If this is the first issuance of the RPT, it doesn’t have any authorization rights attached. It can only be used as a temporary token to get the “real” RPT:
HTTP/1.1 201 Created
Content-Type: application/json
{
     "rpt": "dsdsJKhkiuiuoiwewjewkej"
}

When the client is in possession of the initial RPT, it can once again try to access the resource. In this case, the RPT goes as an OAuth 2.0 bearer token in the HTTP Authorization header. Now the resource server extracts the RPT from the resource request and talks to the Introspection API exposed by the authorization server. The Introspection API can tell whether the RPT is valid and, if it is, the permissions associated with it. In this case, because you’re still using the initial RPT, there are no permissions associated with it, even though it’s a valid token.

Note

The Introspection API exposed by the authorization server is OAuth 2.0 protected. The resource server must present a valid PAT to access it. The PAT is another bearer token that goes in the HTTP Authorization header.

If the RPT doesn’t have enough permission to access the resource, the resource server talks to the Client Requested Permission Registration API exposed by the authorization server and registers the required set of permissions to access the desired resource. When permission registration is successfully completed, the authorization server returns a permission ticket identifier.

Note

The Client Requested Permission Registration endpoint is defined under the permission_registration_endpoint attribute in the authorization server’s configuration. This endpoint, which is part of the UMA Protection API, is secured with OAuth 2.0. The resource server must present a valid PAT to access the API.

The following is a sample request to the permission registration endpoint of the authorization server. It must include a unique resource_set_id corresponding to the requested resource and the required set of scopes associated with it:
POST /perm_uri HTTP/1.1
Content-Type: application/json
Host: auth.server.com
{
    "resource_set_id": "1122wqwq23398100",
    "scopes": [
        "http://photoz.flickr.com/dev/actions/view",
        "http://photoz.flickr.com/dev/actions/all"
          ]
}
In response to this request, the authorization server generates a permission ticket:
HTTP/1.1 201 Created
Content-Type: application/json
{"ticket": "016f88989-f9b9-11e0-bd6f-0cc66c6004de"}
When the permission ticket is created at the authorization server, the resource server sends the following response to the client:
HTTP/1.1 403 Forbidden
WWW-Authenticate: UMA realm="my-realm",
                  host_id=" photos.flickr.com ",
                  as_uri="https://auth.server.com"
                  error="insufficient_scope"
{"ticket": "016f88989-f9b9-11e0-bd6f-0cc66c6004de"}
Now the client has to get a new RPT with the required set of permissions. Unlike in the previous case, this time the RPT request also includes the ticket attribute from the previous 403 response:
POST /rpt HTTP/1.1
Host: as.example.com
Authorization: Bearer GghgjhsuyuE8heweds
{
      "rpt": "dsdsJKhkiuiuoiwewjewkej",
      "ticket": "016f88989-f9b9-11e0-bd6f-0cc66c6004de"
}

Note

The RPT endpoint of the authorization server is secured with OAuth 2.0. To access the RPT endpoint, the client must use an AAT in the HTTP Authorization header as the OAuth bearer token.

At this point, prior to issuing the new RPT to satisfy the requested set of permissions, the authorization server evaluates the authorization policies set by the resource owner against the client and the requesting party. If the authorization server needs more information regarding the requesting party while evaluating the policies, it can interact directly with the requesting party to gather the required details. Also, if it needs further approval by the resource owner, the authorization server must notify the resource owner and wait for a response. In any of these cases, once the authorization server decides to associate permissions with the RPT, it creates a new RPT and sends it to the client:
HTTP/1.1 201 Created
Content-Type: application/json
{"rpt": "dsdJhkjhkhk879dshkjhkj877979"}
../images/323855_2_En_19_Chapter/323855_2_En_19_Fig8_HTML.jpg
Figure D-8

The client gets an authorized RPT from the authorization server

UMA Phase 3: Accessing the Protected Resource

At the end of phase 2, the client got access to a valid RPT with the required set of permissions. Now the client can use it to access the protected resource. The resource server again uses the Introspection API exposed by the authorization server to check the validity of the RPT. If the token is valid and has the required set of permissions, the corresponding resource is returned to the client.

UMA APIs

UMA defines two main APIs: the Protection API and the Authorization API (see Figure D-9). The Protection API sits between the resource server and the authorization server, and the Authorization API sits between the client and the authorization server. Both APIs are secured with OAuth 2.0. To access the Protection API, the resource server must present a PAT as the bearer token; and to access the Authorization API, the client must present an AAT as the bearer token.
../images/323855_2_En_19_Chapter/323855_2_En_19_Fig9_HTML.jpg
Figure D-9

UMA APIs

Protection API

The Protection API is the interface exposed to the resource server by the authorization server. It consists of three subelements: the OAuth Resource Set Registration endpoint,2 the Client Requested Permission Registration endpoint, and the OAuth Token Introspection (RFC 7662) endpoint.

These three APIs that fall under the Protection API address different concerns. The resource server uses the Resource Set Registration API to publish semantics and discovery properties of its resources to the authorization server. The resource server does this in an ongoing manner. Whenever it finds a resource set that needs to be protected by an external authorization server, it talks to the corresponding Resource Set Registration endpoint to register new resources. This action can be initiated by the resource server itself or by the resource owner. The following example shows a JSON request to the Resource Set Registration API of the authorization server. The value of the name attribute should be human-readable text, and the optional icon_uri can point to any image that represents this resource set. The scope array should list all the scope values required to access the resource set. The type attribute describes the semantics associated with the resource set; the value of this attribute is meaningful only to the resource server and can be used to process the associated resources:
{
  "name": "John’s Family Photos",
  "icon_uri": "http://www.flickr.com/icons/flower.png",
  "scopes": [
       "http://photoz. flickr.com/dev/scopes/view",
       "http://photoz. flickr.com/dev/scopes/all"
   ],
  "type": "http://www. flickr.com/rsets/photoalbum"
}

This JSON message is also known as the resource description. Each UMA authorization server must present a REST API to create (POST), update (PUT), list (GET), and delete (DELETE) resource set descriptions. The resource server can utilize this endpoint either during phase 1 or in an ongoing manner.

The resource server accesses the Client Requested Permission Registration endpoint during phase 2 of UMA flow. The resource server uses this API to inform the authorization server about the level of permissions required for the client to access the desired resource. The resource server uses the Introspection API to check the validity of the RPT.

Authorization API

The Authorization API is the interface between the client and the authorization server. The main responsibility of this API is to issue RPTs.

..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset
3.15.5.183