User Managed Access UMA Resource Server

The User-Managed Access (UMA) 2.0 protocol is a secure solution for person-to-person resource sharing. Access Manager provides UMA 2.0 Authorization Server capabilities. A solution requires integration of the Authorization Server with a Resource Server. Resource Server functionality may be provided by updating any existing service or by adding a new service. This is a Resource Server "reference implementation" that can be used as an example of one way a Resource Server could be implemented.

Project Readme

frdp-uma-resource-server

ForgeRock Demonstration Platform : UMA Resource Server : A deployable web service that provides REST / JSON operations for the User Managed Access (UMA) 2.0 Resource Server (RS) functionality. This service is implemented using the Java JAX-RS/Jersey REST API and MongoDB for document persistance. This service also leverages the ForgeRock Access Manager for the UMA 2.0 Authorization Server (AS) functionality.

overview image

git clone https://github.com/ForgeRock/frdp-uma-resource-server.git

Disclaimer

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

License

MIT

Reference

Requirements

The following items must be installed:

  1. Apache Maven (tested with 3.5.x, 3.6.x)
  2. Java Development Kit 8
  3. MongoDB (tested with 3.2)
  4. Apache Tomcat (tested with Tomcat 8.5.x)
  5. ForgeRock Access Manager (tested with 6.0, 6.5)

Build

Prerequisite:

The following items must be completed, in the following order:

  1. frdp-framework ... clone / download then install using Maven (mvn)
  2. frdp-dao-mongo ... clone / download then install using Maven (mvn)
  3. frdp-content-server ... clone / download then install using Maven (mvn)
  4. frdp-dao-rest ... clone / download then install using Maven (mvn)

Clean, Compile, Install:

Run Maven (mvn) processes to clean, compile and package the war file:

mvn clean compile package

The package process creates a deployable war file, in the current directory: ./target/resource-server.war:

ls -la ./target
total 12232
drwxrwxr-x. 5 forgerock forgerock       89 Mar 26 17:29 .
drwxrwxr-x. 7 forgerock forgerock     4096 Mar 26 17:29 ..
drwxrwxr-x. 3 forgerock forgerock       16 Mar 26 17:29 classes
drwxrwxr-x. 2 forgerock forgerock       27 Mar 26 17:29 maven-archiver
drwxrwxr-x. 4 forgerock forgerock       95 Mar 26 17:29 resource-server
-rw-rw-r--. 1 forgerock forgerock 12519090 Mar 26 17:29 resource-server.war

Settings

The procedures in this document will use the following settings. You will need to change some of these settings to match your test environment.

Technology Category Name Value
MongoDB
Default
Password: password
Port: 27017
Tomcat
Access Manager
HTTP Port: 18080
HTTPS Port: 18443
Applications
HTTP Port: 38080
HTTPS Port: 38443
Access Manager
Admin User
User Id: amadmin
Password: password
OAuth Client: Resource Server
Client Id: UMA-Resource-Server
Client Secret: password
OAuth Client: Requesting Party
Client Id: UMA-RqP-Client
Client Secret: password
User: Resource Owner
User Id: dcrane
Password: password
User: Requesting Party
User Id: bjensen
Password: password

Configure MongoDB

The MongoDB object database needs to be configured for the resources and credentials collections in the resource-server database.

  1. Access MongoDB system

    ssh root@hostname

  2. Connect as the "root" MongoDB user to create the database and collections

    mongo --username "root" --password "<ROOT_PASSWORD>" --authenticationDatabase "admin" admin

  3. We need to do some database initialization ... Specify the database name: resource-server. Drop database if it already exists. Create an admin user, remove first, for the database: resourceadmin. Create two collections: credentials and resources. Quit MongoDB.

    use resource-server;
    db.dropDatabase();
    db.dropUser("resourceadmin");
    db.createUser({user:"resourceadmin",pwd:"password",roles:["readWrite","dbAdmin"]});
    db.createCollection("credentials");
    db.createCollection("resources");
    quit();

  4. Connect as the "resourceadmin" user for the resource-server database.

    mongo --username "resourceadmin" --password "password" --authenticationDatabase "resource-server" resource-server

  5. Create indexes for both the resources and credentials collections. Insert test documents into both collections. Read the documents from both collections. Quit MongoDB.

    db.resources.createIndex({"uid":1});
    db.resources.createIndex({"data.owner":1});
    db.resources.createIndex({"data.register":1});
    db.credentials.createIndex({"uid":1});
    db.credentials.createIndex({"data.owner":1}, {unique: true});
    db.resources.insert({"comment": "This is a test document"});
    db.credentials.insert({"comment": "This is a test document"});
    db.resources.find();
    db.resources.find().pretty();
    db.credentials.find();
    db.credentials.find().pretty();
    quit();

Configure Access Manager

The ForgeRock Access Manager (6.0.x, 6.5.x) needs to be configured to support the UMA 2.0 Authorization Server (AS) functionality. The ForgeRock Access Manager Policy APIs and OAuth 2.0 functionality will also configured. See the Access Manager 6.5 User Managed Access (UMA) 2.0 Guide for installation details.

These procedures will create and configure:

  • OAuth2 Provider
  • UMA Provider
  • OAuth 2.0 Client Agent, application used by the Requesting Party (RqP)
  • OAuth 2.0 Resource Server (RS)
  • Resource Owner (RO), the user, dcrane, that owns the resources
  • Requesting Party (RqP), the user, bjensen, that requests and gets access to the resources

See the Access Manager 6.5 UMA Setup Procedures documentation for details

Log into the Access Manager admin console as amadmin

Create Services

This procedure will create two Services:

  • OAuth2 Provider
  • UMA Provider

NOTICE: If you are using an existing Access Manager installation and these Providers exist, they will be replaced.

  1. From Top Menu Bar, select Realms > Top Level Realm
  2. From panel, select Configure OAuth Provider
  3. From panel, select Configure User Managed Access
  4. Check (enable) Issue Refresh Tokens
  5. Check (enable) ISsue Refresh Tokens on Refreshing Access Tokens
  6. Click Create
  7. From the dialog window, click OK

Create OAuth 2.0 UMA Requesting Party (RqP) Client

This procedure creates an OAuth 2.0 client for the Requesting Party (RqP) application which will access resources.

  1. From Top Menu Bar, select Realms > Top Level Realm
  2. From the Left Menu, select Applications > OAuth 2.0
  3. Select Clients Tab
  4. Click + Add Client
  5. Set Client ID to UMA-RqP-Client
  6. Set Client Secret password
  7. Set Redirection URIs _PROTOCOL_://_HOSTNAME_:_PORT_/resource-server
  8. Set Scopes read and openid (press Enter after each item)
  9. Click Create
  10. Select Advanced Tab
  11. Set Display Name to UMA RqP
  12. Set Display Description to User Managed Access (UMA) Requesting Party Client
  13. Set Grant Type to include: Authorization Code and UMA (press Enter after each item)
  14. Click Save Changes

Create OAuth 2.0 UMA Resource Server (RS) Client

This procedure creates an OAuth 2.0 client for the Resource Server (RS) application.

  1. From Top Menu Bar, select Realms > Top Level Realm
  2. From the Left Menu, select Applications, Select OAuth 2.0
  3. Select Clients Tab
  4. Click + Add Client
  5. Set Client ID to UMA-Resource-Server
  6. Set Client Secret password
  7. Set Redirection URIs _PROTOCOL_://_HOSTNAME_:_PORT_/resource-server
  8. Set Scopes uma_protection (press Enter after each item)
  9. Click Create
  10. Select Core Tab
  11. Set Refresh Token Lifetime (seconds) to -1
  12. Click Save Changes
  13. Select Advanced Tab
  14. Set Display Name to UMA RS
  15. Set Display Description to User Managed Access (UMA) Resource Server
  16. Set Grant Type to include: Authorization Code and Refresh Token
  17. Click Save Changes

Create Resource Owner (RO) User

  1. From Top Menu Bar, select Realms > Top Level Realm
  2. From the Left Menu, select Identities
  3. Select Identities Tab
  4. Click + Add Identity
  5. Set User ID to dcrane
  6. Set Password to password
  7. Click Create
  8. Set First Name to Danny
  9. Set Last Name to Crane
  10. Set Full Name to Danny Crane - Resource Owner
  11. Set User Status to Active
  12. Click Save Changes

Create Requesting Party (RqP) User

  1. From Top Menu Bar, select Realms > Top Level Realm
  2. From the Left Menu, select Identities
  3. Select Identities Tab
  4. Click + Add Identity
  5. Set User ID to bjensen
  6. Set Password to password
  7. Click Create
  8. Set First Name to Barb
  9. Set Last Name to Jensen
  10. Set Full Name to Barb Jensen - Requesting Party
  11. Set User Status to Active
  12. Click Save Changes

Install Resource Server

This example deploys the resource-server.war file to an Apache Tomcat 8.x environment.

Deploy war file

Copy the resource-server.war file to the webapps folder in the Tomcat server installation. The running Tomcat server will automatically unpack the war file.

cp ./target/resource-server.war TOMCAT_INSTALLATION/webapps

Configure resource-server.json

The deployed Resource Server application needs to be configured. Edit the resource-server.json file and change / check the values.

cd TOMCAT_INSTALLATION/webapps/resource-server/WEB-INF/config
vi resource-server.json

Edit the following sections of the JSON file:

Resource Server (RS): No SQL Database (MongoDB):

JSON Object ... rs.nosql:

{
   "nosql": {
      "comment": "No SQL Database (MongoDB)",
      "host": "mongo.example.com",
      "port": "27017",
      "authen": {
         "database": "resource-server",
         "user": "resourceadmin",
         "password": "password"
      }
   }
}
  • Set host: Fully Qualified Domain Name (FQDN) of installation
  • Set port: Port for MongoDB service, default is 27017
  • Set password: Password for MongoDB resource-server, resourceadmin user

Resource Server (RS): OAuth 2.0 Client:

JSON Object ... rs.oauth2.client

{
   "client": {
      "id": "UMA-Resource-Server",
      "secret": "password",
      "redirect": "https://uma.example.com:443/resource-server"
   }
}
  • Set secret: Password for the OAuth 2.0 Client: password
  • Set redirect: This value MUST match the redirect when configuring the OAuth 2.0 client

NOTICE: The client attributes MUST match the values used when the Access Manager OAuth 2.0 Client UMA-Resource-Server configuration:

  • id
  • secret
  • redirect

Authorization Server (AS) Connection:

JSON Object ... as.connect

{
   "connect": {
      "protocol": "https",
      "host": "as.example.com",
      "port": "443",
      "path": "openam"
   }
}
  • Set protocol: http or https
  • Set host: Fully Qualified Domain Name (FQDN) of installation
  • Set port: Port that has the Access Manager installed: 443

Authorization Server (AS) admin credentials:

JSON Object ... as.admin

{
   "admin": {
      "user": "amadmin",
      "password": "password"
   }
}
  • Set password: Password for the Access Manager administrator account: password

Configure content-services.json

The deployed Resource Server application needs to be configured. The Resource Server uses a separate file for the configuration of content services. These instruction will cover the configuration of the default Content Service. Edit the content-services.json file and change / check the values.

There's an array of services we will change the service that has an id value of default

JSON Object ... operations.create

{
   "create": {
      "comment": "Use 'uri' attribute and input 'data' to CREATE external content",
      "action": "post",
      "uri": "https://cs.example.com:443/content-server/rest/content-server/content"
   }
}
  • Set uri: This is the full FQDN path for where content is created, via HTTP POST

Note:

Restart the Tomcat server running the Resource Server (resource-server)

Testing

The following Use Cases will test the UMA 2.0 capabilities and "value add" features of the Resource Server:

Actor Use Case Category Description
Resource Owner
Resources UMA 2.0 Create, Read, Update, Delete resources (meta, content, registration, policies).
People Value Add Who has access to my resources.
Requests Value Add Accessing a resource, without permission, will generate a access request.
Requesting Party
Resources UMA 2.0 Accessing shared resources
Shared With Me Value Add What resource do I currently have access to
Discovery Value Add What resources are discoverable
Revoke Access Value Add RqP initiated access revocation

Use the provided Postman collections to test the Use Cases:

Ready-2-Run environment

If you want to get started quickly with UMA ... take a look this Containers for UMA GitHub project. It uses Docker and Docker-Compose to assemble this project in about 5 minutes. There's a YouTube video of the project which covers the setup procedure, building of containers, and running of the use cases.

Project Information
Unsupported
Unverified
openam
authorization
all
sfehrman
here
here