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
- contain information about the ROSA, via a new
- Configuration would be extended to support
registrar
andsubjects
capabilities - Each resource can have the
registrar
set to either the authenticateusername
or the ROSA - Extend the
manage
API to support theregistrar
andsubject
capabilities
The Authorization Server (AS)
- UMA registration uses the
registrar
which is either the authenticatedusername
or the Resource Owner Service Account (ROSA) - Policies are managed by the
registrar
... which is either an authenticatedusername
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
andowner
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
- Add
- 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
andusername
parameters.
- REST API calls can explicitly set the
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
andregistrar
attributes
- If ROSA is used, store ROSA identifier in
- Saving of a resource's subject(s)
- The
owner
can be changed ONLY if theregistrar
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.