Create and Manage Cloud Directory Users

Centrify Identity Platform provides a built-in user service, Centrify Cloud Directory, that you can use to store users for your application. The Cloud User Management API provides calls to create, modify, and delete users, as well as retrieve information about current users, for Cloud Directory. Identity Service also provides a set of generic user functions that apply to all users, both Cloud Directory users and users from other sources, such as Active Directory or social login. For example, to retrieve a user's picture, reset a user's password, set a user's security question, or send an invite to a user, among other things, see Using generic user functions.

To create, modify, or delete users you must be a system administrator or have user-management permissions.

When you create a user, in addition to required and optional account and profile information, you can specify:

  • That the account is locked, for example, if you want to create accounts that won't be used until a later date and require an administrator to unlock.
  • Whether the password must be reset when the user first logs in.
  • Whether to add the user to "Everybody", which is a built-in role that allows an administrator to apply default characteristics— such as access to a set of common applications — to everyone in the organization. "Everybody" is read-only — you cannot add users to this role later on with the Role API, but must do so now when creating a user.
  • Whether to add the user to the System Administrator role.
  • Whet her to send an invite to the new user.

If you connect your Centrify tenant to an external store (Active Directory or LDAP), its users are able to authenticate to the cloud service using their Active Directory or LDAP account. You don't need to replicate these accounts in Identity Platform but simply reference them when authenticating a user. See Work with Generic User Functions.

Get a list of current users

Before adding a new user, you can determine whether the user already exists by calling /Redrock/Query against the User Table to return list of current users.

/Redrock/query
{
"Script":"Select Username, ID from User ORDER BY Username COLLATE NOCASE"
}

The query returns the ID and name for all users similar to the one shown here:

{
  "success": true,
  "Result": 
  {
    "IsAggregate": false,
    "Count": 44,
    "Columns": [
      {
        "Name": "ID",
        "IsHidden": false,
        "DDName": "ID",
        "Title": "ID",
        "DDTitle": "ID",
        "Description": "Row Identifier (primary key)",
        "Type": 12,
        "Format": null,
        "Width": 0,
        "TableKey": "Primary",
        "ForeignKey": null
      },
      {
        "Name": "Username",
        "IsHidden": false,
        "DDName": "Username",
        "Title": "Username",
        "DDTitle": "Username",
        "Description": "User name.",
        "Type": 12,
        "Format": null,
        "Width": 0,
        "TableKey": "Alternate",
        "ForeignKey": null
      }
    ],
    "FullCount": 44,
    "Results": [
      {
        "Entities": [
          {
            "Type": "User",
            "Key": "e7ed3e73-d115-44f3-9553-4bcc1a4ecc05",
            "IsForeignKey": false
          }
        ],
        "Row": {
          "ID": "e7ed3e73-d115-44f3-9553-4bcc1a4ecc05",
          "Username": "auser1@qa.com"
        }
      },
      {
        "Entities": [
          {
            "Type": "User",
            "Key": "1ee22405-59b8-49a9-b64b-5b13aee592ce",
            "IsForeignKey": false
          }
        ],
        "Row": {
          "ID": "1ee22405-59b8-49a9-b64b-5b13aee592ce",
          "Username": "admin@abc1234"
        }
      },
       
  ...
    
   {
        "Entities": [
          {
            "Type": "User",
            "Key": "0ee88549-7c48-486d-a9f5-63cf9167890a",
            "IsForeignKey": false
          }
        ],
        "Row": {
          "ID": "0ee88549-7c48-486d-a9f5-63cf9167890a",
          "Username": "test2@ddog.com"
        }
      {
        "Entities": [
          {
            "Type": "User",
            "Key": "d9fed598-7f16-4305-aaa8-97a9f5c12c00",
            "IsForeignKey": false
          }
        ],
        "Row": {
          "ID": "d9fed598-7f16-4305-aaa8-97a9f5c12c00",
          "Username": "user1@ddog.com"
        }
      }
    ],
    "ReturnID": ""
  },
  "Message": null, "MessageID": null, "Exception": null, "ErrorID": null, "ErrorCode": null, "InnerExceptions": null
}

Create a user

Call /CDirectoryService/CreateUser to create a user.

Note the following about the parameters for this call:

  • Name requires a login suffix (doccraft in this example)
  • Password can be set to any arbitrary string because the user must reset it at the next login ("ForcePasswordChangeNext": true).
  • MobileNumber must be set in order to send an SMS invite ("SendSmsInvite": true).
  • Although InEverybodyRole is true by default, and InSysAdminRole is false by default, for clarity they are set explicitly to these values in the sample.
/CDirectoryService/CreateUser
{
"Name": "test3@doccraft",
"Mail": mike11@somemail.com,
"Password": "abcD1234",
"InEverybodyRole": true,
"InSysAdminRole": false,
"ForcePasswordChangeNext": true,
"SendEmailInvite": true,
"SendSmsInvite": true,
"MobileNumber": "987-654-3210"
}

A successful call to CreateUser returns a UUID for the new user, as shown here:

{
"success":true,
"Result":"899103e2-2309-4f5d-bb27-9523c21846cc",
"Message":null,"MessageID":null,"Exception":null,"ErrorID":null,"ErrorCode":null,"InnerExceptions":null
}

You pass this UUID to any subsequent calls to manage the user.

Update user information

Call /CDirectoryService/ChangeUser to modify a Cloud user account.

Pass the UUID of the user to update, and any fields that you want to update (if you omit ID, the function applies to the current user). For example, the following call updates the mobile number for the specified user:

/CDirectoryService/ChangeUser
{
"ID": "5f766478-7008-4826-a08a-c6a0f8efb18f",
"MobileNumber" "5105555555"
}

/CDirectoryService/ChangeUser changes the mobile number for the user account specified by the ID, and leaves all other fields with their current values.

Set user information

Identity Service provides specific functions to set the picture for a Cloud Directory account, or to lock, disable, or set a Cloud Directory account to expired:

For example, to lock an account (after too many failed logins), make a call such as the following:

/CDirectoryService/SetUserState
{
"ID": "5f766478-7008-4826-a08a-c6a0f8efb18f"
"state": "Locked"
}

You can reenable a locked account by setting the state to "None"; for example:

/CDirectoryService/SetUserState
{
"ID": "5f766478-7008-4826-a08a-c6a0f8efb18f"
"state": "None"
}

Delete a user

You can call /CDirectoryService/DeleteUser to delete a user from the cloud service. Specify either the name or UUID of the user to delete:

/CDirectoryService/DeleteUser
{
"ID": "5f766478-7008-4826-a08a-c6a0f8efb18f"
}

Create and Manage Cloud Directory Users