How Do I Setup User Provisioning Using SCIM?

SCIM 2.0 is a mechanism where users can be pushed, or provisioned from a third party SCIM client to a SCIM service provider, in this case your community. In most circumstances this third party SCIM client acts as the authority for user management and registration in the community itself is generally disabled. It is also designed to be used with single sign-on using OpenID connect, where the identity provider is providing both SCIM and OpenID connect services. Note SCIM supports users being pushed from an identity provider to your community. It does not support acting as a SCIM client where users would be pushed back to the identity provider.

Compatibility And Requirements

SCIM 2.0 support was introduced in version 12.0.3.17950, and is only available in this and later version of the community platform. At this time it is only certified to work with the Okta Identity Platform. The following article is written accounting for expanded support in the future.

Features

Push New Users
- Users provisioned in the SCIM Client will be added as new users to your community
Push Profile Updates
- User profile fields in the SCIM client can be mapped to custom user profile fields based on a JSON mapping format when configured. See "Attribute Mapping" in the plugin configuration. Note that even though profile fields can be updated from the user information, these fields are never returned to the client.
Push User Deactivation (Or Delete For Supported Clients)
- When a SCIM client issues a deactivation action, the user will be disapproved in the community.
- If the client supports deletes, community can react by disapproving the user(default), reassigning content and deleting, or deleting. See "User Delete Action" in the SCIM plugin configuration.
Reactivate Users
- Users that were previously deactivated can be reactivated(approved in the community).
Push Groups as Roles
- Groups can be pushed to your community as new Site Roles.
Push Group Membership As Role Membership
- Group Membership and removal can be updated in your community site roles.
Import Users
- Users can be imported into your SCIM client from your community
Import Groups(Roles)
- Existing community roles can be imported into your SCIM client
  - NOTE: Importing membership is not currently supported
Schema Discovery
- You can learn more about the SCIM implementation through discovery URLs.
  - {{Community Site Url}}/scim/v2/ServiceProviderConfig -This URLwill describe the community SCIM capabilities
  - {{Community Site Url}}/scim/v2/ResourceTypes- Describes what resource types are supported by the community and URLs for additional information.
  - {{Community Site Url}}//scim/v2/Schemas - Describes the supported schemas for the resource types and URLs for additional information.

Add and Configure the SCIM Client Application

For most systems you must configure SCIM provisioning in the client application. Consult the client's documentation on how to setup provisioning. For SCIM clients currently certified to work with your community, you can consult one of the configuration guides below. Note these are the only platforms currently fully supported.

Okta Identity Platform

How Do I Configure Okta for OpenID Connect and SCIM Provisioning

1. Configure an OAuth Client

Note if you are using Okta for SCIM, OAuth currently does not apply. Consult How Do I Configure Okta for OpenID Connect and SCIM Provisioning for how to setup provisioning authentication using Okta, then skip to step 2.

In order for the SCIM client to interact with your community, they use OAuth 2.0 bearer tokens. You must first configure an OAuth client in community to authenticate a user. This client should be Confidential, utilize only the Authorization Code flow, and be trusted. The authenticating user MUST have at least Manage Members permissions in your community. The redirect URLS will be specific to the SCIM client configuration.

For more information on how to setup and configure OAuth Clients, review REST Authentication articles in our Developer Training .

2. Configure The SCIM Plugin

The SCIM plugin can be located in the Administration Area under Extensions, SCIM 2.0 Integration.

Options

Option	Required	Default	Description
Email Address is Username	No	False	If the SCIM client presents user name values as email addresses, this should be checked. To prevent unwilling information disclosure of email addresses, usernames cannot be email addresses in the community. Email addresses will be derived from the email address by removing the '@domain.com' value and ensuring the remainder is unique in the community by appending incremental numbers as needed. When checked however, username value for the user will be presented back to the SCIM client with the username set as the email address.
User Delete Action	Yes	Disapprove User	If a SCIM client issues a DELETE request to community, this value determines how the community will react. You can choose to instead disapprove the user, permanently delete the user, or reassign the content then delete. If reassign is chosen an additional option is presented to choose to what user which is by default 'Former Member'.

Advanced Profile Mapping

You can use the Mapping Options to map SCIM user attribute information to custom profile fields to a user when they are provisioned. It is defined using a specific JSON format. It is important to know that when using this feature, only common attributes and system field information is actually returned to the SCIM client. Custom profile data is preserved in the community but is not communicated to the client.

Understand the JSON

The configuration object contains three properties defined below.

{
  "attributeMappings": [],
}

Option	Description
attributeMappings	An array of attribute mappings used to define how user attributes can be mapped to custom profile fields or system fields.

Attribute Mappings

There are two ways to map an attribute, a system field or a custom profile field. A system field is a constant field in your community, as opposed to a profile field which can be configured specifically for your community. You can map any field that is a simple value, such as a string, or an array of simple values such as a string list.

A field mapping consists of these fields:

{
    "mapsTo": {  },
    "attributes": [],
    "format": ""
}

Option	Description
mapsTo	A mapping object that identifies whether you are mapping to a system field or profile field.
claims	An array of strings that defines the attribute names or paths to be used to set the value of the mapTo field. When a format is not specified and multiple attributes are specified, they are concatenated together using a space, in the order defined.
format	Defines how multiple attributes are joined, or adds additional data to an existing attribute. It is a single string where {attributeId} defines the claim to be used.

Mapping a System Field

The current system fields are supported:

displayName: The display name of the community user.

When defining a system field the following JSON format is added to the mapsTo field:

"mapsTo": { "systemField": "displayName" }

The "systemField" property is all that is required and must conform to an id of pre-defined system field as defined above.

Custom Profile Fields

When not using a system field, you can specify a custom profile field. If the profile field exists, it's value will be managed by the OpenID Connect provider. If it does not exist, it will be created the first time a value is attempted to be written.

"mapsTo": {"profileField":{"key": "profilrField_key", "label": "FieldLabel","fieldType": "Plain Text","searchable": true } }

key: This value is used as a profile field key. It will map to an existing field, or create one if it does not exist.
label: The profile field label, used when creating a new field. It is how the user interface will display the field.
fieldType: The field type of the profile field. 'Palin Text; and 'Comma-separated List' are supported for array fields.
searchable: Defines whether the field will be searchable in the community platform.

Attributes Property

You can specify one or more attributes for a 'mapsTo' field. When more than one attributeis specified, the values are concatenated by a space in the order defined into the 'mapsTo' field if a format is not specified. An attribute can be a simple type, a complex type, or an array of simple values or complex types. Depending on the type, the 'attribute' property value varies. Refer to the user schema for more information on what fields are available, compared to what your SCIM client is configured to send.

Mapping a Simple Type

A simple type is simply a string or int value. It simply uses the attribute name.

Mapping a ComplexType

A complex type is a single value presented as a JSON object. It is identified using the main attribute name, then a period, then the sub attribute name (main.subAttribute).

Mapping a Complex Array Type

A simple array type is an array of simple values. You must specify a single value by using a query

 "claims": [ {"name": "first_name" }, { "name": "emails, "type":"array","delimiter":"," }]

name: The name of the claim as presented in the token. It is always required.
type: If the claim value is an array of string values, specify 'array'
delimiter: Only for array types, this is the value used to concatenate the array values. By default it is a comma(',').

Simple single-valued claim.

{ "name": "first_name" }

Claim that has a string array as a value.

 { "name": "groups","type":"array", "delimiter":","}

Formatting

You can choose how the claim value(s) are presented using the format property. It is a static string with tokens formatted as {claimName} where claim name is the name as defined in the claims area. This is useful when multiple claims are specified. The value of the claim is substituted for the token as presented, with the exception of arrays which will be presented based on how the delineation is defined in the claim definition.

Single value format

"format":"My name is {first_name}"

Multiple attributes

"format":"{last_name}, {first_name}"