Configuring the Resource Management API

This section outlines the administrator configuration required at the Resource Server Adapter to make the Resource Management API functional.

Static Configuration (application.yml)

The following fields in the application.yml of the Resource Server Adapter pertain to the Resource Management API:

Parameter	Description	Default
resourcemanagement.enabled	A boolean which enables or disables the Resource Management API functionality.	false
resourcemanagement.userinfoUrl	The path for which the `related` field should be added to its response as an additional claim. This should be a userinfo response's path on the RSA. See Using the Resource Management API for more information about the `related` field.	/userinfo
resourcemanagement.scope	The scope which is required on the user's access token in order to acquire FPX resources, including the `related` field mentioned above.	fpx_rot

The following snippet shows these configuration properties as they may appear in the application.yml:

...
fpx:
  resourcemanagement:
    enabled: true
    userinfoUrl: /userinfo
    scope: fpx_rot
...

Runtime Configuration (RSA Admin API)

Before you start

Some values shown in the following sections are surrounded by a double set of curly braces, like {{RSA_URI}}. These are environment variables that will change based on the specifics of your deployment. In order to use the Admin API requests shown below, make sure you obtain values for the following variables:

RSA_URI
RSA_ADMIN_URI
RSA_ADMIN_VERSION
RSA_ADMIN_STATIC_TOKEN
AUTH_SERVER_URI

Further information about these environment variables can be found here.

Requests to the following Admin API endpoints are involved in this feature:

/generic-resource
/generic-resource-alias
/generic-resource-alias-scope
/generic-resource-authorization
/generic-resource-authorization-scope

Generic Resource

Admin API Type: generic-resource

A Generic Resource entry defines which resources belonging to users could have other users (delegates) authorized to use them. Defining resources in this table causes them to appear in the response of the RSA's /resources endpoint when retrieved by either the owner, or another user who is authorized to access them (see the generic-resource-authorization section below).

The following attributes are configurable in an Admin API request:

Attribute	Description	Example value	Required
description	A human readable description of the resource for display purposes	"Delegated access to userinfo"	Yes
location	The protected endpoint of the resource at the RSA	{{RSA_URI}}/api/userinfo	Yes
ownerId	The identifier of the user at the real RS who owns this resource	5eed5a1d-4f00-4a1d-a65c-91adf337c05b	Yes
ownerName	A human readable name for the owner	John	Yes
protectionUri	(TBD)		No
resourceId	The identifier of the resource known by the Authorization Server and Wallet Server. This value should match the value of the Wallet Server's RS Resource `identifier` attribute. Further details about that configuration can be found here.	rsa_userinfo_res_id	Yes
type	The type of the resource known by the Authorization Server and Wallet Server. This value must match the value of the Wallet Server's Resource Type `type` attribute. Further details about that configuration can be found here.	https://www.identos.com/resource-definitions/identity-profile-res-def	Yes

Generic Resource Alias

Admin API Type: generic-resource-alias

A Generic Resource Alias entry serves as a link between Generic Resource and Generic Resource Authorization entries. This entry describes the resource being authorized, including which authorization server it is known to, and which Generic Resource is being authorized.

The following attributes are configurable in an Admin API request:

Attribute	Description	Example value	Required
alias	The identifier of the resource known by the Authorization Server and Wallet Server. This value must match the value of the Wallet Server's RS Resource `identifier` attribute. Further details about that configuration can be found here.	rsa_userinfo_res_id	Yes
networkUri	The base url for the authorization server which the resource belongs to, for the case where an RSA may be involved with multiple FPX networks	{{AUTH_SERVER_URI}}	Yes

A Generic Resource Alias entry requires the following relationship:

Relationship	Description	Required
genericResource	The ID of the Generic Resource entry that this alias describes	Yes

Generic Resource Alias Scope

Admin API Type: generic-resource-alias-scope

There also exists the fpx_resource_alias_scope table which defines the scopes which the resource allows for. This table is a simple key-value store table where an alias and its resource can be assigned multiple allowed scopes.

The following attributes are configurable in an Admin API request:

Attribute	Description	Example value	Required
scope	A scope which the resource allows for	read	Yes

A Generic Resource Alias Scope entry requires the following relationship:

Relationship	Description	Required
genericResourceAlias	The ID of the Generic Resource Alias entry that this scope should apply to	Yes

Generic Resource Authorization

Admin API Type: generic-resource-authorization

A Generic Resource Authorization entry defines authorizations to other users (delegates) in order for them to access resources not owned by them.

The following attributes are configurable in an Admin API request:

Attribute	Description	Example value	Required
authorizedParty	The identifier of the user in the underlying resource server who has authorization to access the resource. When trying to access a resource, this value is used to check that the user accessing it is allowed to access it	c0ad2bf5-d755-46c9-a88f-6fd4ea195abf	Yes
authorizedPartyName	The human readable name of the party to access the resource, for display purposes	Alice	No
disabledOn	The timestamp when this authorization was disabled. This value should be null when the authorization is not disabled	2023-04-27 00:00:00	No

A Generic Resource Authorization entry requires the following relationship:

Relationship	Description	Required
genericResourceAlias	The ID of the Generic Resource Alias entry that this Authorization should apply to	Yes

Generic Resource Authorization Scope

Admin API Type: generic-resource-authorization-scope

A Generic Resource Authorization Scope entry defines the scopes which have been authorized for a specific user to access a specific other resource. This is similar to the Generic Resource Alias Scope entry shown above, but the key difference is that instead of defining what scopes are allowed on the owner's resource in general, this defines what scopes the delegate user is specifically authorized to use.

For example, Generic Resource R could have an Authorization A and an Authorization B, which may be assigned to either the same user or different users who are not the owner(s). Generic Resource R has the scopes read, write, and delete. Authorization A has the scope read, while Authorization B has the scopes read and write. Using A would allow you to read the owner's resource only, while using B would allow you to read and write the owner's resource. Neither would allow deletion, but the owner may create an authorization with that scope if needed.

The following attributes are configurable in an Admin API request:

Attribute	Description	Example value	Required
authorizedScope	A scope which is allowed for the related Generic Resource Authorization. Note that this value is not defined by a relationship, but is instead simply a literal string. However, the value must match one of the scopes defined by the Generic Resource Alias Scope entry that the Generic Resource Authorization applies to	read	Yes

A Generic Resource Authorization Scope entry requires the following relationship:

Relationship	Description	Required
genericResourceAuthorization	The ID of the Generic Resource Authorization entry that this scope should apply to	Yes

Sample Requests

Create a Generic Resource

curl -X PATCH '{{RSA_ADMIN_URI}}' \
  --header 'Content-Type: application/vnd.api+json; ext=jsonpatch' \
  --header 'Authorization: {{RSA_ADMIN_STATIC_TOKEN}}' \
  --header 'ApiVersion: {{RSA_ADMIN_VERSION}}' \
  --header 'Accept-Language: en' \
  --data-raw '[
  {
    "op": "add",
    "path": "/generic-resource",
    "value": {
      "type": "generic-resource",
      "id": 1,
      "attributes": {
        "description": "Delegated access to userinfo",
        "location": "{{RSA_URI}}/api/userinfo",
        "ownerId": "5eed5a1d-4f00-4a1d-a65c-91adf337c05b",
        "ownerName": "John",
        "protectionUri": null,
        "resourceId": "rsa_userinfo_res_id",
        "type": "https://www.identos.com/resource-definitions/identity-profile-res-def"
      }
    }
  }
]'

Create a Generic Resource Alias

curl -X PATCH '{{RSA_ADMIN_URI}}' \
  --header 'Content-Type: application/vnd.api+json; ext=jsonpatch' \
  --header 'Authorization: {{RSA_ADMIN_STATIC_TOKEN}}' \
  --header 'ApiVersion: {{RSA_ADMIN_VERSION}}' \
  --header 'Accept-Language: en' \
  --data-raw '[
  {
    "op": "add",
    "path": "/generic-resource-alias",
    "value": {
      "type": "generic-resource-alias",
      "id": 1,
      "attributes": {
        "alias": "rsa_userinfo_res_id",
        "network": "{{AUTH_SERVER_URI}}"
      },
      "relationships": {
        "genericResource": {
          "data": {
            "id": 1,
            "type": "generic-resource"
          }
        }
      }
    }
  }
]'

Create two Generic Resource Alias Scopes

curl -X PATCH '{{RSA_ADMIN_URI}}' \
  --header 'Content-Type: application/vnd.api+json; ext=jsonpatch' \
  --header 'Authorization: {{RSA_ADMIN_STATIC_TOKEN}}' \
  --header 'ApiVersion: {{RSA_ADMIN_VERSION}}' \
  --header 'Accept-Language: en' \
  --data-raw '[
  {
    "op": "add",
    "path": "/generic-resource-alias-scope",
    "value": {
      "type": "generic-resource-alias-scope",
      "id": 1,
      "attributes": {
        "scope": "read"
      },
      "relationships": {
        "genericResourceAlias": {
          "data": {
            "id": 1,
            "type": "generic-resource-alias"
          }
        }
      }
    }
  },
  {
    "op": "add",
    "path": "/generic-resource-alias-scope",
    "value": {
      "type": "generic-resource-alias-scope",
      "id": 2,
      "attributes": {
        "scope": "write"
      },
      "relationships": {
        "genericResourceAlias": {
          "data": {
            "id": 1,
            "type": "generic-resource-alias"
          }
        }
      }
    }
  }
]'

Create a Generic Resource Authorization

curl -X PATCH '{{RSA_ADMIN_URI}}' \
  --header 'Content-Type: application/vnd.api+json; ext=jsonpatch' \
  --header 'Authorization: {{RSA_ADMIN_STATIC_TOKEN}}' \
  --header 'ApiVersion: {{RSA_ADMIN_VERSION}}' \
  --header 'Accept-Language: en' \
  --data-raw '[
  {
    "op": "add",
    "path": "/generic-resource-authorization",
    "value": {
      "type": "generic-resource-authorization",
      "id": 1,
      "attributes": {
        "authorizedParty": "c0ad2bf5-d755-46c9-a88f-6fd4ea195abf",
        "authorizedPartyName": "Alice",
        "disabledOn": null
      },
      "relationships": {
        "genericResourceAlias": {
          "data": {
            "id": 1,
            "type": "generic-resource-alias"
          }
        }
      }
    }
  }
]'

Create a Generic Resource Authorization Scope

curl -X PATCH '{{RSA_ADMIN_URI}}' \
  --header 'Content-Type: application/vnd.api+json; ext=jsonpatch' \
  --header 'Authorization: {{RSA_ADMIN_STATIC_TOKEN}}' \
  --header 'ApiVersion: {{RSA_ADMIN_VERSION}}' \
  --header 'Accept-Language: en' \
  --data-raw '[
  {
    "op": "add",
    "path": "/generic-resource-authorization-scope",
    "value": {
      "type": "generic-resource-authorization-scope",
      "id": 1,
      "attributes": {
        "authorizedScope": "read"
      },
      "relationships": {
        "genericResourceAuthorization": {
          "data": {
            "id": 1,
            "type": "generic-resource-authorization"
          }
        }
      }
    }
  }
]'

Wallet Server Configuration

To support the Resource Management API functionality, the Wallet Server includes one additional configuration apart from the standard configuration that is needed to onboard a Resource Server.

The resourceManagementApiMode configured for a Wallet Server Data Source entry enables this additional functionality.

A Data Source can be configured to use one of two procedures for connecting user Data Source Accounts, depending on the behaviour of the Data Source's Resource Management API.

When a Data Source is set to "DELEGATED_ONLY", the Wallet Server will operate on the assumption that a Data Source Account for the authenticated user has access to all resources registered on the Data Source. The Resource Management API will only be used to learn of and update resources that have been delegated to them by other parties. In this mode, the Wallet Server will automatically look for fields in the userinfo response created by resource delegation at any Resource Server, and attempt to access the /resources endpoint at the Resource Server without disrupting the consent flow if it does not exist.

When a Data Source is set to "ALL_RESOURCES", the Wallet Server will use the Resource Management API to learn of what specific resources the authenticated user owns and has access to, in addition to resources delegated to them. This mode should be used when the Data Source is an RSA which has been updated to return the user's owned resources along with their delegated resources.

In this mode, the resource management API is required, and the DSA connection flow will fail if it cannot be accessed.

An administrator should take care to set the correct mode, as using the ALL_RESOURCES mode with an outdated RSA could result in unexpected behaviour. Specifically, Data Source Accounts would end up with no resources because the Wallet Server expects entries for them to be present in the Resource Management API, but the outdated RSA does not include those entries. The Wallet Server will automatically look for fields in the userinfo response created by resource delegation at any RS, and attempt to access the /resources endpoint at the RS without disrupting the consent flow if it does not exist.

For more information about the standard configuration to add a resource server, please see Configuring a Data Source within the Wallet Server section of this user guide.

Static Configuration (application.yml)​

Runtime Configuration (RSA Admin API)​

Generic Resource​

Generic Resource Alias​

Generic Resource Alias Scope​

Generic Resource Authorization​

Generic Resource Authorization Scope​

Sample Requests​

Create a Generic Resource​

Create a Generic Resource Alias​

Create two Generic Resource Alias Scopes​

Create a Generic Resource Authorization​

Create a Generic Resource Authorization Scope​

Wallet Server Configuration​

Static Configuration (application.yml)

Runtime Configuration (RSA Admin API)

Generic Resource

Generic Resource Alias

Generic Resource Alias Scope

Generic Resource Authorization

Generic Resource Authorization Scope

Sample Requests

Create a Generic Resource

Create a Generic Resource Alias

Create two Generic Resource Alias Scopes

Create a Generic Resource Authorization

Create a Generic Resource Authorization Scope

Wallet Server Configuration