Work with user roles


User roles

The ability to perform an action using PingOne APIs is determined by roles. For example, when you initiate a request to a PingOne endpoint, you must have the permissions required by the endpoint to execute the request. Permissions in PingOne are associated with the following roles:

  • Organization Admin

    The Organization Admin role provides user permissions to perform the following PingOne API operations:

    • Assign, read, and update organization resources.
    • Assign, create, delete, update, and promote environment resources.
  • Environment Admin

    The Environment Admin role provides user permissions to perform the following PingOne API operations:

    • Assign, create, delete, update, and promote environments
    • Assign identity resources
    • Read population resources
    • Read organization resources
    • Read and update password policy resources
    • Read and create notifications resources and email resources
    • Update and delete branding resources
    • Read audit reporting activities resources
    • Read and update sign-on policy resources
    • Read and update schema resources
  • Identity Data Admin

    The Identity Data Admin role provides user permissions to perform the following PingOne API operations:

    • Read, create, update, and delete user resources
    • Assign identity resources
    • Read, create, update and delete population resources
    • Update user password resources
    • Read user password state resources
    • Read password policy resources
    • Read audit reporting activities resources
    • Read schema resources
  • Client Application Developer

    The Client Application Developer role provides user permissions to perform the following PingOne API operations:

    • Assign, read, create, update, and delete application (client) resources
    • Read and update an application’s client_secret resources
    • Read create update, and delete application grant resources
    • Read, create, update, and delete resource entity resources
    • Read, create, update, and delete scope resources
    • Read schema resources

Roles are defined at a more granular level by the scope attribute. The role assignment scope identifies the type of platform resource that defines the scope, and the id of the specific resource to which the scope applies. The following sample shows the scope attribute, which includes the resource type and id attributes. In this case, the scope is restricted to the organization resource identified by its id.

"scope": {
   "id": "d928aa51-c194-4333-9cf5-0fd0c9b7d62f",
   "type": "ORGANIZATION"
 }

Role assignment scope types include:

  • Platform

    This scope type designates a platform-level assignment scope for the role.

  • Organization

    This scope type designates an organization resource as the assignment scope of the role.

  • Environment

    This scope designates an environment resource as the assignment scope of the role.

  • Population

    This scope designates a population resource as the assignment scope of the role.

  • Actor

    This scope designates an actor resource (users or applications) as the assignment scope of the role.

Get all platform roles

You can get a list of all the defined roles in the PingOne platform available for assignment.

The following sample shows the GET /roles operation to return each platform role and the list of all permissions associated with the role.

curl -vX GET "https://api.pingone.com/v1/roles" \
-H "Content-type: application/json" \
-H "Authorization: Bearer jwtToken"

If you want to get information on just one specific platform role, the GET /roles/{id} operation returns the role name, description, ID, and the list of permissions associated with the role ID you submitted in the request.

curl -vX GET "https://api.pingone.com/v1/roles/1813bc13-8d13-4e88-a825-d40bfe82777b" \
-H "Content-type: application/json" \
-H "Authorization: Bearer jwtToken"

The response data for a specific role looks like this:

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

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

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

Assign a new role to a user

The permissions service provides operations to view all roles defined in the platform and manage the roles assigned to specific actors. When you assign a role to an actor, you provide the attribute values required to identify the role and designate the role assignment scope for this actor.

The following sample shows the POST /environments/{envUuid}/{actorType}/{actorUuid}/roleAssignments operation to update the role assignment for the actor in the specified environment resource.

curl -vX POST "https://api.pingone.com/v1/environments/f29547a1-841c-45f8-977e-00d0fdb73ede/users/c521265e-a6dd-4a15-8156-2b8d13382f1f/roleAssignments" \
-H "Content-type: application/json" \
-H "Authorization: Bearer jwtToken" \
-d "{
  "role": {
    "id": "1813bc13-8d13-4e88-a825-d40bfe82777b",
  },
  "scope": {
    "id": "d928aa51-c194-4333-9cf5-0fd0c9b7d62f",
    "type": "ORGANIZATION"
  }
}"

The request URL identifies the environment ID, actor type (users), and actor ID. The request body specifies the role ID and the scope attribute values. The scope attribute provides the resource ID and resource type to designate the role assignment scope associated with this actor. In this sample, the scope type is ORGANIZATION and the specific organization to which the role assignment scope applies is specified in the id value.

View all roles assigned to a user

Actors in PingOne can be assigned one or more roles. You can view the roles assigned to a specific actor, and you can view the role assignment scopes that define the limitations of each role.

The GET /environments/{envUuid}/{actorType}/{actorUuid}/roleAssignments operation returns the list of roles assigned to the actor identified by the actor’s ID.

curl -vX GET "https://api.pingone.com/v1/environments/f29547a1-841c-45f8-977e-00d0fdb73ede/users/c521265e-a6dd-4a15-8156-2b8d13382f1f/roleAssignments" \
-H "Content-type: application/json" \
-H "Authorization: Bearer jwtToken"

The request URL identifies the environment ID, actor type, and the actor’s ID.

The response data for an actor with more than one role looks like this. Note that the list of permissions for the roles in this sample has been edited. The data returned from this GET request will show every permission assigned to each role.

{
  "count" : 4,
  "size" : 4,
  "_links" : {
    "self" : {
      "href" : "https://api.pingone.com/environments/76777665-61cb-415a-b0f7-3c6f7a7235c3/users/986ab733-6dc8-4d3b-bc66-0cdaaed00e1f/roleAssignments"
    }
  },
  "_embedded" : {
    "roleAssignments" : [ {
      "id" : "170e554e-dd6f-427f-9115-a253e3cf3911",
      "role" : {
        "id" : "0bd9c966-7664-4ac1-b059-0ff9293908e2",
        "name" : "Identity Data Admin",
        "description" : "Identity Data Admin",
        "applicableTo" : [ "POPULATION", "ENVIRONMENT" ],
        "permissions" : [
         {
          "namespace" : "dir",
          "description" : "Read users"
         }
        ]
      },
      "actor" : {
        "id" : "986ab733-6dc8-4d3b-bc66-0cdaaed00e1f",
        "environmentId" : "76777665-61cb-415a-b0f7-3c6f7a7235c3",
        "type" : "USER"
      },
      "scope" : {
        "id" : "07267d87-8b3f-4524-8175-b5dacd221121",
        "type" : "ENVIRONMENT"
      }
    }, {
      "id" : "97898b41-914f-477e-88ae-df57f51ea57c",
      "role" : {
        "id" : "29ddce68-cd7f-4b2a-b6fc-f7a19553b496",
        "name" : "Environment Admin",
        "description" : "Environment Admin",
        "applicableTo" : [ "ORGANIZATION", "ENVIRONMENT" ],
        "permissions" : [
        {
          "namespace" : "dir",
          "description" : "Delete populations"
        }
        ]
      },
      "actor" : {
        "id" : "986ab733-6dc8-4d3b-bc66-0cdaaed00e1f",
        "environmentId" : "76777665-61cb-415a-b0f7-3c6f7a7235c3",
        "type" : "USER"
      },
      "scope" : {
        "id" : "07267d87-8b3f-4524-8175-b5dacd221121",
        "type" : "ENVIRONMENT"
      }
    }, {
      "id" : "26299e68-1c9d-40ba-801f-eb8d42d6f748",
      "role" : {
        "id" : "0bd9c966-7664-4ac1-b059-0ff9293908e2",
        "name" : "Identity Data Admin",
        "description" : "Identity Data Admin",
        "applicableTo" : [ "POPULATION", "ENVIRONMENT" ],
        "permissions" : [
        {
          "namespace" : "dir",
          "description" : "Update users"
        }
       ]
      },
      "actor" : {
        "id" : "986ab733-6dc8-4d3b-bc66-0cdaaed00e1f",
        "environmentId" : "76777665-61cb-415a-b0f7-3c6f7a7235c3",
        "type" : "USER"
      },
      "scope" : {
        "id" : "1c6a8c00-04e8-4573-9b32-64d6d107548c",
        "type" : "ENVIRONMENT"
      }
    }, {
      "id" : "61a7abee-1290-4633-ad97-e98c6366107c",
      "role" : {
        "id" : "29ddce68-cd7f-4b2a-b6fc-f7a19553b496",
        "name" : "Environment Admin",
        "description" : "Environment Admin",
        "applicableTo" : [ "ORGANIZATION", "ENVIRONMENT" ],
        "permissions" : [
        {
          "namespace" : "api_client_config",
          "description" : "Update or Reset secret for Client"
        }
       ]
      },
      "actor" : {
        "id" : "986ab733-6dc8-4d3b-bc66-0cdaaed00e1f",
        "environmentId" : "76777665-61cb-415a-b0f7-3c6f7a7235c3",
        "type" : "USER"
      },
      "scope" : {
        "id" : "1c6a8c00-04e8-4573-9b32-64d6d107548c",
        "type" : "ENVIRONMENT"
      }
    } ]
  }
}

The response data also shows that this actor has two roles: Environment Admin and Identity Data Admin. In addition, each of these roles is defined by two role assignment scopes. The JSON excerpt below shows the two role assignment scopes for the Identity Data Admin role.

"_embedded" : {
  "roleAssignments" : [ {
    "id" : "170e554e-dd6f-427f-9115-a253e3cf3911",
    "role" : {
      "id" : "0bd9c966-7664-4ac1-b059-0ff9293908e2",
      "name" : "Identity Data Admin",
      "description" : "Identity Data Admin",
      "applicableTo" : [ "POPULATION", "ENVIRONMENT" ],
      "permissions" : [
       {
        "namespace" : "dir",
        "description" : "Read users"
       }
      ]
    },
    "actor" : {
      "id" : "986ab733-6dc8-4d3b-bc66-0cdaaed00e1f",
      "environmentId" : "76777665-61cb-415a-b0f7-3c6f7a7235c3",
      "type" : "USER"
    },
    "scope" : {
      "id" : "07267d87-8b3f-4524-8175-b5dacd221121",
      "type" : "ENVIRONMENT"
    }
  }, {
    "id" : "26299e68-1c9d-40ba-801f-eb8d42d6f748",
    "role" : {
      "id" : "0bd9c966-7664-4ac1-b059-0ff9293908e2",
      "name" : "Identity Data Admin",
      "description" : "Identity Data Admin",
      "applicableTo" : [ "POPULATION", "ENVIRONMENT" ],
      "permissions" : [
      {
        "namespace" : "dir",
        "description" : "Read users"
      }
     ]
    },
    "actor" : {
      "id" : "986ab733-6dc8-4d3b-bc66-0cdaaed00e1f",
      "environmentId" : "76777665-61cb-415a-b0f7-3c6f7a7235c3",
      "type" : "USER"
    },
    "scope" : {
      "id" : "1c6a8c00-04e8-4573-9b32-64d6d107548c",
      "type" : "ENVIRONMENT"
    }
   }
  } ]
}

The id attribute for each scope attribute specifies a different environment resource ID.