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

Prerequsites

• Download and install WSO2 Identity Server, which will act as the authorization server. Let’s refer to the WSO2 Identity Server installation location as <IS_HOME> throughout the tutorial.

• Follow the steps below to register the UMA grant type in WSO2 Identity Server.

  1. Open the <IS_HOME>/repository/conf/identity/identity.xml file and add the following configuration under the <SupportedGrantTypes> element:

     <SupportedGrantType> <GrantTypeName>urn:ietf:params:oauth:grant-type:uma-ticket</GrantTypeName> <GrantTypeHandlerImplClass>org.wso2.carbon.identity.oauth.uma.grant.UMA2GrantHandler</GrantTypeHandlerImplClass> <GrantTypeValidatorImplClass>org.wso2.carbon.identity.oauth.uma.grant.GrantValidator</GrantTypeValidatorImplClass> </SupportedGrantType>

  2. Save the changes.

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.

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:

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:

  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:

  curl -v -X POST -H "Authorization:Bearer <PAT>" -H "Content-Type: application/json" -d '{"resource_scope":["view", "download"], "description":"Collection of digital photographs", "icon_uri":"http://www.example.com/icons/flower.png", "name":"Photo Album", "type":"http://www.example.com/rsrcs/photoalbum"}' https://localhost:9443/api/identity/oauth2/uma/resourceregistration/v1.0/resource -k

  You will get a response similar to the following:

  { "resourceId":"3f88c89a-d3b8-4ebb-9567-08e5bb774d3c", "policy_uri":null }

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:

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