Configuring a Resource Server

Scope and Audience

This section is meant for an administrator of an FPX network and covers how to register a new Resource Server or update an existing one in an FPX environment using 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

Before a Resource Server can interact with a Federated Privacy Exchange (FPX) Network, an FPX Admin User must register their service at the Authorization Server (AS). This process can be done through the AS Admin API, either manually or through a scripted API sequence.

Onboarding is a two-step process. First, the Resource Server must be registered and set up as an OAuth 2.0 Client of the Authorization Server. Secondly, the FPX Admin User can register Resources to this Resource Server. If the FPX network is not set up to allow Resource Servers from registering their resources, this step is required.

Resources which are registered by the Admin User on the Resource Server's behalf, or registered by the Resource Server using the Resource Server's own PAT, are more general than standard UMA 2.0 resources. These resources may be mapped to a specific user's data during introspection through the ROT, a unique extension of FPX. For more information on the purpose and use of ROTs, refer to the Glossary and the Partners section of this guide.

Until Resources are defined, users will still be able to connect to the Resource Server but will be unable to share any data with Clients.

Configuring a Resource Server via API

Resource Server 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 instruction can be found at here

Overview

A resource server is composed by the following data (Ordered by the creation time from old to latest)

Resource Server

OAuthClientMetadata
OAuthClient

Resource

Resource is optional

Resource Servers may be able to create their own resources depending on the governance model and security of the network. Creating resources during onboarding allows Resource Servers to easily integrate and test their applications, but requires cooperation between the network administrator and the Resource server for what resources and scopes they wish to protect.

If the Resource Server cannot create its own resources, then resource definitions need to exist at the Authorization Server.

Section 1: Resource Server

Type: "oauth-client-metadata"

Defines additional data for OAuth client. For example, authentication type, scope, secret, etc.

Note

The clientAuthenticationType, grantTypes, scopes, and secret attributes MUST contain valid data. Failure to provide these details will result in an error being returned by the Authorization Server.

Note

"" means empty string

Attributes	Description	Example value	Required	Localizable
issuerUri	Provide host URL of the service provider.	""	Yes	No
clientType	Client type. For a resource server, this should be CONFIDENTIAL.	CONFIDENTIAL	Yes	No
jwksRaw	Public key details registered directly into the database. A client can either register the public key set in this parameter or provide a URI in the `jwksUri` parameter to expose that endpoint and get the public key set. Can be left blank if `jwksUri` is populated.	Public key information	Yes	No
jwksUri	URL of a set of keys containing the public keys. Can be left blank if `jwksRaw` is populated.	https://fpxrs-alpha.rs.dev.identos.ca/jwks	Yes	No
clientAuthenticationType	Authentication method. This may be one of the following: - client_secret_basic - client_secret_post - private_key_jwt	client_secret_basic	Yes	No
grantTypes	Grant type	"refresh_token client_credentials"	Yes	No
scopes	Scopes of client. This may be register or uma_protection. To use the resource registration or introspection APIs, the uma_protection scope is required.	uma_protection	Yes	No
clientSecret	Any string length `<=`255	fpxrs-alpha-clientsecret	No	No

Type: "oauth-client"

Defines client id for the Resource Server

Attribute	Description	Example value	Required	Localizable
clientId	Client identifier in string	fpxrs-alpha-clientid	Yes	No
clientName	A human readable name for the client.	FPX Resource Server Alpha	No	No

Relationship	Description	Required
oAuthClientMetaData	The ID needs to match that of the associated OAuth Client Metadata, see the sample request	Yes

Type: "resource-server"

Attribute	Description	Example value	Required	Localizable
baseUrl	Host of the resource server	"https://fpxrs-alpha.rs.dev.identos.ca"	Yes	No
name	Readable name of resource server.	"Resource Server Alpha"	Yes	Yes
resourceServerId	Unique string identifier that represents resource server.	"fpx-alpha"	Yes	No
disabledOn	Date and time at which the entity was, or will be, disabled. The value must be in "yyyy-MM-dd'T'HH:mm:ss'Z'" format. In order to re-enable, the value must be reset to the default value `null`.	"2021-01-01T11:00:00Z"	No	No

Relationship	Description	Required
oAuthClient	The OAuth Client previously created	Yes

Sample Requests

Create Resource Server - All in one

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": "/oauth-client-metadata",
        "value": {
            "id": 2,
            "type": "oauth-client-metadata",
            "attributes": {
                "issuerUri": "https://fpxrs-alpha.rs.dev.identos.ca",
                "clientAuthenticationType": "client_secret_basic",
                "clientType": "CONFIDENTIAL",
                "grantTypes": "refresh_token client_credentials",
                "jwksRaw": null,
                "jwksUri": null,
                "scopes": "uma_protection",
                "clientSecret": "fpxrs-alpha"
            }
        }
    },
    {
        "op": "add",
        "path": "/oauth-client",
        "value": {
            "type": "oauth-client",
            "id": 2,
            "attributes": {
                "clientId": "fpxrs-alpha",
                "clientName": "FPX Resource Server Alpha"
            },
            "relationships": {
                "oAuthClientMetaData": {
                    "data": {
                        "type": "oauth-client-metadata",
                        "id": 2
                    }
                }
            }
        }
    },
    {
        "op": "add",
        "path": "/resource-server",
        "value": {
            "type": "resource-server",
            "id": 1,
            "attributes": {
                "baseUrl": "https://fpxrs-alpha.rs.dev.identos.ca",
                "name": "FPXRS Alpha",
                "resourceServerId": "fpx-alpha"
            },
            "relationships": {
                "oAuthClient": {
                    "data": {
                        "id": 2,
                        "type": "oauth-client"
                    }
                }
            }
        }
    }
]'

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

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

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

Update Resource Server - All in one

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": "/oauth-client-metadata/2",
        "value": {
            "id": 2,
            "type": "oauth-client-metadata",
            "attributes": {
                "issuerUri": "https://fpxrs-alpha.rs.dev.identos.ca",
                "clientAuthenticationType": "client_secret_basic",
                "clientType": "CONFIDENTIAL",
                "grantTypes": "refresh_token client_credentials",
                "jwksRaw": null,
                "jwksUri": null,
                "scopes": "uma_protection",
                "clientSecret": "fpxrs-alpha"
            }
        }
    },
    {
        "op": "replace",
        "path": "/oauth-client/2",
        "value": {
            "type": "oauth-client",
            "id": 2,
            "attributes": {
                "clientId": "fpxrs-alpha",
                "clientName": "FPX Resource Server Alpha"
            },
            "relationships": {
                "oAuthClientMetaData": {
                    "data": {
                        "type": "oauth-client-metadata",
                        "id": 2
                    }
                }
            }
        }
    },
    {
        "op": "replace",
        "path": "/resource-server/1",
        "value": {
            "type": "resource-server",
            "id": 1,
            "attributes": {
                "baseUrl": "https://fpxrs-alpha.rs.dev.identos.ca",
                "name": "FPXRS Alpha",
                "resourceServerId": "fpx-alpha"
            },
            "relationships": {
                "oAuthClient": {
                    "data": {
                        "id": 2,
                        "type": "oauth-client"
                    }
                }
            }
        }
    }
]'
 

Disable Resource Server

curl --location -g --request PATCH '{{AS_ADMIN_URI}}/resource-server/1' \
--header 'Content-Type: application/vnd.api+json' \
--header 'Authorization: {{AS_ADMIN_STATIC_TOKEN}}' \
--header 'ApiVersion: v1.0' \
--data-raw '{
     "data": {
            "type": "resource-server",
            "id": 1,
            "attributes": {
                "disabledOn": "2021-01-01T11:00:00Z"
        }
    }
}'

Section 2: Resource

A protected resource allows a Resource Server to provide data and APIs for end-users to clients through FPX. Resources can be as simple as an email address or as complicated as granular access to an FHIR repository or banking services. Each resource must specify what type of resource this is, which will allow end-users to provide them to clients requesting that type of resource.

Be careful with Resource Definition and Scope

The Resource_Definition and Scope need to be created before creating any Resource. See the page on configuring Resource Definitions, here

Type: "resource"

Attribute	Description	Example Value	Required	Localizable
maxPermissionDuration	The maximum duration that client is allowed to access this resource	300000	Yes	No
resourceId	The unique identifier of resource	resource1_fpx-alpha	Yes	No
resourceLocation	The path to the resource at the RS	"https://fpxrs-alpha.rs.dev.identos.ca/resource/identity-profile"	No	No
disabledOn	Date and time at which the entity was, or will be, disabled. The value must be in "yyyy-MM-dd'T'HH:mm:ss'Z'" format. In order to re-enable, the value must be reset to the default value `null`.	"2021-01-01T11:00:00Z"	No	No

Relationship	Description	Required
AllowedScopes	A resource need to have as least one scope. For example, the network may have registered a resource type for a standardized Calendar API. It specifies that the API can offer read, write, delete, share, and export scopes to Clients. It specifies that the API can offer read, write, delete, share, and export scopes to Clients. A network administrator may wish to create a Calendar API Resource for a specific Resource Server that offers read access only for security reasons. This entry was previously created here.	No (but need at least one to maintain normal functionality)
resourceDefinition	The definition of the resource, which was previously created here.	Yes
resourceServer	The resource server previously created	Yes

Sample Requests

Create Resource

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": "/resource",
        "value": {
            "type": "resource",
            "id": 1,
            "attributes": {
                "maxPermissionDuration": 3000000000,
                "resourceId": "resource1_fpx-alpha",
                "resourceLocation": "https://fpxrs-alpha.rs.dev.identos.ca/resource/identity-profile"
            },
            "relationships": {
                "allowedScopes": {
                    "data": [
                        {
                            "id": 1,
                            "type": "scope"
                        },
                        {
                            "id": 2,
                            "type": "scope"
                        }
                    ]
                },
                "resourceDefinition": {
                    "data": {
                        "id": 1,
                        "type": "resource-definition"
                    }
                },
                "resourceServer": {
                    "data": {
                        "id": 1,
                        "type": "resource-server"
                    }
                }
            }
        }
    }
]'

Get Resource

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

Update Resource

curl --location -g --request PATCH '{{AS_ADMIN_URI}}/resource/1' \
--header 'Content-Type: application/vnd.api+json' \
--header 'ApiVersion: v1.0' \
--header 'Authorization: {{AS_ADMIN_STATIC_TOKEN}}' \
--header 'Accept-Language: en' \
--data-raw '{
    "data": {
        "type": "resource",
        "id": 1,
        "attributes": {
            "maxPermissionDuration": 3000000000,
            "resourceId": "resource1_fpx-alpha",
            "resourceLocation": "https://fpxrs-alpha.rs.dev.identos.ca/resource/identity-profile"
        },
        "relationships": {
            "allowedScopes": {
                "data": [
                    {
                        "id": 1,
                        "type": "scope"
                    },
                    {
                        "id": 2,
                        "type": "scope"
                    }
                ]
            },
            "resourceDefinition": {
                "data": {
                    "id": 1,
                    "type": "resource-definition"
                }
            },
            "resourceServer": {
                "data": {
                    "id": 1,
                    "type": "resource-server"
                }
            }
        }
    }
}'

Disable Resource

curl --location -g --request PATCH '{{AS_ADMIN_URI}}/resource/1' \
--header 'Content-Type: application/vnd.api+json' \
--header 'Authorization: {{AS_ADMIN_STATIC_TOKEN}}' \
--header 'ApiVersion: v1.0' \
--data-raw '{
     "data": {
            "type": "resource",
            "id": 1,
            "attributes": {
                "disabledOn": "2021-01-01T11:00:00Z"
        }
    }
}'

note

The localization feature is covered in more detail here.

Scope and Audience​

Required Reference​

Overview​

Configuring a Resource Server via API​

Overview​

Section 1: Resource Server​

Type: "oauth-client-metadata"​

Type: "oauth-client"​

Type: "resource-server"​

Sample Requests​

Create Resource Server - All in one​

Get Resource Server related information - OAuthClient_Metadata​

Get Resource Server related information - OAuthClient​

Get Resource Server related information - ResourceServer​

Update Resource Server - All in one​

Disable Resource Server​

Section 2: Resource​

Type: "resource"​

Sample Requests​

Create Resource​

Get Resource​

Update Resource​

Disable Resource​

Scope and Audience

Required Reference

Overview

Configuring a Resource Server via API

Overview

Section 1: Resource Server

Type: "oauth-client-metadata"

Type: "oauth-client"

Type: "resource-server"

Sample Requests

Create Resource Server - All in one

Get Resource Server related information - OAuthClient_Metadata

Get Resource Server related information - OAuthClient

Get Resource Server related information - ResourceServer

Update Resource Server - All in one

Disable Resource Server

Section 2: Resource

Type: "resource"

Sample Requests

Create Resource

Get Resource

Update Resource

Disable Resource