On this page

    Role assignment

    As a super admin, you can assign admin permissions to principals so they're able to perform tasks and access resources. Principals can be users, groups of users, or client apps. You can assign standard roles, or create custom roles that limit an admin’s access to a subset of permissions (opens new window) and resources.

    This page discusses the concepts of role assignment through APIs. See Custom administrator roles (opens new window) for product documentation through the Admin Console.

    Standard role assignment

    Standard role types

    The following role types are provided and supported:

    Role type Label Optional targets
    API_ACCESS_MANAGEMENT_ADMIN API Access Management administrator
    APP_ADMIN Application administrator Apps
    GROUP_MEMBERSHIP_ADMIN Group membership administrator Groups (opens new window)
    HELP_DESK_ADMIN Help desk administrator Groups (opens new window)
    MOBILE_ADMIN Mobile administrator
    ORG_ADMIN Organization administrator
    READ_ONLY_ADMIN Read-only administrator
    REPORT_ADMIN Report administrator
    SUPER_ADMIN Super administrator
    USER_ADMIN Group administrator Groups (opens new window)

    IAM-based standard role Types

    Okta also supports the following IAM-based standard roles:

    Role type Label Permissions
    ACCESS_CERTIFICATIONS_ADMIN Access certifications administrator okta.governance.accessCertifications.manage
    ACCESS_REQUESTS_ADMIN Access requests administrator okta.governance.accessRequests.manage

    You can assign IAM-based standard roles using assignment operations for standard or custom roles. These roles are immutable, and you can't update or delete them.

    Standard Role Assignment steps

    Perform a standard role assignment:

    1. Assign a role to a user or group. The user now has access to the admin permissions and resources for the role.
    2. (Optional) If the role supports targets, use one of the target operations (user role targets (opens new window) or group role targets (opens new window)) to indicate which specific resource the admin can manage.

    The following are the entities involved in a standard role assignment:

    Custom role assignment

    You can build custom roles by selecting Permissions (opens new window). After a custom role is built, you can use its id or label to assign to admins:

    1. Create a custom role.
    2. Create a resource set.
    3. Bind the admin with the role from step one that targets the resource set from step two.

    An assignment of a role to an admin is called a Binding (opens new window), which you can identify by its unique ID. A binding represents a single unique combination of principal, resource set, and custom role. A given resource set can have multiple bindings. The resource allows for different combinations of principals and roles to grant permissions to the encompassing resource.

    Therefore, when dealing with custom roles, these three entities always exist:

    • Role: Identified by its label or id
    • Principal: Either a group or a user - known as a member of the binding
    • Resource set: Identified by its id

    Custom role assignment for IAM-based standard roles

    When using IAM-based standard roles the same concepts as custom roles apply with the following distinctions:

    • IAM-based standard roles can only be used with predefined resource sets.
    • For both IAM-based standard roles and resource sets, there’s a predefined constant id. This id is always the type of the role or resource set.
    Role id (type) Applicable resource set id (type)
    ACCESS_CERTIFICATIONS_ADMIN ACCESS_CERTIFICATIONS_IAM_POLICY
    ACCESS_REQUESTS_ADMIN ACCESS_REQUESTS_IAM_POLICY

    Resource sets

    A resource set is simply a collection of resources. There are two types of resource identifiers: an Okta Resource Name (ORN) or by a REST URL format.

    Okta Resource Name (ORN)

    The primary resource identifier is the ORN. ORNs uniquely identify Okta resources.

    ORN format

    ORN identifiers are in the following format:

    orn:{partition}:{service}:{tenantId}:{objectType}:{objectId}

    Partitions

    The partition is specific to your Okta environment. The following are the supported partitions:

    Partition ORN partition value
    Preview environments oktapreview
    Production environments okta
    Service

    The service that the resource belongs to. Each resource belongs to only one service. The following are the supported services:

    Service ORN service value
    Directory directory
    Identity Provider idp
    Workflow workflow
    Governance governance
    tenantId

    The identifier for the tenant that is using the service. This is typically your org ID (opens new window).

    objectType

    The object type that's specific to the service. For example, object types groups or users are used for the directory service. For examples of object types, see Supported resources.

    objectId

    The object's identifier. For examples of object identifiers, see Supported resources.

    contained_resources

    The contained_resources ORN property indicates to target all resources within the container resource. For example:

    orn:{partition}:directory:{yourOrgId}:groups:123:contained_resources

    Group 123 is the example container resource. Since :contained_resources is specified, the resource includes the users in the group, rather than the group itself.

    Not all resources support this property, see Supported resources for container resources.

    REST URL

    If the resource has a corresponding Okta API, you can specify the resource by its REST URL. Use the ORN format to specify resources that don't have corresponding Okta APIs.

    Supported resources

    Service Resource ORN identifier REST URL
    Directory All users orn:{partition}:directory:{yourOrgId}:users https://{yourOktaDomain}/api/v1/users (opens new window)
    All groups orn:{partition}:directory:{yourOrgId}:groups https://{yourOktaDomain}/api/v1/groups (opens new window)
    A specific group orn:{partition}:directory:{yourOrgId}:groups:{groupId} https://{yourOktaDomain}/api/v1/groups/{groupId} (opens new window)
    All users within a specific group orn:{partition}:directory:{yourOrgId}:groups:{groupId}:contained_resources https://{yourOktaDomain}/api/v1/groups/{groupId}/users (opens new window)
    All devices
    Early Access     		orn:{partition}:directory:{yourOrgId}:devices https://{yourOktaDomain}/api/v1/devices
    Identity Provider All apps orn:{partition}:idp:{yourOrgId}:apps https://{yourOktaDomain}/api/v1/apps (opens new window)
    All apps of a specific type orn:{partition}:idp:{yourOrgId}:apps:{appType} https://{yourOktaDomain}/api/v1/apps/?filter=name+eq+\"{targetAppType}\" (opens new window)
    A specific app orn:{partition}:idp:{yourOrgId}:apps:{appType}:{appId} https://{yourOktaDomain}/api/v1/apps/{appId} (opens new window)
    All authorization servers orn:{partition}:idp:{yourOrgId}:authorization_servers https://{yourOktaDomain}/api/v1/authorizationServers (opens new window)
    A specific authorization server orn:{partition}:idp:{yourOrgId}:authorization_servers:{authorizationServerId} https://{yourOktaDomain}/api/v1/authorizationServers/{authorizationServerId} (opens new window)
    All customizations orn:{partition}:idp:{yourOrgId}:customizations
    Workflows All delegated flows orn:{partition}:workflow:{yourOrgId}:flows
    A specific delegated flow orn:{partition}:workflow:{yourOrgId}:flows:{flowId}
    Governance All access certifications orn:partition:governance:orgId:certifications
    All access requests orn:partition:governance:orgId:requests

    Note: If you use a role with permissions that don't apply to the resources in the resource set, it doesn't affect the admin role. For example, the okta.users.userprofile.manage permission gives the admin no privileges if it’s granted to a resource set that only includes https://{yourOktaDomain}/api/v1/groups/{targetGroupId} resources. If you want the admin to be able to manage the users within the group, the resource set must include the corresponding https://{yourOktaDomain}/api/v1/groups/{targetGroupId}/users resource.

    Note: Governance resources are currently only supported as part of the Standard Resource Sets. You can't use these to create or update other resource sets. See IAM-based standard roles (opens new window).

    Binding member identifiers

    To specify binding members, use the REST URL of the corresponding Okta API:

    Early Access

    The following resource sets are currently supported out of the box and can be used to assign admins only when used with their associated roles. Standard resource sets and roles are always identified using their type as id.

    Resource set ID/type Applicable role ID/type Resources
    ACCESS_CERTIFICATIONS_IAM_POLICY ACCESS_CERTIFICATIONS_ADMIN All users, all groups, all Apps, all access certifications
    ACCESS_REQUESTS_IAM_POLICY ACCESS_REQUESTS_ADMIN all users, all groups, all access requests, access request app

    Only Okta manages standard resource sets, so you can't update or delete them.

    Custom vs. standard

    • An admin can have both standard role assignments and custom role bindings. Privileges granted to an admin are an aggregate of the following:

      • Standard roles directly assigned
      • Standard roles granted through group membership
      • Custom roles directly assigned
      • Custom roles granted through group membership

      As a result, if an admin was granted a standard role that is limited to a single group, and received group management privileges on all groups in the org through a custom role, the ultimate outcome is group management on all groups.

    • You can't assign a custom role without a resource set. The custom role is applicable only to a subset of resources. Standard roles, however, are initially granted to the entire org. You can only scope standard roles to specific resources by invoking target operations (user role targets (opens new window), group role targets (opens new window), or client role targets (opens new window)).

    Permission types

    See Permissions (opens new window) in the API documentation.

    Edit This Page On GitHub