SCIM API for STA

The System for Cross-domain Identity Management (SCIM) specifications are designed to make identity management between different systems easier. SCIM provides a defined schema and extension model for representing identity resources like users and groups, and a standard protocol for exchanging user data between your cloud applications and service providers, such as STA. This ensures that user data is stored in a consistent way, so that it can be shared with different applications.

The SCIM  protocol supports the creation, discovery, retrieval, and modification of users and groups. It includes an application-level REST API to run CRUD operations on your users and groups.

The STA SCIM API includes inbound REST endpoints for the SCIM 2.0 model. This means that you can connect a user repository that supports outbound SCIM directly to STA, and use the SCIM protocol to provision your users into STA.

STA implements SCIM 2.0 as specified in the RFC documents from the Internet Engineering Task Force:

• Definitions, Overview, Concepts, and Requirements: RFC 7642

• Core Schema: RFC 7643

• Protocol: RFC 7644

STA does not support the complete SCIM specification. Compatibility between a user directory that supports SCIM and the STA SCIM implementation is not guaranteed.

STA also includes a REST API for STA provides programmatic access to the management and logging functions of STA.

Getting started with the STA SCIM API

Before you can use the STA SCIM API, you need to get the following information from the STA consoles: 

• API key for authentication

• Endpoint URL to access the APIs

• Tenant code for your virtual server or account

• API documentation that describes the endpoints, methods, requests, and responses

SCIM resources

In SCIM, a resource is an artifact that is managed by a service provider, such as STA, and that contains attributes. The resource type, such as user or group, defines the resource name, endpoint URL, schemas, and other metadata. The schema is a collection of attributes that define the contents of the respective resource.

Each SCIM resource is a JSON object that has the following components:

• Resource type is either user or group.

• Schemas lists the SCIM schemas for the resources. It includes the core schema and any extensions.

• Attributes:

  • Common attributes are part of every SCIM resource, but are not defined in any particular schema.

  • Core attributes are listed in the resource type's schema.

  • Extended attributes are extensions for custom fields in STA that are not found in the core SCIM schemas.

SCIM API

The SCIM protocol uses REST-style architecture and JSON objects to communicate data about your users and groups. The API provides CRUD operations that you run on your user and group resources:

• GET Retrieves a user or group from STA.

• POST Creates a new user or group in STA.

• PUT Modifies a user or group by replacing the entire resource.

• PATCH Modifies a user or group by updating only the specified attributes.

• DELETE Deletes a user or group.

All requests to STA are made via HTTP operations on a URL derived from the base URL. Responses are returned in the body of the HTTP response, formatted as JSON. Response and error codes are transmitted via the HTTP status code of the response, and are specified in the body of the response.

The SCIM protocol specifies well-known endpoints and HTTP methods for managing resources defined in the core schema. For example, user and group resources correspond to /Users and /Groups respectively.

Service discovery operations

GET /serviceProviderConfig

Returns the configuration details for the STA SCIM API, including supported operations.

The following serviceProviderConfig attributes are not supported:

• bulk

• change password

• eTag

• filter: Only the following filters are supported:

  • and

  • eq

• sort

GET /Schemas

Returns the details for how user and group resources are formatted.

GET /Schemas/{schemaId}

Returns the details of a specific resource configuration. The following schema IDs are available:

GET /ResourceTypes

Returns the metadata about a resource type, defining the endpoint location of a resource, and the applicable schemas and extensions. Resource type resources are read-only.

It has two child endpoints:

• ResourceTypes/User

• ResourceTypes/Group

GET /ResourceTypes/User

Returns the metadata about the User resource type.

GET /ResourceTypes/Group

Returns the metadata about the Group resource type.

Rate limiting

When rate limiting occurs, the following response is returned:

• 429 Too Many Requests

The header indicates:

• RateLimit-Reset: 47

The rate limit reset is the number of seconds until the rate limiting resets, which is the minimum wait time.

In addition, the current thresholds and remaining calls are always included in the response:

X-RateLimit-Limit-minute
X-RateLimit-Limit-second
X-RateLimit-Remaining-minute
X-RateLimit-Remaining-second

Filter results

To reduce the number of returned results, include a filter as a parameter. Only the results that match the filter are returned.

You can use filters with the following operations:

• GET /tenants/{tenantCode}/scim/v2/users

• GET /tenants/{tenantCode}/scim/v2/groups

The filter parameter must contain at least one valid expression. Each expression must contain an attribute name followed by an attribute operator and optional value. Attribute names and attribute operators used in filters are case insensitive.

The following operators are supported: 

• and (logical AND): The filter is a match only if both expressions evaluate to true.

• eq (equal): The attribute and operator values must be identical for a match.

There are some limitations when using filters with patch operations.

For example:

GET /tenants/{tenantCode}/scim/v2/groups?filter=members.value **eq** "08D9B595B260F5AE01879255E21200000001"

GET /tenants/{tenantCode}/scim/v2/users?filter=active **eq** true **and** name.familyName **eq** "Smith"

The scim attribute reference identifies which user and group attributes support filters.