# Generic SCIM Endpoint - Replace User The Replace User endpoint completely replaces the requested user's email, name, status (active or suspended), and any other supported attributes in StrongDM with the provided user information. To suspend a user, provide the property `active: false`. ### Request #### Endpoint `/provisioning/generic/v2/Users/` #### HTTP Method `PUT` #### Path variables | Variable | Requirement | Description | Notes | Example | | -------- | ----------- | ----------- | --------------------------------------------------------------------- | -------------------- | | `` | Required | User ID | Returns a 404 if the user ID is not found or if it matches a non-user | `a-53fa578c61716688` | #### Request body attributes | Attribute | Requirement | Description | Example | | ---------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | | `active` | Required | User's status (Boolean); set `false` to suspend a user | `active: false` | | `displayName` | Optional | Name of the user that is suitable for display to end users | `"Bob Belcher"` | | `emails.display` | Optional | Email addresses for the user with subattribute `display` (canonicalized representation of user's email value) | `"[{"display": "primary email"}]` | | `emails.primary` | Optional | Email addresses for the user with subattribute `primary` (Boolean) | `"emails": [{"name": {"primary": true}]` | | `emails.type` | Optional | Email addresses for the user with subattribute `type` (human-readable classification of user's email) | `"emails": [{"name": {"type": "work"}]` | | `emails.value` | Optional | Email addresses for the user with subattribute `value` (user's email value) | `"emails": [{"name": {"value": "bob.belcher@strongdm.com"}]` | | `entitlements` | Optional | List of entitlements for the user that represent a thing the user has; may include subattributes `value`, `display`, `primary` (Boolean), and `type` | `[{"value": "value", "display": "display", "primary": true, "type": "one"}]` | | `externalId` | Optional | Identifier (string) for the resource as defined by the provisioning client | `"701984"` | | `locale` | Optional | User's default location for purposes of localizing items such as currency, date time format, or numerical representations | `"en-US"` | | `name.familyName` | Required | User's name with subattribute `familyName` (last name) | `"name": {"familyName": "Belcher"}` | | `name.formatted` | Optional | User's name with subattribute `formatted` (full name, including all middle names, titles, and suffixes as appropriate, formatted for display) | `"name": {"formatted": "Mr. Bob Belcher, III"}` | | `name.givenName` | Required | User's name with subattribute `givenName` (first name) | `"name": {"givenName": "Bob"}` | | `name.honorificPrefix` | Optional | User's name with subattribute `honorificPrefix` (title) | `"name": {"honorificPrefix": "Mr."}` | | `name.honorificSuffix` | Optional | User's name with subattribute `honorificSuffix` (suffix) | `"name": {"honorificSuffix": "III"}` | | `name.middleName` | Optional | User's name with subattribute `middleName` (middle name) | `"name": {"middleName": "Jay"}` | | `nickName` | Optional | Casual way to address the user in real life | `"Bobby"` | | `preferredLanguage` | Optional | User's preferred written or spoken language(s) | `"en-US"` | | `profileUrl` | Optional | URI that is a uniform resource locator and that points to a location representing the user's online profile | `"https://login.example.com/bobbelcher"` | | `roles` | Optional | List of roles for the user that collectively represent who the user is; does not correspond to StrongDM's internal `role` entity type; only `groups` in SCIM correspond to StrongDM roles | `[{"value": "value", "display": "display", "primary": true, "type": "one"}]` | | `schemas` | Required | Schema URI for representing users; include the value as indicated in the example | `["urn:ietf:params:scim:schemas:core:2.0:User"]` | | `timezone` | Optional | User's time zone, in IANA Time Zone database format | `"America/Los_Angeles"` | | `title` | Optional | User's title | `"Vice President"` | | `userName` | Required | User's username | `"myUser@example.test"` | | `x509Certificates` | Optional | List of certificates associated with the resource | `[{"value":"aGVsbG8gd29ybGQK"}]` | {% hint style="info" %} Optional fields are supported for the User object. Optional fields currently have no exposed representation within StrongDM's non-SCIM interfaces, but they may in the future. {% endhint %} #### Enterprise User extension attributes The following attributes are supported underneath the [Enterprise User Schema extension](https://www.rfc-editor.org/rfc/rfc7643.html#section-4.3). In order to identify the enterprise User extension, these attributes are prefixed with the schema URI `urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:`. | Attribute | Requirement | Description | Example | | ---------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | `costCenter` | Optional | Identifies the name of a cost center | `"4130"` | | `department` | Optional | Identifies the name of a department | `"Operations"` | | `division` | Optional | Identifies the name of a division | `"Research and Development"` | | `employeeNumber` | Optional | String identifier assigned to a person, typically based on order of hire or association with an organization | `"701984"` | | `manager` | Optional | User's manager; may include subattributes `value` (identifier of the SCIM resource representing the user's manager), `$ref` (URI of the SCIM resource representing the user's manager), and `displayName` (display name of the user's manager; optional) | `{"value": "26118915-6090-4610-87e4-49d8ca9f808d", "$ref": "../Users/26118915-6090-4610-87e4-49d8ca9f808d", "displayName": "Alice Glick"}` | | `organization` | Optional | Identifies the name of an organization | `"Universe"` | #### StrongDM User extension attributes The following attribute is supported under [schema extensions](https://www.rfc-editor.org/rfc/rfc7643.html#section-3.3). In order to identify the StrongDM User extension, this attribute is prefixed with the schema URI `urn:ietf:params:scim:schemas:extension:strongdm:2.0:User:`. | Attribute | Requirement | Description | Example | | ----------------- | ----------- | ----------------------------------------------------------- | ------------------------------------------------------------------------ | | `identityAliases` | Optional | Identifies the user's Identity Aliases within Identity Sets | `["identity-set-1,identity-alias-1", "identity-set-2,identity-alias-2"]` | {% hint style="info" %} For backwards compatibility, StrongDM accepts but does not store data sent via the `password` attribute. We recommend not sending `password`, as it exposes such passwords to potential Manipulator-in-the-Middle (MITM) Attacks. {% endhint %} #### Example request with all supported attributes The following Replace User example request includes all supported attributes. `PUT app.strongdm.com/provisioning/generic/v2/Users/a-1377f104617182e1` ```json { "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User", "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User", "urn:ietf:params:scim:schemas:extension:strongdm:2.0:User" ], "userName": "bob.belcher@strongdm.com", "name": { "givenName": "Bob", "familyName": "Belcher", "middleName": "Jay", "honorificPrefix": "Mr.", "honorificSuffix": "III", "formatted": "Mr. Bob Jay Belcher III" }, "emails": [ { "primary": true, "value": "bob.belcher@strongdm.com", "display": "primary email", "type": "work" }, { "primary": false, "value": "bob.belcher@example.com", "type": "personal" } ], "x509Certificates": [ { "value": "aGVsbG8gd29ybGQK", "display": "display", "primary": true }, { "value": "aGVsbG8gd29ybGQK", "display": "display2" } ], "roles": [ { "value": "value", "display": "display", "primary": true, "type": "one" }, { "value": "value", "display": "display", "type": "two" } ], "entitlements": [ { "value": "value", "display": "display", "primary": true, "type": "one" }, { "value": "value", "display": "display", "type": "two" } ], "displayName": "Bob Belcher", "nickName": "Bobby", "profileUrl": "https://login.example.com/bobbelcher", "title": "Vice President", "preferredLanguage": "en-US", "timezone": "America/Los_Angeles", "locale": "en-US", "externalId": "701984", "groups": [], "password": "t1meMa$heen", "active": true, "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": { "employeeNumber": "701984", "costCenter": "4130", "organization": "Universe", "division": "Research and Development", "department": "Operations", "manager": { "value": "26118915-6090-4610-87e4-49d8ca9f808d", "$ref": "../Users/26118915-6090-4610-87e4-49d8ca9f808d" } }, "urn:ietf:params:scim:schemas:extension:strongdm:2.0:User": { "identityAliases": [ "rdp-set,rdp-alias", "ssh-set,ssh-alias" ] } } ``` #### Simplified example request For compatibility with certain clients, the `roles` and `entitlements` attributes may be added to a user in two formats: the canonical method and the simplified method. The canonical method is shown in the [example request with all supported attributes](#example-request-with-all-supported-attributes). The simplified method of adding `roles` and `entitlements` to a user is shown in the following Replace User example request. `PUT app.strongdm.com/provisioning/generic/v2/Users/a-1377f104617182e1` ```json { "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User", "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User" ], ... "roles": [ "role1", "role2", "role3" ], "entitlements": [ "ent1", "ent2", "ent3" ] } ``` ### Response #### Example success response ```http (Status 201) ``` ```json { "active": true, "displayName": "Bob Belcher", "emails": [ { "display": "primary email", "primary": true, "type": "work", "value": "bob.belcher@strongdm.com" }, { "display": "", "type": "personal", "value": "bob.belcher@example.com" } ], "entitlements": [ { "display": "display", "primary": true, "type": "one", "value": "value" }, { "display": "display", "primary": false, "type": "two", "value": "value" } ], "externalId": "701984", "groups": [], "id": "a-412950b063569179", "locale": "en-US", "meta": { "resourceType": "User", "location": "Users/a-412950b063569179" }, "name": { "familyName": "Belcher", "formatted": "Mr. Bob Jay Belcher III", "givenName": "Bob", "honorificPrefix": "Mr.", "honorificSuffix": "III", "middleName": "Jay" }, "nickName": "Bobby", "preferredLanguage": "en-US", "profileUrl": "https://login.example.com/bobbelcher", "roles": [ { "display": "display", "primary": true, "type": "one", "value": "value" }, { "display": "display", "primary": false, "type": "two", "value": "value" } ], "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User", "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User", "urn:ietf:params:scim:schemas:extension:strongdm:2.0:User" ], "timezone": "America/Los_Angeles", "title": "Vice President", "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": { "costCenter": "4130", "department": "Operations", "division": "Research and Development", "employeeNumber": "701984", "manager": { "$ref": "../Users/26118915-6090-4610-87e4-49d8ca9f808d", "displayName": "26118915-6090-4610-87e4-49d8ca9f808d", "value": "26118915-6090-4610-87e4-49d8ca9f808d" }, "organization": "Universe" }, "userName": "bob.belcher@strongdm.com", "userType": "user", "x509Certificates": [ { "display": "display", "primary": true, "type": "", "value": "aGVsbG8gd29ybGQK" }, { "display": "display2", "primary": false, "type": "", "value": "aGVsbG8gd29ybGQK" } ], "urn:ietf:params:scim:schemas:extension:strongdm:2.0:User": { "identityAliases": [ "rdp-set,rdp-alias", "ssh-set,ssh-alias" ] } } ``` #### Example response there was a conflicting email ```json { "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], "scimType": "uniqueness", "detail": "One or more of the attribute values are already in use or are reserved.", "status": "409" } ``` #### Example response if there was no email ```json { "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], "detail": "could not create user: cannot create user: invalid operation: email cannot be blank", "status": "400" } ```