User and Identity Role Search API

The PolicyServer management API provides a search feature for users and identity roles. This search feature is used in the UI for easier user assignment to application roles in policies.

PolicyServer does not internally manage the user and identity roles in the database, and as such the search feature must integrate with external systems to provide this feature. This integration requires a separate, customer-provided, HTTP-based search API. This documentation describes the semantics and contract for this search API.

Search API Requirements

The customer-provided user and identity role search API must contain two endpoints: one for users, and one for identity roles. These endpoints must be configured in the PolicyServer management host for PolicyServer to use them.

These endpoints are very similar, and mainly differ in the response payload expected (given the different type of data). Both must support filtering and paging according to this specification.

Important

The subjectId and roleName are case-sensitive so the implementations must return the correctly cased values. It is up to the implementation to determine whether searches are case-sensitive according to requirements.

Request

The HTTP request for the search endpoints must support GET, and accept optional query parameters:

filter: A value used to filter the search. The customer can define the semantics of what the value is used to actually filter on (e.g. name of the user or role, the description, etc.).
count: The number of results to return. If omitted, a default should be chosen by the implementation.
page: The page number being requested (1-based). If omitted, a default of 1 should be assumed.

Response

A successful HTTP response should issue a status code of 200 and contain the Content-Type of application/json.

Payload

The response payload is an object with these properties:

data: An object with the paged result.
links: An object with the links to other paged results.

Paged Result Data

The paged result data is an object that contains these properties:

totalCount: The number of the total number of records that match the request.
totalPages: The number of the total number of pages that match the request.
items: An array of the data items (user or identity role) returned in this page of results.

User

If the search result is for users, then each item in items should be an object that contains these properties:

subjectId: The unique identifier of the user.
displayName: A display name for the user.

Identity Role

If the search result is for identity roles, then each item in items should be an object that contains these properties:

roleName: The unique name of the role.
description: A description of the role.

Links

A link contains navigation information to obtain more paged results. Each link in the links array is an object with these properties:

rel: The constant value page. Indicates that the link is for paged results.
href: The URL of the paged result.
name: The type of paged result link, relative to the current paged results.

The allowed values and semantics for the link name property are:

current: The current page in the results.
first: The first page in the results.
last: The last page in the results.
prev: The previous page in the results. This link may not be present (depending on the current).
next: The next page in the results. This link may not be present (depending on the current).

Examples

An example of user results is shown below:

{
    "data": {
        "totalCount": 5002,
        "totalPages": 1001,
        "items": [
            {
                "subjectId": "8f66ab86-fc25-4605-bf42-13241febd165",
                "displayName": "Aaenzkv Gmcdgwn (Aaenzkv.Gmcdgwn@Qfycpfm.com) no-tenant"
            },
            {
                "subjectId": "db4cf50e-6183-4f1f-9a72-71d30269355d",
                "displayName": "Aanxgvw Omvqdsh (Aanxgvw.Omvqdsh@Ejanrio.com) no-tenant"
            },
            {
                "subjectId": "64c77246-73d3-460b-ac03-333b153c99de",
                "displayName": "Aasvpjj Umlduho (Aasvpjj.Umlduho@Tqfikgi.com) tenant2"
            },
            {
                "subjectId": "819edcd4-7063-4ea4-bc19-d5d374d0de0d",
                "displayName": "Aatizlv Ryqoyie (Aatizlv.Ryqoyie@Geodgtr.com) tenant3"
            },
            {
                "subjectId": "1fa4431e-4813-43b5-bf1b-d89847538a14",
                "displayName": "Aavgifp Ilnmnfn (Aavgifp.Ilnmnfn@Icfoaxp.com) tenant2"
            }
        ]
    },
    "links": [
        {
            "rel": "page",
            "href": "http://localhost:7059/users?count=5&page=2",
            "name": "current"
        },
        {
            "rel": "page",
            "href": "http://localhost:7059/users?count=5&page=1",
            "name": "first"
        },
        {
            "rel": "page",
            "href": "http://localhost:7059/users?count=5&page=1001",
            "name": "last"
        },
        {
            "rel": "page",
            "href": "http://localhost:7059/users?count=5&page=3",
            "name": "next"
        },
        {
            "rel": "page",
            "href": "http://localhost:7059/users?count=5&page=1",
            "name": "prev"
        }
    ]
}

A sample of role results is shown below:

{
    "data": {
        "totalCount": 200,
        "totalPages": 40,
        "items": [
            {
                "roleName": "b0caa591-a970-48c2-bc08-5d4395e75701",
                "description": "Aiupsmg tenant3"
            },
            {
                "roleName": "50367246-187a-40a7-8240-15d70f61cd73",
                "description": "Aspgswg tenant2"
            },
            {
                "roleName": "ec931567-6418-4cf2-84b8-9a71bdb23be1",
                "description": "Atfdqxj tenant3"
            },
            {
                "roleName": "ef7b8a85-362f-453d-a1aa-6e5f8a4f3f83",
                "description": "Audoghl tenant3"
            },
            {
                "roleName": "bf129539-f9c0-4bbf-85a5-1c6603f66756",
                "description": "Ayaxgsq tenant2"
            }
        ]
    },
    "links": [
        {
            "rel": "page",
            "href": "http://localhost:7059/roles?count=5&page=2",
            "name": "current"
        },
        {
            "rel": "page",
            "href": "http://localhost:7059/roles?count=5&page=1",
            "name": "first"
        },
        {
            "rel": "page",
            "href": "http://localhost:7059/roles?count=5&page=40",
            "name": "last"
        },
        {
            "rel": "page",
            "href": "http://localhost:7059/roles?count=5&page=3",
            "name": "next"
        },
        {
            "rel": "page",
            "href": "http://localhost:7059/roles?count=5&page=1",
            "name": "prev"
        }
    ]
}

Securing the API

The search API should authenticate calls to prevent unauthorized callers from accessing the user and identity role data. This authentication will be in the form of a token passed via the Authorization header. This token will be a JSON web token (JWT) issued by PolicyServer.

The JWT must be validated by checking:

The digital signature. The public key used to sign the token will be available from the PolicyServer authority discovery document (e.g. the path .well-known/openid-configuration/jwks relative to base URL of PolicyServer).
The iss (issuer) is the base URL of PolicyServer’s authority.
The exp (expiration in unix time) has not yet passed.
The scope is the value policyserver.externalsearch.