User Managed Access with WSO2 Identity Server

WSO2 Identity Server (WSO2 IS) supports the UMA 2.0 protocol, which allows a resource owner to easily share resources with other requesting parties. This tutorial demonstrates how you can use WSO2 IS as the authorization server to try out UMA for a sample scenario.

This tutorial includes the following sections:

Introduction

To demonstrate the UMA flow using WSO2 IS as the authorization server, let’s consider a sample scenario where Larry (resource owner) wants to share a photo album (resource) on a cloud drive (resource server) with a friend, Sam (requesting party).  Let's assume that Sam uses a mobile app (client) to view Larry’s photo album. Note that Larry wants to allow Sam to only have view permission to this photo album.

Once you try out the tutorial you will understand how to use UMA 2.0 to do the following:

• Outsource authorization.
• Control resources and share resources in a selective manner via a single console (authorization server).

Try out the UMA flow

Now you can follow the instructions in the sections below to try out the UMA flow:

Create the resource owner

Follow the steps below to create a user named Larry who will act as the resource owner:

1. Start WSO2 Identity Server and access the management console. You can sign in using admin as the username and password. For detailed instructions on starting WSO2 Identity Server and accessing the management console, see Running the Product.
2. On the Main tab, click Add under Users and Roles.
3. Click Add New User.

4. Specify the following values to create a new user.

   Domain	PRIMARY
   Username	Larry.
   Password	Larry123
   Confirm password	Larry123

5. Click Next.

6. Select admin.

7. Click Finish. 

Create the requesting party

Follow the steps below to create a user named Sam who will act as the requesting party:

1. On the Main tab, click Add under Users and Roles.
2. Click Add New User.

3. Specify the following values to create a new user:

   Domain	PRIMARY
   Username	sam
   Password	sam123
   Confirm password	sam123

4. Click Finish.

Now that you have the resource owner and requesting party to try out the scenario, next step is to configure one service provider for the resource server and another service provider for the client acting on behalf of the requesting party.

Configure service providers to act as the resource server and client

1. Follow the steps below to configure a service provider for the resource server:
   1. On the Main tab, click Add under Service Providers.
   2. Enter LarrySP as the Service Provider Name and click Register.
   3. Expand Inbound Authentication Configuration, then expand  OAuth/OpenID Connect Configuration, and then click Configure.
   4. Enter https://localhost/callback as the value for the Callback Url.
      
   5. Click Add.
2. Follow the steps below to configuring a service provider for the client acting on behalf of the requesting party:
   
   1. On the Main tab, click Add under Service Providers.
   2. Enter samSP as the Service Provider Name and click Register.
   3. Expand Inbound Authentication Configuration, then expand  OAuth/OpenID Connect Configuration, and then click Configure.
   4. Enter  https://localhost/callback  as the value for the Callback Url. 
      
   5. Click Add.

Obtain the Protection API Access token (PAT)

• Execute the following curl command to obtain the PAT:

  Tip

  • Be sure to replace the <CLIENT_ID> and <CLIENT_SECRET> tags with the values you obtained when you configured the service provider for the client.

  • In this tutorial, the grant type that is used to obtain the PAT is the password grant type. Therefore, you need to pass the resource owners credentials in the curl command. Since you have configured Larry as the resource owner, you need to pass Larry's user name and password in the curl command.

  curl -u <CLIENT_ID>:<CLIENT_SECRET> -k -d "grant_type=password&username=Larry&password=Larry123&scope=uma_protection" -H "Content-Type:application/x-www-form-urlencoded" https://localhost:9443/oauth2/token

  You will get a response similar to the following:

  {
     "access_token":"b8df48ff-feab-3632-b3dc-68ae6b4c62e2",
     "refresh_token":"1037ccad-f45a-38e7-96ad-40c00fbc7ca4",
     "scope":"uma_protection",
     "token_type":"Bearer",
     "expires_in":3600
  }

Register the resource

Now, you need to register the resource. 

• Execute the following curl command to register a resource named Photo Album:

  Tip

  • Make sure to replace the <PAT> tag with the access token you got in the previous section.

  curl -X POST \
    https://localhost:9443/api/identity/oauth2/uma/resourceregistration/v1.0/resource \
    -H 'Authorization: Bearer 64658549-47c1-3b5a-8637-c629f16c4118' \
    -H 'Content-Type: application/json' \
    -d '{
    "resource_scopes": [
      "view",
      "download"
    ],
    "description": "Collection of digital photographs",
    "icon_uri": "http://www.example.com/icons/flower.png",
    "name": "Photo Album 2",
    "type": "http://www.example.com/rsrcs/photoalbum"
  }'

  You will get a response similar to the following:

  {
      "_id": "ceaa6506-1da9-456b-88d8-027797d2e081"
  }

Now you have completed registering the resource.

Next, you need to create and publish an access policy to provide specific users appropriate permission to access the resource. In our sample scenario, the requesting party (i.e., Sam) is only provided view permission to the photo album. Therefore, let's create and publish a policy so that users who have view permission to the album can view the images, whereas those who have download permission can download the images.

Publish a policy

Follow the steps given below to create, register and publish a policy:

1. Sign in to the management console using Larry's credentials., which has Larry as the username and Larry123 as the password:  https://localhost:9443/carbon
2. On the Main tab, go to the Entitlement section and click Policy Administration under PAP.
3. Click Add New Entitlement Policy and then click Write Policy in XML.

4. Copy the following sample policy and paste it on the Source View pane:

   Be sure to replace the {ENTER_YOUR_RESOURCE_ID} tag with the resource ID that you obtained when you registered the resource.

   <Policy xmlns="urn:oasis:names:tc:xacml:3.0:core:schema:wd-17"  PolicyId="UMApolicy" RuleCombiningAlgId="urn:oasis:names:tc:xacml:1.0:rule-combining-algorithm:first-applicable" Version="1.0">
      <Target>
         <AnyOf>
            <AllOf>
               <Match MatchId="urn:oasis:names:tc:xacml:1.0:function:string-equal">
                  <AttributeValue DataType="http://www.w3.org/2001/XMLSchema#string">{ENTER_YOUR_RESOURCE_ID}</AttributeValue>
                  <AttributeDesignator AttributeId="http://wso2.org/identity/identity-resource/resource-id" Category="http://wso2.org/identity/identity-resource" DataType="http://www.w3.org/2001/XMLSchema#string" MustBePresent="true"></AttributeDesignator>
               </Match>
            </AllOf>
         </AnyOf>
      </Target>
      <Rule Effect="Permit" RuleId="permit_for_username">
         <Target>
            <AnyOf>
               <AllOf>
                  <Match MatchId="urn:oasis:names:tc:xacml:1.0:function:string-equal">
                     <AttributeValue DataType="http://www.w3.org/2001/XMLSchema#string">sam</AttributeValue>
                     <AttributeDesignator AttributeId="http://wso2.org/identity/user/username" Category="http://wso2.org/identity/user" DataType="http://www.w3.org/2001/XMLSchema#string" MustBePresent="false"></AttributeDesignator>
                  </Match>
               </AllOf>
            </AnyOf>
         </Target>
         <Condition>
            <Apply FunctionId="urn:oasis:names:tc:xacml:1.0:function:string-at-least-one-member-of">
               <Apply FunctionId="urn:oasis:names:tc:xacml:1.0:function:string-bag">
                  <AttributeValue DataType="http://www.w3.org/2001/XMLSchema#string">view</AttributeValue>
                  <AttributeValue DataType="http://www.w3.org/2001/XMLSchema#string">download</AttributeValue>
               </Apply>
               <AttributeDesignator AttributeId="http://wso2.org/identity/identity-action/action-name" Category="http://wso2.org/identity/identity-action" DataType="http://www.w3.org/2001/XMLSchema#string" MustBePresent="true"></AttributeDesignator>
            </Apply>
         </Condition>
      </Rule>
      <Rule Effect="Deny" RuleId="Deny_all"></Rule>
   </Policy>

5. Save the policy. You will see the new policy that you created listed in the Policy Administration page. 
   

6. Select the policy and click Publish To My PDP. This displays the Publish Policy page.

7. Click Publish. This displays a message for confirmation to publish the policy. 
8. Click Yes. This publishes the policy. If you want to view the published policy, click Policy View under PDP.
   

Obtain a permission ticket

The permission endpoint allows the resource server to request permission when a client makes a resource request without a token or if the request contains an invalid token.

The request can contain one or more permission values by having multiple resources and the relevant scopes of a resource owner. The request used in this tutorial contains a single permission.

• Execute the following curl command to obtain the permission ticket. 

  • Make sure to replace the <PAT> tag with the access token you got in the previous section.
  • Replace the <RESOURCE_ID> tag with the ID you got when registering the resource.

  curl -X POST https://localhost:9443/api/identity/oauth2/uma/permission/v1.0/permission -H 'authorization: Bearer <PAT>' -H "Content-Type: application/json" -d '[{"resource_id":"<RESOURCE_ID>","resource_scopes":["view"]}]' -k

  
  You will get a response similar to the following:

  {"ticket":"97f476f2-72d0-4540-aa08-a4784bd2053e"}

 <Introspection>
    <EnableDataProviders>true</EnableDataProviders>
 </Introspection>

{
  "nbf": 1553411123,
  "active": true,
  "token_type": "Bearer",
  "exp": 1553414723,
  "iat": 1553411123,
  "client_id": "JfTSiJ24gh8sYHTQVuOl5RoftkAa",
  "username": "oliver.uma.demo"
}