Activity - Assign an administrator to a new environment


Introduction and workflow tasks

This activity shows you how to create a business domain for the European Union (EU) region in a global enterprise. The new environment resource needs an administrator 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 some common operations supported by the PingOne for Customers API services, including:

  • Creating an environment
  • Creating a population
  • Creating a user
  • Assigning roles to a user

Workflow order of operations

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

  1. Make a POST request to the /environments service to create the new environment resource.

  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 service 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: Create an environment

You can create an environment resource to define the new business region. The request body for the POST must provide values for these required properties:

  • name

    The name of the new environment resource. An environment name must be unique within its associated organization.

  • type

The type of environment, which defines the working domain or boundary for this environment. Options include: PRODUCTION or SANDBOX.

For this environment, the following optional properties are also defined:

  • Description

    A brief description of the environment.

  • region

    The geographic region that describes the area of business operations for this environment.

The POST /environments operation creates a new environment resource.

curl -X POST "https://api.pingone.com/v1/environments" \
-H "Content-type: application/json" \
-H "Authorization: Bearer jwtToken"
-d "{
  "name": "AU-Sandbox",
  "description": "Test Environment for the European Union region.",
  "region": "EU",
  "type": "SANDBOX",
}"

In this sample, the request body defines the name and description of the new environment. It also defines the environment’s region as EU and the environment type as SANDBOX.

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

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba"
        },
        "organization": {
            "href": "https://api.pingone.com/v1/organizations/ddb8e223-10a0-4b96-9298-d306ae84ef46"
        },
        "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"
        },
        "clients": {
            "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/clients"
        },
        "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": "{
        "_links": {
            "self": {
                "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba"
            },
            "organization": {
                "href": "https://api.pingone.com/v1/organizations/ddb8e223-10a0-4b96-9298-d306ae84ef46"
            },
            "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"
            },
            "clients": {
                "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/clients"
            },
            "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"
            }
        },",
    "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/{id}/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/{id}/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"
        },
        "environment": {
            "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba"
        },
        "population": {
            "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/populations/54ea015a-efc8-4169-9dee-3488f1fb8859"
        },
        "passwordState": {
            "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/users/2c820676-3f02-49fe-b3c6-0fd854e53d4e/password"
        }
    },
    "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",
    "password": "",
    "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 "Content-type: application/json" \
-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/{envUuid}/{actorType}/{actorUuid}/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 environment you created in Step 1.

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. It specifies the type as ENVIRONMENT and the id as the ID of the environment.

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