POST Identity/AddGroup

Adds a group to an identity provider. The group or team resides in the local provider. However, members, which are Trust Protection Platform users or groups, can originate from a local, AD, or LDAP provider.

TIP  If you are logged into an AD or LDAP provider with View permission and Read permission, you can see local users and groups. Otherwise, call POST Identity/GetMembers.

Requirements

  • Permissions:  The caller must have Master Admin permission. However, results are limited to the identity provider that authenticated the caller. For example, if a LDAP caller tries to change information about an AD identity, the API call returns an empty JSON result.
  • Token scope:  Configuration:Manage

Headers

  • Content type: Content-Type:application/json.

  • Token: The bearer access token that you received. For example, Authorization:Bearer 4MyGeneratedBearerTknz==. For more information, see Passing a bearer token in your API calls.

Parameters

Input parameters

Name

Description

Name

Specify a PrefixedName for the new local group. For example, PrefixedName:local:Apache Team3.

Members

(Optional) An array of users and groups from one or more identity provider.

The syntax varies based on the identity provider. For more information, see Identity Information:

  • AD: Specify a value for PrefixedName or PrefixedUniversal.
  • LDAP: Specify a value for PrefixedName or PrefixedUniversal.
  • Local: Specify values for both a PrefixedName and PrefixedUniversal.
Products

(Optional) An array of Venafi product names: TLS, SSH, Code Signing.

Returns

Response description

Name

Description

ID

  • FullName:The Distinguished Name (DN) of the identity group.
  • IsGroup: The value is true if this instance is a group, otherwise false.
  • Name: The group name.
  • Prefix: The AD, LDAP or Identity provider. For more information, see Identity Information.
  • PrefixedName: The concatenated Prefix: and Group Name.
  • PrefixedUniversal: The concatenated Prefix: and Universal.
  • Type: The type of identity:
    • 1: User
    • 2: SecurityGroups
    • 8: DistributionGroups

      -OR-

    • [Combo value]. Any combination of identity types that are related to the Filter. For example: SecurityGroupsandDistributionGroups = 10.
  • Universal: The Universal Unique ID (UUID) that identifies a user or group identity. The formatting including curly braces depends on the settings from the identity provider. For example, Universal: {f32b5c37-c2d7-49aa-9ef4-2d38954a8b9b}.

Invalid Owners

Appears only if an individual or group is not currently a group owner:

  • Prefix: The identity provider prefix that manages the account or group Name. For more information, see Identity Information.
  • PrefixedName: The concatenated Prefix: and account Name. For more information, see Identity Information.
  • PrefixedUniversal: The concatenated Prefix: and Universal. For more information, see Identity Information.

InvalidMembers

Appears only if an individual or group member is missing from the identity tree.

  • Prefix: The identity provider prefix that manages the account or group Name. For more information, see Identity Information.
  • PrefixedName: The concatenated Prefix: and account Name. For more information, see Identity Information.
  • PrefixedUniversal: The concatenated Prefix: and Universal. For more information, see Identity Information.
Message

If the response is a HTTP 400, it only contains Message and the reason for failure. Omits all other return values.

  • A group or members are missing.
  • Either the group is not valid or all of the members are not valid.
  • The prefixed name of a group identity is missing.

Example: Create a local group and add existing users

Request for Example

POST https://tpp.venafi.example/vedsdk/Identity/AddGroup
Authorization:Bearer 4MyGeneratedBearerTknz==
{
   "Name":{
      "PrefixedName":"local:Apache Team4"
   },
   "Members":[
      {
         "PrefixedName":"AD+venqa:Bob"
      },
      {
         "PrefixedName":"local:TestUser2",
         "PrefixedUniversal":"local:{14d4b717-4981-4e8b-a808-b76f5f768233}"
      },
      {
         "PrefixedUniversal":"AD+venqa:11111a11111a11111a11111a1111111a"
      },
      {
         "PrefixedUniversal":"AD+venqa:30ea418420122f4c84d2490b991e1294"
      }
   ]
}

Response for Example

HTTP/1.1 200 OK
{
   "ID":{
      "FullName":"\\VED\\Identity\\Apache Team4",
      "IsGroup":true,
      "Name":"Apache Team4",
      "Prefix":"local",
      "PrefixedName":"local:Apache Team4",
      "PrefixedUniversal":"local:{f389989f-eb53-4b77-9ffa-620d8091cf20}",
      "Type":2,
      "Universal":"{f389989f-eb53-4b77-9ffa-620d8091cf20}"
   },
   "InvalidMembers":[
      {
         "Prefix":"AD+venqa",
         "PrefixedName":"AD+venqa:",
         "PrefixedUniversal":"AD+venqa:11111a11111a11111a11111a1111111a",
         "Universal":"11111a11111a11111a11111a1111111a"
      }
   ]
}