Configuring Resource Definitions

Scope and Audience

This section is meant for an administrator of an FPX network and covers how to register a new Resource Definition or update an existing one in an FPX environment through the Admin API.

Required Reference

The reader of this document should be familiar with the architecture and terminology associated with the FPX specification. This specification extends the UMA 2.0 specification by enabling privacy preservation and governable network actors.

If you are unfamiliar with Resource Definitions or Scopes, refer to the Glossary and the Partners section of the guide for more information before trying to add a resource definition.

Overview

Resource Definitions represent generic resource types which may be protected by an FPX network. Examples may be FHIR resources, standard banking APIs, or something as simple as a home address.

Each Resource Definition will have a unique Type, which is a URL that defines the specification for the format of this resource as well as how to use it. Resource Servers can offer a concrete version of a Resource Definition by registering a Resource against that Resource Type.
Resource Definitions must have a set of Scopes that may be allowed by Resource Servers and requested by Clients. If a scope does not exist on a Resource Definition, Clients may not request that scope through the FPX network.

Configuring Resource Definitions and Scopes via API

Resource Definition and Scope configuration at the Authorization Server can be done directly through the API.

Before you start

Make sure you obtain the following valid parameters from the Helm chart:

• AS_URI
• AS_ADMIN_URI
• AS_ADMIN_STATIC_TOKEN

Further instructions can be found here

Overview

A resource in an FPX network is composed of the following data type (Ordered by the creation time from old to latest)

1. scope
2. resource_definition

Type: "scope"

Scopes that clients/resource servers may be allowed to request/provide

Attribute	Description	Example Value	Required	Localizable
name	Scope name.	"Read"	Yes	No
description	Description of the scope.	"Allows for read access"	No	Yes
iconUri	External link to icon.	"https://google.ca/img"	No	Yes

Type: "resource-definition"

Note

The admin api allows scope to be null. In practice, it MUST be valid data

Attribute	Description	Example Value	Required	Localizable
maxPermissionDuration	Duration (in milliseconds) that this resource is accessible to a client	3000000	Yes	No
name	Readable (UI Friendly) name of the resource	"Identify Profile"	Yes	Yes
resourceId	Unique string identifier of the resource	identity-profile-res-def	Yes	No
description	Description of the resource	User identity profile which provides basic information such as email	No	Yes
type	External reference that describe the resource type. Must be unique	https://www.identos.com/resource-definitions/identity-profile-res-def	Yes	No
iconUri	External link to icon	"https://google.ca/img"	No	No

Relationship	Description	Required
scope	Scope previously created. There may be zero scopes.	No

Create Resource Definition - All in one

The following request will create two scopes, "read" and "write", and two resource definitions.

curl --location -g --request PATCH '{{AS_ADMIN_URI}}' \
--header 'Content-Type: application/vnd.api+json; ext=jsonpatch' \
--header 'Authorization: {{AS_ADMIN_STATIC_TOKEN}}' \
--header 'ApiVersion: v1.0' \
--header 'Accept-Language: en' \
--data-raw '[
    {
        "op": "add",
        "path": "/scope",
        "value": {
            "type": "scope",
            "id": 1,
            "attributes": {
                "description": "Read value",
                "name": "read",
                "iconUri": null,
                "dType": "Scope"
            }
        }
    },
    {
        "op": "add",
        "path": "/scope",
        "value": {
            "type": "scope",
            "id": 2,
            "attributes": {
                "description": "write value",
                "name": "write",
                "iconUri": null,
                "dType": "Scope"
            }
        }
    },
    {
        "op": "add",
        "path": "/resource-definition",
        "value": {
            "type": "resource-definition",
            "id": 1,
            "attributes": {
                "maxPermissionDuration": 3000000000,
                "name": "English name",
                "resourceId": "identity-profile-res-def",
                "type": "https://www.identos.com/resource-definitions/identity-profile-res-def",
                "description": "English description"
            },
            "relationships": {
                "scopes": {
                    "data": [
                        {
                            "id": 1,
                            "type": "scope"
                        },
                        {
                            "id": 2,
                            "type": "scope"
                        }
                    ]
                }
            }
        }
    },
    {
        "op": "add",
        "path": "/resource-definition",
        "value": {
            "type": "resource-definition",
            "id": "2",
            "attributes": {
                "maxPermissionDuration": 3000000000,
                "name": "Health record english name",
                "resourceId": "health-record-res-def",
                "type": "https://www.identos.com/resource-definitions/health-record-res-def",
                "description": "It is the health record of each individual"
            },
            "relationships": {
                "scopes": {
                    "data": [
                        {
                            "id": 1,
                            "type": "scope"
                        },
                        {
                            "id": 2,
                            "type": "scope"
                        }
                    ]
                }
            }
        }
    }
]'

Get Resource Definition

curl --location -g --request GET '{{AS_ADMIN_URI}}/resource-definition/1' \
--header 'Content-Type: application/vnd.api+json' \
--header 'ApiVersion: v1.0' \
--header 'Authorization: {{AS_ADMIN_STATIC_TOKEN}}' \
--header 'Accept-Language: en'

Get All Resource Definitions

curl --location -g --request GET '{{AS_ADMIN_URI}}/resource-definition' \
--header 'Content-Type: application/vnd.api+json' \
--header 'ApiVersion: v1.0' \
--header 'Authorization: {{AS_ADMIN_STATIC_TOKEN}}' \
--header 'Accept-Language: en'

Get Scope

curl --location -g --request GET '{{AS_ADMIN_URI}}/scope/1' \
--header 'Content-Type: application/vnd.api+json' \
--header 'ApiVersion: v1.0' \
--header 'Authorization: {{AS_ADMIN_STATIC_TOKEN}}' \
--header 'Accept-Language: en'

Update Resource Definition - All in one

WARNING

Because Resource Definitions can be integral to defining existing resources, removing Scopes or changing Types can make existing resources unusable or incorrect. Examples of when it might make sense to update these fields for a Resource Definition:

• The URL defining the specification for this type has been changed.
• A new Scope is required to onboard a new Resource Server or allow an existing Resource Server to offer more Scopes to Clients.

curl --location -g --request PATCH '{{AS_ADMIN_URI}}' \
--header 'Content-Type: application/vnd.api+json; ext=jsonpatch' \
--header 'Authorization: {{AS_ADMIN_STATIC_TOKEN}}' \
--header 'ApiVersion: v1.0' \
--header 'Accept-Language: en' \
--data-raw '[
    {
        "op": "replace",
        "path": "/scope/1",
        "value": {
            "type": "scope",
            "id": 1,
            "attributes": {
                "description": "Read value",
                "name": "read",
                "iconUri": null,
                "dType": "Scope"
            }
        }
    },
    {
        "op": "replace",
        "path": "/scope/2",
        "value": {
            "type": "scope",
            "id": 2,
            "attributes": {
                "description": "write value",
                "name": "write",
                "iconUri": null,
                "dType": "Scope"
            }
        }
    },
    {
        "op": "replace",
        "path": "/resource-definition/1",
        "value": {
            "type": "resource-definition",
            "id": 1,
            "attributes": {
                "maxPermissionDuration": 3000000000,
                "name": "English name",
                "resourceId": "identity-profile-res-def",
                "type": "https://www.identos.com/resource-definitions/identity-profile-res-def",
                "description": "English description"
            },
            "relationships": {
                "scopes": {
                    "data": [
                        {
                            "id": 1,
                            "type": "scope"
                        },
                        {
                            "id": 2,
                            "type": "scope"
                        }
                    ]
                }
            }
        }
    },
    {
        "op": "replace",
        "path": "/resource-definition/2",
        "value": {
            "type": "resource-definition",
            "id": 2,
            "attributes": {
                "maxPermissionDuration": 3000000000,
                "name": "Health record english name",
                "resourceId": "health-record-res-def",
                "type": "https://www.identos.com/resource-definitions/health-record-res-def",
                "description": "It is the health record of each individual"
            },
            "relationships": {
                "scopes": {
                    "data": [
                        {
                            "id": 1,
                            "type": "scope"
                        },
                        {
                            "id": 2,
                            "type": "scope"
                        }
                    ]
                }
            }
        }
    }
]'

note

The localization feature is covered in more detail here.