PingGateway 2024.9

UmaService

The UmaService includes a list of resource patterns and associated actions that define the scopes for permissions to matching resources. When creating a share using the REST API described below, you specify a path matching a pattern in a resource of the UmaService.

Usage

{
    "name": string,
    "type": "UmaService",
    "config": {
        "protectionApiHandler": Handler reference,
        "amService": AmService reference,                    // Use either "amService"
        "wellKnownEndpoint": configuration expression<url>,  // or "wellKnownEndpoint", but not both.
        "resources": [ object, ... ]
    }
}

Properties

"protectionApiHandler": Handler reference, required

The handler to use when interacting with the UMA Authorization Server to manage resource sets, such as a ClientHandler capable of making an HTTPS connection to the server.

For more information, refer to Handlers.

"amService": AmService reference, required if wellKnownEndpoint is not configured

The AmService heap object to use for the URI to the well-known endpoint for this UMA Authorization Server. The endpoint is extrapolated from the url property of the AmService, and takes the realm into account.

If the UMA Authorization Server is AM, use this property to define the endpoint.

If amService is configured, it takes precedence over wellKnownEndpoint.

For more information, refer to UMA discovery in AM’s User-Managed Access (UMA) 2.0 guide.

See also AmService.

"wellKnownEndpoint": configuration expression<url>, required if amService is not configured

The URI to the well-known endpoint for this UMA Authorization Server.

If the UMA Authorization Server is not AM, use this property to define the endpoint.

If amService is configured, it takes precedence over wellKnownEndpoint.

Examples:

  • In this example, the UMA configuration is in the default realm of AM:

    https://am.example.com:8088/openam/uma/.well-known/uma2-configuration

  • In this example, the UMA configuration is in a European customer realm:

    https://am.example.com:8088/openam/uma/realms/root/realms/customer/realms/europe/.well-known/uma2-configuration

For more information, refer to AM as UMA Authorization Server in AM’s User-Managed Access (UMA) 2.0 guide.

"resources": array of objects, required

Resource objects matching the resources the resource owner wants to share.

Each resource object has the following form:

{
    "pattern": resource pattern,
    "actions": [
        {
            "scopes": [ scope string, ... ],
            "condition": runtime expression<boolean>
        },
        {
            ...
        }
    ]
}

Each resource pattern can represent an application, or a consistent set of endpoints that share scope definitions. The actions map each request to the associated scopes. This configuration serves to set the list of scopes in the following ways:

  1. When registering a resource set, PingGateway uses the list of actions to provide the aggregated, exhaustive list of all scopes that can be used.

  2. When responding to an initial request for a resource, PingGateway derives the scopes for the ticket based on the scopes that apply according to the request.

  3. When verifying the RPT, PingGateway checks that all required scopes are encoded in the RPT.

A description of each field follows:

"pattern": pattern, required

A pattern matching resources to be shared by the resource owner, such as .* to match any resource path, and /photos/.* to match paths starting with /photos/.

See also Patterns.

"actions": array of objects, optional

A set of scopes to authorize when the corresponding condition evaluates to true.

"actions": [
  {
    "scopes": [ "#read" ],
    "condition": "${request.method == 'GET'}"
  },
  {
    "scopes": [ "#create" ],
    "condition": "${request.method == 'POST'}"
  }
]
"scopes": array of configuration expression<strings>, optional

One or more scopes that are authorized when the corresponding condition evaluates to true.

For example, the scope #read grants read-access to a resource.

"condition": runtime expression<boolean>, required

When the condition evaluates to true, the corresponding scope is authorized.

For example, the condition ${request.method == 'GET'} is true when reading a resource.

REST API for shares

The REST API for UMA shares is exposed at a registered endpoint. PingGateway logs the paths to registered endpoints when the log level is INFO or finer. Look for messages such as the following in the log:

UMA Share endpoint available at
 '/openig/api/system/objects/_router/routes/00-uma/objects/umaservice/share'

To access the endpoint over HTTP or HTTPS, prefix the path with the PingGateway scheme, host, and port to obtain a full URL, such as http://localhost:8080/openig/api/system/objects/_router/routes/00-uma/objects/umaservice/share.

The UMA REST API supports create (POST only), read, delete, and query (_queryFilter=true only). For an introduction to common REST APIs, refer to About Common REST.

In the present implementation, PingGateway does not have a mechanism for persisting shares. When PingGateway stops, the shares are discarded.

For information about API descriptors for the UMA share endpoint, refer to API descriptors. For information about Common REST, refer to About Common REST.

A share object has the following form:

{
    "path": pattern,
    "pat": UMA protection API token (PAT) string,
    "id": unique identifier string,
    "resource_id": unique identifier string,
    "user_access_policy_uri": URI string
}
"path": pattern, required

A pattern matching the path to protected resources, such as /photos/.*.

This pattern must match a pattern defined in the UmaService for this API.

See also Patterns.

"pat": PAT string, required

A PAT granted by the UMA Authorization Server given consent by the resource owner.

In the present implementation, PingGateway has access only to the PAT, not to any refresh tokens.

"id": unique identifier string, read-only

This uniquely identifies the share. This value is set by the service when the share is created, and can be used when reading or deleting a share.

"resource_id": unique identifier string, read-only

This uniquely identifies the UMA resource set registered with the authorization server. This value is obtained by the service when the resource set is registered, and can be used when setting access policy permissions.

"user_access_policy_uri": URI string, read-only

This URI indicates the location on the UMA Authorization Server where the resource owner can set or modify access policies. This value is obtained by the service when the resource set is registered.

More information

User-Managed Access (UMA) 2.0 Grant for OAuth 2.0 Authorization

org.forgerock.openig.uma.UmaSharingService