Generic SCIM Endpoint - Replace User

Last modified on October 25, 2022

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/<ID>

HTTP Method

PUT

Path variables

Variable	Requirement	Description	Notes	Example
`<ID>`	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"}]`

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.

Enterprise User extension attributes

The following attributes are supported underneath the Enterprise User Schema extension.

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"`

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.

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

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:enterprise: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"
    }
  }
}

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.

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

{
    "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

(Status 201)

{
  "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"
  ],
  "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"
    }
  ]
}

Example response there was a conflicting email

{
  "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

{
  "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"
}

Generic SCIM Endpoint - Replace User

Request #

Endpoint #

HTTP Method #

Path variables #

Request body attributes #

Enterprise User extension attributes #

Example request with all supported attributes #

Simplified example request #

Response #

Example success response #

Example response there was a conflicting email #

Example response if there was no email #