Project: Resource Server as the Resource Owner - ForgeRock/frdp-uma-resource-server GitHub 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:

  • An organization may have resources that are not "owned" by a specific / unique (human) owner
  • The resources are owned or managed by an organization
  • There may be a need to change the owner of a resource
  • Need for "admin" access to perform management tasks for resources
  • Complexity of managing tokens, Protection API Token (PAT)

How

The Resource Server (RS)

  • A Resource Owner Service Account (ROSA) could be used by the Resource Server (RS) for UMA registration and policy operations
  • The ROSA authenticates to the Authorization Server (AS) and generates / manages a UMA PAT
  • Resource management operations (create, register, update, share, delete) can be implemented by the ROSA
  • The ROSA would create and maintain Authorization Server (AS) ForgeRock Access Manager policies
  • The Resource Server (RS) resource record would be updated to:
    • contain information about the ROSA, via a new registrar attribute
    • optionally maintain subject(s) for whom the resource is about
  • Configuration would be extended to support registrar and subjects capabilities
  • Each resource can have the registrar set to either the authenticate username or the ROSA
  • Extend the manage API to support the registrar and subject capabilities

The Authorization Server (AS)

  • UMA registration uses the registrar which is either the authenticated username or the Resource Owner Service Account (ROSA)
  • Policies are managed by the registrar ... which is either an authenticated username or the Resource Owner Service Account (ROSA)
  • With regards to the ForgeRock Access Manager, access requests generated by a failed access attempt are assigned to the registrar

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

  • System wide setting for the following:
    • Default registrar id: use a ROSA (account id) or the authenticated username (_self_) for registration
  • Provide an API option to set the registrar and owner parameters
  • Admin accounts would be enabled to perform resource management via automated / proxy systems
  • After a resource has been "registered" (UMA Resource registration), the registrar can not be changed.

The following table outlines the possible UMA registration options:

Owner Registrar Mode Implementation
not set not set Default If the default configuration is authenticated, this is an error (username must be set). If the default configuration is rosa, the UMA Registration process will use the ROSA. Only administrators of the Resource Server can make changes to the resource.
authen username not set or _self_ Traditional / Legacy A PAT will be needed for the authenticated user. The UMA registration process will use the authenticated user as the UMA Owner. Only the authenticated user can make changes to the resource.
not set rosa_id ROSA The Resource Owner Service Account (ROSA) is used for the UMA registration process. Only administrators of the Resource Server can make changes to the resource.
authen username rosa_id ROSA The Resource Owner Service Account (ROSA) is used for the UMA registration process. The username value is set in the resource record owner attribute. Only administrators of the Resource Server can make changes to the resource.

Phased development

  • Change MongoDB document format:
    • Add registrar attribute (String) to the record object
    • Add subject attribute (String Array) to the record object
    • Add rosa attribute (Boolean) to indicate if the registrar value is a ROSA
  • Implement configuration of Resource Owner Service Account (ROSA)
    • Global default for registrar id, either a rosa id or _self_
    • Configuration of the service account
    • Resource management: create, register, policy, update, delete
    • Discovery, getting resources that are "discoverable" for a given owner
    • Shared-With-Me, Requesting Party being able to access that have already been shared to them
    • Request management, failed access attempts generated "access requests", needs to be approved by an "effective" owner
  • Allow use of either registrar mode on a per resource basis
    • REST API calls can explicitly set the registrar and username parameters.

What

Definitions:

Terminology Quantity Type Description
Owner 0,1 String Identifier for the owner of the resource. The value is set to a username of an authenticated user. If the value is empty, the resource is considered "owned" by the organization.
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 a 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:

  • A Resource Owner Service Account (ROSA) may be used by the Resource Server to manage resources.
    • Credentials for the Resource Owner Service Account (ROSA) are accessible by the Resource Server.
    • Different Resource Owner Service Accounts could be used.
  • Authorization Server (AS) resources can be registered by the Resource Owner Service Account (ROSA), or by the authenticated user.
  • The Resource Server's metadata, for resources, would be enhanced:
    • If ROSA is used, store ROSA identifier in registrar attribute
    • Else store username identifier in the owner and registrar attributes
  • Saving of a resource's subject(s)
  • The owner can be changed ONLY if the registrar is a ROSA account
  • New array of subject strings. Could be used for searching / reporting

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

  • Pros:
    • Management of the Protection API Token (PAT) can be completely controlled by the Resource Server
    • Ability to create policy "on behalf" of another user
    • Setting / changing the owner attribute
  • Cons:
    • Authorization Server does not know who the "human" UMA owner is
    • Real resource owner(s) would not be able to manage resources through the Authorization Server (AS) User Interfaces or APIs, ForgeRock Access Manager
    • Access Requests (from failed Requesting Party flow) are generated for the "UMA registered" owner, in this case the Resource Owner Service Account (ROSA). Would need a way for the "effective" owner to manage requests for access.

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:

  • Creation
  • Registration (UMA)
  • Update (meta data attributes)
  • Policy management
  • Delete
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": "",
    "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:

  • Change owner attribute:
    • Can only be done by the "admin" account
    • The registrar MUST be set to a rosa account, for the given resource
    • The owner value can not be empty. The value should be an existing (or future) valid username that can authenticate.
  • Add, Change, Delete subject attribute:
    • Set the value to an Array of strings.
    • The array values should be non-empty strings that represent usernames that can authenticate.

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.