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

VariableRequirementDescriptionNotesExample
<ID>RequiredUser IDReturns a 404 if the user ID is not found or if it matches a non-usera-53fa578c61716688

Request body attributes

AttributeRequirementDescriptionExample
activeRequiredUser’s status (Boolean); set false to suspend a useractive: false
displayNameOptionalName of the user that is suitable for display to end users"Bob Belcher"
emails.displayOptionalEmail addresses for the user with subattribute display (canonicalized representation of user’s email value)"[{"display": "primary email"}]
emails.primaryOptionalEmail addresses for the user with subattribute primary (Boolean)"emails": [{"name": {"primary": true}]
emails.typeOptionalEmail addresses for the user with subattribute type (human-readable classification of user’s email)"emails": [{"name": {"type": "work"}]
emails.valueOptionalEmail addresses for the user with subattribute value (user’s email value)"emails": [{"name": {"value": "bob.belcher@strongdm.com"}]
entitlementsOptionalList 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"}]
externalIdOptionalIdentifier (string) for the resource as defined by the provisioning client"701984"
localeOptionalUser’s default location for purposes of localizing items such as currency, date time format, or numerical representations"en-US"
name.familyNameRequiredUser’s name with subattribute familyName (last name)"name": {"familyName": "Belcher"}
name.formattedOptionalUser’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.givenNameRequiredUser’s name with subattribute givenName (first name)"name": {"givenName": "Bob"}
name.honorificPrefixOptionalUser’s name with subattribute honorificPrefix (title)"name": {"honorificPrefix": "Mr."}
name.honorificSuffixOptionalUser’s name with subattribute honorificSuffix (suffix)"name": {"honorificSuffix": "III"}
name.middleNameOptionalUser’s name with subattribute middleName (middle name)"name": {"middleName": "Jay"}
nickNameOptionalCasual way to address the user in real life"Bobby"
preferredLanguageOptionalUser’s preferred written or spoken language(s)"en-US"
profileUrlOptionalURI that is a uniform resource locator and that points to a location representing the user’s online profile"https://login.example.com/bobbelcher"
rolesOptionalList 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"}]
schemasRequiredSchema URI for representing users; include the value as indicated in the example["urn:ietf:params:scim:schemas:core:2.0:User"]
timezoneOptionalUser’s time zone, in IANA Time Zone database format"America/Los_Angeles"
titleOptionalUser’s title"Vice President"
userNameRequiredUser’s username"myUser@example.test"
x509CertificatesOptionalList of certificates associated with the resource[{"value":"aGVsbG8gd29ybGQK"}]

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:.

AttributeRequirementDescriptionExample
costCenterOptionalIdentifies the name of a cost center"4130"
departmentOptionalIdentifies the name of a department"Operations"
divisionOptionalIdentifies the name of a division"Research and Development"
employeeNumberOptionalString identifier assigned to a person, typically based on order of hire or association with an organization"701984"
managerOptionalUser’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"}
organizationOptionalIdentifies the name of an organization"Universe"

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