Project: Resource Server as the Resource Owner - ForgeRock/frdp-uma-resource-server Wiki

Why

A traditional deployment of an UMA solution has an authenticated "human user" perform Resource Owner (RO) operations. These operations include the registration and maintenance of UMA resources. There are situations where a "human user" Resource Owner is not able to execute operations. This project evaluates the concept of having the Resource Server (RS) act as a Resource Owner (RO). The list below outlines some of the issues and opportunities that could be addressed by this project:

How

The Resource Server (RS)

The Authorization Server (AS)

Registration options

A solution could support a registrar that is either the authenticated username or the ROSA on a per resource basis. A deployment of the Resource Server could be configured to "default" the registrar value to either use the authenticated username with _self_ or a rosa account. The registrar can be explicitly set (override) via an API flag: registrar=_self_ or registrar={rosa_id}.

Phased development

What

Definitions:

Terminology Quantity Type Description
Owner 1 String Identifier for the owner of the resource. Will eventually need to be authenticated by the Authorization Server (AS) if used to perform management operations on the resource. The value is either set to the username of the authenticated user or can be set to another non-empty value by an administrator.
Registrar 0,1 String Identifier for the "account" that is used to register a UMA resource and manage policies. The value is either the authenticated username or a valid Resource Owner Service Account (ROSA). This is the identifier that will be associated with the UMA Resource Owner and the UMA Protection API Token (PAT). If the value is empty, the resource is not an UMA registered resource (there is no registration GUID value).
Subject 0, 1, + Array An array of Strings containing the unique identifier of subjects. Subjects are for whom the resource is about. May be empty, have one or more values. A value should be a username that can be used for authentication. Used for finding resource that "are about" a specific subject.
Username 1 String A unique identifier for a "user" that has been authenticated. Authentication can be provided by a SSO session or OAuth/OIDC token

This project would have the following changes / features:

The use of a Resource Owner Service Account (ROSA) to manage a resource has the following "pros" and "cons":

The project involves the following enhancements / features

Resource Server

The Resource Sever will have a new configuration option to set the default registrar id to either a rosa account or _self_ authenticated username. The registrar determines how UMA resources are registered to the Authorization Server (AS) and how policies are managed. This includes the following resource management operations:

Id Description Resource Record
_self_ The UMA registered owner will be the authenticated (SSO Token) username. The owner attribute will be the SSO Token username. The registrar attribute will be the SSO Token username.
rosa account The UMA registered owner will be a Resource Server Service Account (ROSA) account id. The owner attribute will be the SSO Token username. The registrar attribute will be the ROSA account id. An administrator operation can set the owner attribute to a different non-empty value.

Configuration change:

The Resource Server has an existing JSON file, resource-server.json.

Extend the rs Object to contain a new registrar Object. The default attribute defines how resources will be managed ... by either a end-user's username or by the Resource Owner Service Account (ROSA).

Attribute Required Value Description
id true _self_, rosa account id For _self_, the authenticated username is used for the PAT, registration, policies. For rosa account id, the ROSA is used for the PAT, registration, policies
accounts.id true "default_rosa" Authenticated proxy account identifier for ROSA
accounts.password true "password" Password value for the proxy account ROSA

Example resource-server.json for setting registrar mode to "username" as the default:

"rs": {
  ...
  "registrar": {
    "id": "_self_",
    ...
  },
  ...
}

Example resource-server.json for setting registrar mode to "rosa" as the default:

{
  "rs": {
    ...,
    "registrar": {
      "id": "default_rosa",
      "accounts": [
        {
          "id": "default_rosa",
          "password": ""
        },
        {
          "id": "org_rosa",
          "password": ""
        }
      ]
    },
    ...
  },
  ...
}

Extend the rs Object to contain a "admin" account. The "admin" account is used to perform REST API operations when there is no authenticate "owner".

Example resource-server.json for the Resource Server admin account:

"rs": {
  ...
  "admin": {
    "id": "rsadmin",
    "password": "password"
  },
  ...
}

Resource document change:

Add support for the registrar String attribute and the subject Array of Strings.

The documents stored in the resources collection will need to be updated to support these features.

Current Resource Server document for a resource:

{
  "uid": "",
  "data": {
    "owner": "",
    "access": "",
    "meta": { ... },
    "content": { ... },
    "register": ""
  },
  "timestamps": { ... }
}

Proposed Resource Server document for a resource:

{
  "uid": "",
  "data": {
    "owner": "",
    "access": "",
    "registrar": "",
    "rosa": true | false,
    "subject": [ "" ],      
    "meta": { ... },
    "content": { ... },
    "register": ""
  },
  "timestamps": { ... }
}

REST API changes

The APIs will support SSO session tokens that are authenticated with the rsadmin "admin" account in addition to a real end-user's SSO session username. See the following conditions for SSO session tokens.

SSO Session Registrar Owner REST API calls
User _self_ or rosa username Can ONLY create, read, update, delete records for the username. Can override the default registrar mode.
Admin _self_ or rosa username Can create, read, update, delete ANY record. Can override the owner attribute value, but the owner attribute can not be empty. Can override the default registrar mode.
Admin rosa non-empty value Can create, read, update, delete ANY record. The ability to override the username is only allowed with registrar mode set to rosa

The "Manage" API /manage provides the following new capabilities:

Implementation changes

/manage

This interface (REST end point) is used to manage the life-cycle of resources by the traditional UMA Resource Owner (RO). It is used by the "end user" account (the owner) to manage their own resources, as defined by the resource record's owner attribute. It is also be used the "admin" account to manage any resource.

Method URI Allowed Params Description
POST /manage/resources registrar=_self_ or {rosa_id}, owner={username} Create a new resource. All users can set the registrar. Only an "admin" user can set the owner, if registrar is a "{rosa_id}" account
GET /manage/resources Get the collection of resource identifiers where the authenticated user is the owner of a resource.
GET /manage/resources/{id} Get the resource details: meta, content, register, policy. The authenticated user must be the owner or an "admin" account.
PUT /manage/resources/{id} owner={username} Update an existing resource. Can change the owner of a resource to a non-empty value. The current "owner" of a resource can change the owner to another value. An "admin" user can change the owner for any resource.
DELETE /manage/resources/{id} Delete the resource. The "owner" can only delete their own resources. An "admin" user can delete any resource.
PUT /manage/resources/{id}/register registrar=_self_ or {rosa_id} Change the "UMA registration" data of an existing resource. NOTE: Can only use the registrar parameter if the resource is not currently registered.

/share

This interface (REST end point) is used to access a resource by the traditional UMA Requesting Party (RqP). Is is used to "discover" resources associated to certain owners. Get a collection of resource that are currently being shared to the Requesting Party.