Managing Active Directory users

Administrators can access the users endpoint to create and manage user accounts and groups that authenticate by using Microsoft Active Directory (AD).

Prerequisites

To enable AD you must specify either an AD domain, an AD server, or both. Turbonomic uses this connection for all AD users.

Use a secure connection to communicate with AD servers. The AD domain must be configured to use LDAPS, and you must import a certificate into the Turbonomic server. Turbonomic can support LDAP channel binding and LDAP signing. To support these Active Directory features, you must configure secure access.

For more information, see Enforcing Secure Access.

To connect to an AD server, make a POST request to the users/ldap endpoint. Configure your request with the following parameters:

domainName: Specify the domain for AD authentication.

To authenticate AD groups, specify a domain so that AD can find a user with the User Principal Name (UPN). If you specify a domain, but not a server, authentication uses any AD server from that domain. If you want to support only AD users and not groups, the domain is optional.
loginProviderURI: Specify the server for AD authentication.

To disable AD groups, specify a server but do not specify a domain. If you specify a domain and a server, authentication uses that server and also supports groups.

When you configure an AD server, by default Turbonomic assumes the AD server port to be 389 or 636. To specify a custom port for the AD server, add the port number to the AD server IP address. For example, 10.10.10.123:444 sets port 444.
isSecure: Specify true for this setting to enable a secure connection to the AD server.

Use a secure connection to communicate with AD servers. The AD domain must be configured to use LDAPS, and you must import a certificate into the Turbonomic server. Turbonomic can support LDAP channel binding and LDAP signing. To support these Active Directory features, you must configure secure access.

For more information, see Enforcing Secure Access.

Example:

POST https://10.10.10.10/api/v3/users/ldap

Example input:

{
  "loginProviderURI": "10.10.10.123:444",
  "isSecure": "true"
}

To get information about the currently configured AD server and AD groups, make a GET request to the users/ldap endpoint.

Example:

GET https://10.10.10.10/api/v3/users/ldap

Response:

[
  {
    "loginProviderURI": "ldaps://10.10.10.123:444",
    "isSecure": true,
    "groups": [
      {
        "uuid": "adGroup",
        "displayName": "adGroup",
        "type": "DedicatedCustomer",
        "roleName": "ADVISOR"
      },
      {
        "uuid": "administrator",
        "displayName": "administrator",
        "type": "DedicatedCustomer",
        "roleName": "ADMINISTRATOR"
      },
      {
        "uuid": "advisor",
        "displayName": "advisor",
        "type": "DedicatedCustomer",
        "roleName": "ADVISOR"
      },
      {
        "uuid": "automator",
        "displayName": "automator",
        "type": "DedicatedCustomer",
        "roleName": "AUTOMATOR"
      },
      {
        "uuid": "deployer",
        "displayName": "deployer",
        "type": "DedicatedCustomer",
        "roleName": "DEPLOYER"
      },
      {
        "uuid": "guyexternalgrouptest",
        "displayName": "guyexternalgrouptest",
        "type": "DedicatedCustomer",
        "roleName": "OBSERVER"
      },
      {
        "uuid": "observer",
        "displayName": "observer",
        "type": "DedicatedCustomer",
        "roleName": "OBSERVER"
      },
      {
        "uuid": "operational_observer",
        "displayName": "operational_observer",
        "type": "DedicatedCustomer",
        "roleName": "OPERATIONAL_OBSERVER"
      },
      {
        "uuid": "site_admin",
        "displayName": "site_admin",
        "type": "DedicatedCustomer",
        "roleName": "SITE_ADMIN"
      },
      {
        "uuid": "testgroop",
        "displayName": "testgroop",
        "type": "DedicatedCustomer",
        "roleName": "OBSERVER"
      }
    ]
  }
]

Adding AD Users

To add an AD user, make a POST request to the users endpoint. The following parameters are required:

username: Specify a username for the account. The username must be a valid User Principal Name (UPN). For example, john@corp.mycompany.com.
roles: Specify a user role to grant the user access to specific Turbonomic features.
loginProvider: For an AD user, specify LDAP.
type: Specify DedicatedCustomer.

Optionally, you can specify one or more scopes for the user, which limit what the user can monitor in your environment. For example, you can scope to a group that contains only the physical machines that support this user’s VMs or applications. This parameter is not valid for users who are in the ADMINISTRATOR role.

scope: Specify one or more scopes by using the numeric UUID value for each scope. To get a list of the groups that are available to scope to in your Turbonomic instance, along with their display names and UUIDs, make a GET request to the /search endpoint, for example:
```
GET https://10.10.10.10/api/v3/search?types=Group
```

For more information about user roles and scopes, see Managing user accounts.

Example:

POST https://10.10.10.10/api/v3/users

Example input

{
  "username": "john@corp.mycompany.com",
  "roles": [
    {
      "name": "DEPLOYER"
    }
  ],
  "loginProvider": "LDAP",
  "type": "DedicatedCustomer"
  "scope": [
  {
    "uuid":"286125332284065"
  },
  {
    "uuid":"266725335284010"
  }
 ]
}

Response:

{
  "uuid": "4776186363888",
  "displayName": "john@corp.mycompany.com",
  "username": "john@corp.mycompany.com",
  "roles": [
    {
      "name": "DEPLOYER"
    }
  ],
  "loginProvider": "LDAP",
  "type": "DedicatedCustomer",
  "scope": [
    {
      "uuid": "286125332284065",
      "isStatic": true,
      "logicalOperator": "AND",
      "groupClassName": "GroupApiDTO"
    },
    {
      "uuid": "266725335284010",
      "isStatic": true,
      "logicalOperator": "AND",
      "groupClassName": "GroupApiDTO"
    }
  ],
  "showSharedUserSC": false
}

Maintaining AD Users

To edit the details of an existing user or to delete a user, you must know the UUID value for the user.

To get a list of all the currently configured user accounts, make a GET request to the users endpoint:

GET https://10.10.10.10/api/v3/users

The API returns an array of UserApiDTO objects. Each UserApiDTO object contains the universal unique identifier (UUID), display name, username, encoded password, roles, scope, and other details about a user account.

Response:

[
  {
    "uuid": "0000000000111",
    "displayName": "extTestUser",
    "username": "extTestUser",
    "roles": [
      {
        "name": "DEPLOYER"
      }
    ],
    "loginProvider": "LDAP",
    "type": "DedicatedCustomer",
    "showSharedUserSC": false
  },
  {
    "uuid": "0000000000112",
    "displayName": "externaluser1",
    "username": "externaluser1",
    "roles": [
      {
        "name": "OBSERVER"
      }
    ],
    "loginProvider": "LDAP",
    "type": "DedicatedCustomer",
    "showSharedUserSC": false
  },
  {
    "uuid": "0000000000113",
    "displayName": "administrator",
    "username": "administrator",
    "roles": [
      {
        "name": "ADMINISTRATOR"
      }
    ],
    "loginProvider": "Local",
    "type": "DedicatedCustomer",
    "showSharedUserSC": false
  },
  {
    "uuid": "0000000000114",
    "displayName": "newTestUser",
    "username": "newTestUser",
    "roles": [
      {
        "name": "DEPLOYER"
      }
    ],
    "loginProvider": "Local",
    "type": "DedicatedCustomer",
    "showSharedUserSC": false
  }
]

To get details about a specific user, append the UUID of the user to the request:
```
GET https://10.10.10.10/api/v3/users/0000000000111
```
To get information about the currently logged-in user, append /me to the request:
```
GET https://10.10.10.10/api/v3/users/me
```

To edit the details for a user, make a PUT request to the users endpoint and include the user's UUID:
```
PUT https://10.10.10.10/api/v3/users/0000000000111
```
The following parameters are required, regardless of whether you want to modify them:
- username
- roles
- loginProvider
- type
Include the required parameters in the request body and specify the values that you want to modify. In the following example, the role for the extTestUser user is changed from DEPLOYER to OBSERVER. The other parameters remain unchanged.
Example:
```
{
  "username": "extTestUser",
  "roles": [
    {
      "name": "OBSERVER"
    }
  ],
  "loginProvider": "LDAP",
  "type": "DedicatedCustomer"
}
```
Response:
```
{
  "uuid": "0000000000111",
  "displayName": "extTestUser",
  "username": "extTestUser",
  "roles": [
    {
      "name": "OBSERVER"
    }
  ],
  "loginProvider": "LDAP",
  "type": "DedicatedCustomer",
  "showSharedUserSC": false
}
```
To delete a user, make a DELETE request to the users endpoint and include the user's UUID:
```
DELETE https://10.10.10.10/api/v3/users/0000000000111
```

Adding AD Groups

To add an AD group, make a POST request to the /users/ldap/groups endpoint. The following parameters are required:

displayName: Specify the name of the group. The group name must match a group that is accessible from the AD domain and servers that you configured for your Turbonomic instance.
roleName: Specify a role to grant group members access to specific Turbonomic features.
type: Specify DedicatedCustomer.

Optionally, you can specify one or more scopes for the group, which limit what the group can monitor in your environment. For example, you can scope to a group that contains only the physical machines that support this group’s VMs or applications. This parameter is not valid for groups that are in the ADMINISTRATOR role.

scope: Specify one or more scopes by using the numeric UUID value for each scope. To get a list of the groups that are available to scope to in your Turbonomic instance, along with their display names and UUIDs, make a GET request to the /search endpoint, for example:
```
GET https://10.10.10.10/api/v3/search?types=Group
```

For more information about user roles and scopes, see Managing user accounts.

Example:

POST https://10.10.10.10/api/v3/users/ldap/groups

Example input:

{
  "displayName: "myAdGroup",  
  "rolename": "DEPLOYER",
  "type": "DedicatedCustomer"
}

Response:

curl -X 'POST' \
  'https://10.10.10.10/api/v3/users' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "uuid": "myAdGroup",
  "displayName: "myAdGroup", 
  "rolename": "DEPLOYER", 
  "type": "DedicatedCustomer"
}'

Note:

If a user is a member of multiple groups, then Turbonomic logs the user on via the first SSO or AD that successfully authenticates the user. Also, Turbonomic does not support nested AD groups. AD logins must be for users in an upper-level group.

Maintaining AD Groups

To edit the details of an existing AD group or to delete an AD group, you must know the UUID value for the group.

To get a list of all the currently configured AD groups, make a GET request to the users/ldap/groups endpoint:
```
GET https://10.10.10.10/api/v3/users/ldap/groups
```
The API returns an array of ActiveDirectoryApiDTO objects. Each ActiveDirectoryGroupApiDTO object contains the UUID, role, and other details about a group.
To edit the details for a group, make a PUT request to the users/ldap/groups endpoint.
```
PUT https://10.10.10.10/api/v3/users/ldap/groups
```
The following parameters are required in the request body, regardless of whether you want to modify them:
- displayName
- roles
- type
Include the required parameters in the request body and specify the values that you want to modify. In the following example, the role for the myAdGroup group is changed from DEPLOYER to OBSERVER. The other parameters remain unchanged:
Example input:
```
{
  "displayName": "myAdGroupr",
  "rolename": "OBSERVER", 
  "type": "DedicatedCustomer"
}
```

Response:

{ 
"uuid": "mySsoGroup", 
"displayName": "mySsoGroup", 
"type": "DedicatedCustomer", 
"roleName": "DEPLOYER" }

To delete a group, make a DELETE request to the users/ldap/groups endpoint and include the group's UUID:
```
DELETE https://10.10.10.10/api/v3/users/ldap/groups/myADgroup
```