--- title: Creating a SCIM connection description: You can set up provisioning to or from a SCIM identity store. component: pingone page_id: pingone:integrations:p1_create_scim_connection canonical_url: https://docs.pingidentity.com/pingone/integrations/p1_create_scim_connection.html revdate: June 4, 2025 page_aliases: ["p1_scim_provisioning_features.adoc", "p1_scim_filter_expressions.adoc", "p1_scim_provisioning_limitations.adoc", "p1_use_scim_api_to_import_users.adoc"] section_ids: steps: Steps result: Result: result-2: Result: troubleshooting: Troubleshooting: result-3: Result next-steps: Next steps scim-provisioning-features: SCIM provisioning features p1_scim_filter_expression: SCIM filter expressions p1_scim_limitations: SCIM provisioning known limitations service-provider-sp-connections: Service provider (SP) connections attributes: Attributes other: Other p1_scim_api_provisioning: Using the SCIM API to import users accessing-the-pingone-scim-api: Accessing the PingOne SCIM API using-the-users-endpoint: Using the Users endpoint examples: Examples --- # Creating a SCIM connection You can set up provisioning to or from a System for Cross-domain Identity Management (SCIM) identity store. You can also use the PingOne API to set up inbound SCIM for user provisioning. Learn more in [SCIM](https://developer.pingidentity.com/pingone-api/platform/scim.html) in the PingOne API documentation. ## Steps 1. In the PingOne admin console, go to **Integrations > Provisioning**. 2. Click **[icon: plus, set=fa]**and then click **New Connection**. 3. On the **Identity Store** line, click **Select**. 4. On the **SCIM Outbound** tile, click **Select**. Click **Next**. 5. Enter a name and description for this provisioning connection. ### Result: The connection name appears in the provisioning list after you save the connection. 6. Click **Next**. 7. In the **Configure Authentication** section, enter the values for the following fields: | Field | Value | | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **SCIM Base URL** | The fully qualified URL to use for the SCIM resources, such as `https://scim-example.com/v2/`. | | **Users Resource** | The endpoint for the SCIM `User` resource. | | **SCIM Version** | The SCIM version to use for the connection. | | **Groups Resource** | The endpoint for the SCIM `Groups` | | **Authentication Method** | The SCIM authentication method to use for the connection.You can choose to use no authentication (**None**). For all other methods, additional entry fields are displayed, depending on the selected authentication method. If possible, you should use the OAuth 2 Bearer Token or OAuth 2 Client Credentials authentication methods. Basic Authentication provides limited security: The identity store configuration has the provided Basic Auth credentials. The authentication scope is exactly that of the Basic Auth user, rather than a subset of the user data.- **Basic Authentication** * **Basic Auth User**: Enter the Basic Auth user for the identity store. * **Basic Auth Password**: Enter the Basic Auth user password for the identity store. * **Auth Type Header**: Select **Basic**, **Bearer**, **OAuth Client Credentials**, or **Custom** (to supply your own header configuration). - **OAuth 2 Bearer Token** * **OAuth Access Token**: Enter the OAuth access token value supplied by the authorization server for the identity store. * **Auth Type Header**: Select **Basic**, **Bearer**, **OAuth Client Credentials**, or **Custom** (to supply your own header configuration). - **OAuth 2 Client Credentials** * **OAuth Token Request**: Enter the endpoint URL used to obtain an access token, such as `https://scim-example.com/as/token.oauth2`. * **OAuth Client ID**: Enter the client ID registered with the OAuth server for the provisioning identity store. * **OAuth Client Secret**: Enter the client secret value associated with the OAuth client ID. * **Auth Type Header**: Select **Basic**, **Bearer**, **OAuth Client Credentials**, or **Custom** (to supply your own header configuration). If you select Custom, the Custom Header entry field displays. Enter the custom header configuration. Custom headers added here will be added only as authorization headers in the request. | 8. Click **Test connection** to verify that PingOne can establish a connection to the SCIM resource. ### Result: If there are any issues with the connection, a **Test Connection Failed** modal opens. Click **Continue** to resume the setup with an invalid connection. | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | You can't use the connection for provisioning until you've established a valid connection to SCIM. To retry, click **Cancel** in the **Test Connection Failed** modal and repeat step 7. | ### Troubleshooting: Learn more about troubleshooting your connection in [Troubleshooting Test Connections Failure](p1_provisioning_troubleshooting_test_connection_failure.html). 9. In the **Configure Preferences** and **Users Actions** sections, configure the following: | Field | Description | | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **User filter expression** | Determines how the connection uses the specified **User Identifier** to match existing users in the target identity store to the users being provisioned from the source identity store. Learn more in [SCIM filter expressions](#p1_scim_filter_expression). | | **User Identifier** | The identifier for the user filter expression. | | **Custom Attribute Schema URNs** (optional) | A comma-delimited list of schema URNs to define a location for custom attributes. Use this option if the SCIM provider does not follow the standard naming convention for schema extensions in which custom attributes are defined. That is, URNs of the form `urn:ietf:params:scim:schemas:extension::2.0:User`. | | **Group Membership Handling** | Determines whether to update or replace target groups with PingOne memberships. Select **Merge** or **Overwrite**. Merging or overwriting memberships only applies to SCIM, Slack, and GitHub EMU provisioning connections. There is a limitation when syncing groups and group memberships to AWS Identity Centre and Atlassian Cloud. Learn more in SCIM provisioning known limitations. | | **Enable users creation** | Determines whether to create a user in the target identity store when the user is created in the source identity store. | | **Enable users updation** | Determines whether to update user attributes in the target identity store when the user is updated in the source identity store.If **Enable users updation** is selected, you can choose to select **Enable users disable** which determines whether to disable a user in the target identity store when the user is disabled in the source identity store. | | **Enable users deprovision** | Determines whether to deprovision a user in the target identity store when the user is deprovisioned in the source identity store.If Enable users deprovision is selected, the following configurations appear.- **Remove Action**: Determines whether to remove or disable a user in the target identity store when the user is deleted in the source identity store. Select **Delete** or **Disable**. Remove Action is only available if you select Enable users disable. - **Deprovision on rule deletion**: Determines whether to deprovision users if the associated provisioning rule is deleted. | 10. Click **Save**. 11. To enable the connection, click the toggle at the top of the details panel to the right (blue). | | | | - | ------------------------------------------------------------------------- | | | You can disable the connection by clicking the toggle to the left (gray). | ## Result The SCIM provisioning profile is complete and added to the list of provisioning profiles on the **Provisioning** page. ## Next steps Sync group members out of PingOne into a software as a service (SaaS) application. Learn more in [Configuring outbound group provisioning](p1_provisioning_configuring_outbound_group_provisioning.html). ## SCIM provisioning features Provision users from the PingOne identity store to a System for Cross-domain Identity Management (SCIM)-compliant identity store. The provisioner offers the following features: * Supports the SCIM 1.1 and 2.0 specifications * User provisioning, including `create`, `update`, `disable`, and `delete` * Supports SCIM core and enterprise attributes * Basic authentication, OAuth 2 bearer token, and OAuth 2 client credentials authentication * Supports SCIM overrides, such as filter expression, authorization header type, and users API path * Ability to provision disabled user accounts * Configurable deprovisioning actions * Configurable group provisioning ## SCIM filter expressions Use SCIM filter expressions to define how the provisioner matches existing users in the target application to users in the identity store. The expression overrides the default filter expression that is set by the User Identifier field. The user filter expression contains the attribute name, the operation, and the attribute value. The attribute value is represented by `"%s"` in the expression. ![The User Filter Expression screen.](_images/ypm1586808243472.png) The `"%s"` variable stores the value of the user identifier. The value that you select in the User Identifier list, such as `userName` or `workEmail`, is used in the User Filter Expression and replaces the contents of the `"%s"` variable. Example filter expressions: * `userName Eq "%s"` * `email Co "%s"` For more information, see the [Filtering section](https://tools.ietf.org/html/rfc7644#section-3.4.2.2) in the SCIM 2.0 specification RFC 7644. ## SCIM provisioning known limitations The following are known issues or limitations with System for Cross-domain Identity Management (SCIM) user provisioning. ### Service provider (SP) connections * The `Unique User Identifier` cannot be changed in an SP connection configuration. To change to a different `Unique User Identifier`, delete the existing connection and then create a connection with the new `Unique User Identifier`. * All SP connections with the same target must use the same `Unique User Identifier`. If multiple SP connections are created for the same target, every subsequent connection will use the `Unique User Identifier` configured in the first connection that was created. ### Attributes * The connector has a limit of one value per type (for example, home, work, and other) for multi-value attributes (for example, email, phone, and address). * If the application does not specify type or primary information on multi-value attributes, unexpected behavior can occur. During an update, existing attributes on the application cannot be removed, and the desired value cannot be correctly set as primary. * The provisioner cannot clear a user attribute after it is set. * PingOne does not support multi-value attributes, so the first attribute value will be used. * If the target application supports two email attributes and one attribute is empty, the provisioner populates both attributes with the email address and sets both as primary. This can produce unexpected effects in some target applications. ### Other * SCIM-compliant SPs might implement or interpret the SCIM standards differently, which can result in behavior that is not consistent with the intended use of the SCIM provisioner. * When syncing groups and group memberships to AWS Identity Centre, you can encounter a `400 invalid` filter when a group's name has a special character in a different language. * When syncing groups and group memberships to Atlassian Cloud, renaming a group is not supported. Updating the Group Name causes a UI mismatch on the group's Sync Status(Healthy - for overwrite / Sync Failure - for merge). Adding and removing members continues to work. * When provisioning users and groups to AWS Identity Center, you might encounter an error such as `The resource could not be modified. [prov_exception_msg] [SCIM004,]`.The SCIM Provisioner responds with the message `Request is unparsable, syntactically incorrect, or violates schema`. | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | For AWS, every user must have a First name, Last name, Username, and Display name value specified. If any of these values are missing from a user, that user is not provisioned.Learn more about special characters that you must not use in attributes synchronized with SCIM in [Limitations](https://docs.aws.amazon.com/singlesignon/latest/developerguide/limitations.html) and [ListUsers](https://docs.aws.amazon.com/singlesignon/latest/developerguide/listusers.html) in the AWS documentation. The `<>;:%` SCIM filter expression is in the correct format as defined by AWS. | * When provisioning users and groups to Atlassian Cloud, the SCIM filter is `userName eq "%s"`. If given an invalid SCIM filter, you might encounter an error such as `The resource could not be modified. [prov_exception_msg] [SCIM004]`.The SCIM Provisioner responds with the message `Resource [USER] invalid filter`. ## Using the SCIM API to import users Use the SCIM API to import users into PingOne. The PingOne SCIM API acts as a translation layer that receives SCIM requests to then issue as equivalent PingOne API requests, and translates PingOne API responses to SCIM-compliant responses for the user. | | | | - | ------------------------------------------------------- | | | PingOne supports only version 2.0 of the SCIM standard. | ### Accessing the PingOne SCIM API The URI for the PingOne SCIM API is `https://scim-api.pingone.com/environments/{{envID}}/v2/` where {{envID}} is the ID for the appropriate PingOne environment. ### Using the `Users` endpoint Use the `Users` endpoint to create, update, and delete users. The URI for the `Users` endpoint is {{scimPath}}/environments/{{envID}}/v2/Users where: * {{scimPath}} is the geography-based domain for the PingOne SCIM service provider, such as `https://scim-api.pingone.com` or `https://scim-api.pingone.eu`. * {{envID}} is the ID for the appropriate PingOne environment. ### Examples * Create user POST {{scimPath}}/environments/{{envID}}/v2/Users * Read one SCIM user GET {{scimPath}}/environments/{{envID}}/v2/Users/{{userID}} * Read all SCIM users GET {{scimPath}}/environments/{{envID}}/v2/Users * Delete SCIM user DELETE {{scimPath}}/environments/{{envID}}/v2/Users/{{userID}} You can use the `DirectMappedUsers` endpoint to pass attributes exactly as they appear in the PingOne schema. You can pass any attributes, including custom attributes, by including the exact name of the attribute in the SCIM payload. Learn more in [SCIM](https://developer.pingidentity.com/pingone-api/platform/scim.html) in the PingOne API Reference.