Activity - Create an environment administrator


Introduction and workflow tasks

This activity shows you how to assign an administrator to an environment who has the permissions to manage the environment, add populations, add users, and assign users to populations. The environment administrator needs both the Environment Admin role and the Identity Data Admin role to manage the environment and its users.

This scenario illustrates the following common operations supported by the PingOne for Customers APIs:

  • Get the environment ID
  • Create a population
  • Create a user
  • Assign roles to a user

Workflow order of operations

To designate an administrator for an environment, the following tasks must be completed successfully:

  1. Make a GET request to the /environments endpoint to get the environment resource ID.

  2. Make a POST request to /environments/{id}/populations to create a population resource for the administrators group.

  3. Make a POST request to /environments/{id}/users to create a user who will be assigned to the administrators population resource and granted environment admin-level permissions.

  4. Make a GET request to the /roles endpoint to return a list of all defined platform roles.

  5. Make a POST request to /environments/{id}/users/{id}/roleAssignments to assign to the specified user resource the roles needed to manage the environment.

Step 1: Get the environment ID

You can use the GET /environments endpoint to retrieve all environment resources associated with your organization.

curl -X GET "https://api.pingone.com/v1/environments" \
-H "Authorization: Bearer jwtToken"

The response data returns information about every environment referenced by your organization. For each environment resource, the data contains HAL links for related resources as well as the properties for the environment. The id property identifies the UUID for the environment resource. The response data for one environment resource is shown below:

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/"
        },
        "organization": {
            "href": "https://api.pingone.com/v1/organizations/ab6d7bc2-01bf-4e20-9479-3fd1b33c7b81"
        },
        "populations": {
            "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/populations"
        },
        "users": {
            "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/users"
        },
        "applications": {
            "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/applications"
        },
        "activities": {
            "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/activities"
        },
        "branding": {
            "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/branding"
        },
        "features": {
            "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/features"
        },
        "resources": {
            "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/resources"
        },
        "scopes": {
            "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/scopes"
        },
        "importTasks": {
            "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/importTasks"
        },
        "passwordPolicies": {
            "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/passwordPolicies"
        },
        "userActivities": {
            "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/userActivities"
        },
        "signOnPolicies": {
            "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/signOnPolicies"
        }
    },
    "id": "0bda42bc-d54f-449f-8d46-d5b8990c43ba",
    "name": "AU-Sandbox",
    "description": "Test Environment for the European Union region.",
    "organization": {
        "id": "460659d7-6c2f-4227-94da-9f0368ace5cd"
    },
    "type": "SANDBOX",
    "region": "EU",
    "createdAt": "2018-02-26T17:36:27.025Z",
    "updatedAt": "2018-02-26T17:36:27.025Z"
}

Step 2: Create a population

Before you create a user resource and assign administrator privileges to the user, you must create a population resource to associate with the user. You need the environment id property value returned in Step 1 to specify the environment resource in the request URL to create the population.

The request body for the POST must provide a value for the required name property.

The POST /environments/{environmentId}/populations/ creates a new population resource in the specified environment.

curl -X POST "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/populations/" \
-H "Content-type: application/json" \
-H "Authorization: Bearer jwtToken" \
-d "{
  "name" : "Administrators",
  "description" : "EU-Sandbox Environment administrators group",
}"

The response data returned for the new population resource looks like this:

{
  "id": "54ea015a-efc8-4169-9dee-3488f1fb8859",
  "environment": {
      "id": "0bda42bc-d54f-449f-8d46-d5b8990c43ba"
  },
  "name": "Administrators",
  "description": "EU-Sandbox Environment administrators group",
  "userCount": 0,
  "createdAt": "2018-04-26T17:13:34.498Z",
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/populations/"
        },
        "environment": {
            "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba"
        }
    }
}

Step 3: Create the user

Use the population id returned in Step 2 to create a new user resource, which is associated with the Administrators population.

The request body for the POST to create the new user must provide values for these required properties:

  • email

    The unique email address for the new user.

  • username

A name for the new user that must be unique within the specified environment.

  • population.id

The population to associate with the new user resource.

The POST /environments/{environmentId}/users operation creates the new user resource in the specified environment. The user is associated with a population identified by the population id generated in Step 2. The request URL specifies the environment id generated in Step 1.

curl -X "POST" "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/users" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \
-d $'{
  "username": "gracepotter",
  "email": "grace.potter@company.com"
  "population" : {
    "id" : "54ea015a-efc8-4169-9dee-3488f1fb8859"
    }
}'

The request body specifies values for the username, email, and population properties. The response data looks like this:

{
    "_links" : {
        "self" : {
          "href" : "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/users/2c820676-3f02-49fe-b3c6-0fd854e53d4e"
        },
        "password": {
            "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/users/2c820676-3f02-49fe-b3c6-0fd854e53d4e/password"
        },
        "password.reset": {
            "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/users/2c820676-3f02-49fe-b3c6-0fd854e53d4e/password"
        },
        "password.set": {
            "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/users/2c820676-3f02-49fe-b3c6-0fd854e53d4e/password"
        },
        "password.validate": {
            "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/users/2c820676-3f02-49fe-b3c6-0fd854e53d4e/password"
        },
        "password.recover": {
            "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/users/2c820676-3f02-49fe-b3c6-0fd854e53d4e/password"
        },
        "account.sendVerificationCode": {
            "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/users/2c820676-3f02-49fe-b3c6-0fd854e53d4e"
        }
    },
    "id": "2c820676-3f02-49fe-b3c6-0fd854e53d4e",
    "environment": {
        "id": "0bda42bc-d54f-449f-8d46-d5b8990c43ba"
    },
    "population": {
        "id": "54ea015a-efc8-4169-9dee-3488f1fb8859"
    },
    "username": "gracepotter",
    "name": {
        "family": "",
        "given": ""
    },
    "email": "grace.potter@company.com",
    "enabled": true,
    "lifecycle": {
        "status": "ACCOUNT_OK"
    },
    "mfaEnabled": false,
    "mobilePhone": "",
    "photoUrl": "",
    "createdAt": "2017-12-07T15:29:15.284Z",
    "updatedAt": "2017-12-07T15:29:15.284Z"
}

Step 4: Get roles

The permissions service provides functions to get role IDs and assign roles to users. To assign a role (and its corresponding permissions) to a user, you must get the role’s id.

The GET /roles operation returns each platform role, its id, name, and description. It also lists all permissions associated with the role.

curl -X GET "https://api.pingone.com/v1/roles" \
-H "Authorization: Bearer jwtToken"

The response data returned for the GET request displays a list of role resources. Note that this sample shows only the Environment Admin role and some of the permissions associated with it:

{
    "id": "1813bc13-8d13-4e88-a825-d40bfe82777b",
    "name": "Environment Admin",
    "description": "Environment Admin",
    "applicableTo": [
        "ENVIRONMENT"
    ],
    "permissions": [
        ...

        {
            "namespace": "orgmgt",
            "description": "Update environment"
        },
        {
            "namespace": "orgmgt",
            "description": "Create environment"
        },
        {
            "namespace": "orgmgt",
            "description": "Delete environment"
        },

        ...
    ],
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/roles/1813bc13-8d13-4e88-a825-d40bfe82777b"
        }
    }
}

Step 5: Assign roles to a user

After retrieving all the platform role IDs from the GET /roles request, you can use the POST /environments/{environmentId}/users/{userId}/roleAssignments operation to assign the Environment Admin role to the new user (actor). The request URL specifies the actor’s environment ID, actor type, and actor ID.

curl -X POST "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/users/2c820676-3f02-49fe-b3c6-0fd854e53d4e/roleAssignments" \
-H "Content-type: application/json" \
-H "Authorization: Bearer jwtToken" \
-d "{
  "role": {
    "id": "1813bc13-8d13-4e88-a825-d40bfe82777b",
  },
  "scope": {
    "id": "6a4fdba9-063b-4678-addc-268013acb27c",
    "type": "ENVIRONMENT"
  }
}"

In the request body, the role attribute specifies the ID of the role assigned to the actor. In this case, the assigned role is the Environment Admin role. The scope attribute provides the resource ID and resource type to designate the role assignment scope associated with this actor. In this case, the role type is ENVIRONMENT and the id attribute specifies the ID of the scope resource.

To assign this actor the Identity Data Admin role so that the new administrator can add and manage user resources within the scope of this environment, you can perform the same operation, but in this request you specify the ID for the Identity Data Admin role. The scope attribute is exactly the same.

curl -X POST "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/users/2c820676-3f02-49fe-b3c6-0fd854e53d4e/roleAssignments" \
-H "Content-type: application/json" \
-H "Authorization: Bearer jwtToken" \
-d "{
  "role": {
    "id": "0bd9c966-7664-4ac1-b059-0ff9293908e2",
  },
  "scope": {
    "id": "6a4fdba9-063b-4678-addc-268013acb27c",
    "type": "ENVIRONMENT"
  }
}"