Filtering users using the REST API

Introduction

This document explains how to filter users using the .filter endpoint: api/rest/v2/users/.filter. The filtering capabilities include:

• Filtering on user properties: userName, displayName, groups, organization, externalId and active
• Filter on user claims

For more details on the filter operators, refer to https://tools.ietf.org/html/rfc7644#section-3.4.2.

Filtering users by claims

Syntax:

urn:scim:schemas:extension:safewhere:identify:1.0[Claims[(type <operator> "claim_type" and value <operator> "claim_value")]]

Examples

The following examples explain how to filter users based on their claims through the REST API.

Example 1. Users assigned at least one role

The following query finds all users who have been assigned at least one role in your system. It can be helpful for auditing purposes, such as identifying users with permissions to access the REST API and the Admin interface:

urn:scim:schemas:extension:safewhere:identify:1.0[Claims[(type eq "urn:identify:rest-api:role" and value pr)]]

To find all users who have not been assigned a role:

urn:scim:schemas:extension:safewhere:identify:1.0[Claims[(type eq "urn:identify:rest-api:role" and value eq "")]]

Example 2. Users with a specific role

The following query finds all users with a specific role in your system, such as users with the Administrator role:

urn:scim:schemas:extension:safewhere:identify:1.0[Claims[(type eq "urn:identify:rest-api:role" and value co "Administrator")]]

Example 3. Users with roles matching a specific pattern

The following query finds all users with permission to make changes to at least one resource type in Identify:

urn:scim:schemas:extension:safewhere:identify:1.0[Claims[(type eq "urn:identify:rest-api:role" and value co "Contributor")]]

Example 4. Users with at least one of specific roles

The following query finds all users who have either the Administrator or Observer role:

urn:scim:schemas:extension:safewhere:identify:1.0[Claims[(type eq "urn:identify:rest-api:role" and (value eq "Administrator" or value eq "Observer"))]]

Example 5. Chaining filters with other user attributes

You can also apply additional filters on other user attributes. For example, the following query finds all users with the Observer role who belong to the ITDepartment organization:

urn:scim:schemas:extension:safewhere:identify:1.0[Claims[(type eq "urn:identify:rest-api:role" and value co "Observer")]] and urn:scim:schemas:extension:enterprise:1.0[organization eq "ITDepartment"]

Filtering users by the userName property

Syntax:

userName <operator> "<user_Name>"

Example:

The following query finds all users whose userName ends with @gmail.com.

userName ew "@gmail.com"

Filtering users by the displayName property

Syntax:

displayName <operator> "<display_Name>"

Example:

The following query finds all users whose displayName contains John.

displayName co "John"

Filtering users by the active property

Syntax:

active <operator> "<true_or_false>"

Example:

The following query finds all users who is inactive.

active eq "false"

Filtering users by the organization property

Syntax (by organization name):

urn:scim:schemas:extension:enterprise:1.0[organization <operator> "<organization_name>"]

Syntax (by organization Id):

urn:scim:schemas:extension:enterprise:1.0[organizationid <operator> "<organization_id>"]

Example:

• The following query retrieves all users associated with the organization whose name is Organization 01.

  urn:scim:schemas:extension:enterprise:1.0[organization eq "Organization 01"]
  

• The following query retrieves all users associated with the organization whose ID is 0ef86b49-1edf-4c3b-ae17-d5e4b13606a5.

  urn:scim:schemas:extension:enterprise:1.0[organizationid eq "0ef86b49-1edf-4c3b-ae17-d5e4b13606a5"]
  

Filtering users by the group property

Filtering users by group is used to retrieve users associated with a specific group, identified by its display name and Id. This filter can be applied using just the display name, just the group Id, or by combining both.

Syntax (by display name):

groups[(display <operator> "<group_display_name>")]

Syntax (by group Id):

groups[(value <operator> "<group_id>")]

Syntax (by combining both):

groups[(display <operator> "<group_display_name>" and value <operator> "<group_id>")]

Examples:

• The following query retrieves all users in the group whose name is Group1:

  groups[(display eq "Group1")]
  

• The following query retrieves all users in the group whose Id is 36d21035-9092-46ee-a962-fa3c7c5dad45:

  groups[(value eq "36d21035-9092-46ee-a962-fa3c7c5dad45")]
  

• The following query retrieves all users in the group whose name is Group1 and Id is 36d21035-9092-46ee-a962-fa3c7c5dad45:

  groups[(display eq "Group1" and value eq "36d21035-9092-46ee-a962-fa3c7c5dad45")]
  

Filtering users by the ExternalId property

Syntax:

externalId <operator> "<external_id>"

Example:

externalId sw "4f0bb799-eb33-4c23-80c9-b06e3da388a5"

This example returns users whose externalId starts with 4f0bb799-eb33-4c23-80c9-b06e3da388a5.