Roles in Okta

Role assignment to principals grants them a specific set of access privileges. Principals can be users, groups of users, or client apps. When a role is assigned to a group, all members of the group automatically have the privileges granted by the role.

Roles can be one of the following types:

Note

A principal, with an assigned a custom role, can't add or remove the super admin (SUPER_ADMIN) standard role to or from another principal. This custom role operation isn't permitted regardless of the permissions for the custom role. For example, a service app with an assigned custom role can't make an API request to assign the super admin role to a group, even if the custom role has the okta.users.groupMembership.manage, okta.groups.manage, and okta.users.manage permissions.

IAM access to API resources

Okta recommends that you grant your principal (user, group, or client) least privilege access to API resources. To grant least privilege access, assign the principal a standard or custom admin role with minimal permissions.

The suggested standard admin roles and custom admin permissions are documented for some Okta API resource operations. For example, these admin roles and permissions are included in the Retrieve a user schema operation:

Admin roles: API_ACCESS_MANAGEMENT_ADMIN APP_ADMIN ORG_ADMIN

Permissions: okta.apps.manage

This indicates that you need to assign at least one of API_ACCESS_MANAGEMENT_ADMIN, APP_ADMIN, or ORG_ADMIN standard admin roles to your principal for them to access the operation for common use cases. Or if your principal is assigned a custom role, that custom role must include the okta.apps.manage permission for them to access the operation.

Note

When you create a custom service app in Okta, you must assign an admin role to your app since roles aren't automatically assigned to apps. See Assign admin roles to the OAuth 2.0 service app.

Standard roles

See Standard administrator roles and permissions for a list of permissions included in each standard admin role.

Role Label Optional targets
API_ACCESS_MANAGEMENT_ADMIN API Access Management Administrator
APP_ADMIN Application Administrator Apps
GROUP_MEMBERSHIP_ADMIN Group Membership Administrator Groups
HELP_DESK_ADMIN Help Desk Administrator Groups
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

IAM-based standard roles

You can assign IAM-based standard roles. These roles are immutable. You can't update or delete them.

Role Label Permissions     
ACCESS_CERTIFICATIONS_ADMIN Access Certifications Administrator okta.governance.accessCertifications.manage
ACCESS_REQUESTS_ADMIN Access Requests Administrator okta.governance.accessRequests.manage

Permissions

For custom roles, permissions allow the principal to perform tasks and access resources.

Note
  • Governance permissions are currently only supported as part of the Standard IAM-based roles . You can't use these to create or update other roles.
  • The okta.apps.manageFirstPartyApps permission is only supported as part of some Standard IAM-based roles . You can't use it to create or update other roles.
  • The okta.devices.* permissions are self-service Early Access . Turn on the Enable custom admin roles for device permissions feature from the Settings > Feature page in the Admin Console to access these permissions. See Enable self-service features .

The following permissions are supported in Okta.

Permission
 Description Applicable resources
okta.users.manage Allows the admin to create and manage users and read all profile and credential information for users. Delegated admins with this permission can only manage user credential fields and not the credential values themselves. All users, all users within a specific group
okta.users.create Allows the admin to create users. If the admin is also scoped to manage a group, that admin can add the user to the group on creation and then manage. All groups, a specific group
okta.users.read Allows the admin to read any user's profile and credential information. Delegated admins with this permission can only manage user credential fields and not the credential values themselves. All users, all users within a specific group
okta.users.credentials.manage Allows the admin to manage only credential lifecycle operations for a user All users, all users within a specific group
okta.users.credentials.resetFactors Allows the admin to reset MFA authenticators for users All users, all users within a specific group
okta.users.credentials.resetPassword Allows the admin to reset passwords for users All users, all users within a specific group
okta.users.credentials.expirePassword Allows the admin to expire a user's password and set a new temporary password All users, all users within a specific group
okta.users.userprofile.manage Allows the admin to only perform operations on the user object, including hidden and sensitive attributes All users, all users within a specific group
okta.users.lifecycle.manage Allows the admin to perform any user lifecycle operations All users, all users within a specific group
okta.users.lifecycle.activate Allows the admin to activate user accounts All users, all users within a specific group
okta.users.lifecycle.deactivate Allows the admin to deactivate user accounts All users, all users within a specific group
okta.users.lifecycle.suspend Allows the admin to suspend user access to Okta. When a user is suspended, their user sessions are also cleared. All users, all users within a specific group
okta.users.lifecycle.unsuspend Allows the admin to restore user access to Okta All users, all users within a specific group
okta.users.lifecycle.delete Allows the admin to permanently delete user accounts All users, all users within a specific group
okta.users.lifecycle.unlock Allows the admin to unlock users who have been locked out of Okta All users, all users within a specific group
okta.users.lifecycle.clearSessions Allows the admin to clear all active Okta sessions and OAuth 2.0 tokens for a user All users, all users within a specific group
okta.users.groupMembership.manage Allows the admin to manage a user's group membership (also need okta.groups.members.manage to assign to a specific group) All users, all users within a specific group
okta.users.appAssignment.manage Allows the admin to manage a user's app assignment (also need okta.apps.assignment.manage to assign to a specific app) All users, all users within a specific group
okta.users.apitokens.manage Allows the admin to manage API tokens All users, all users within a specific group
okta.users.apitokens.read Allows the admin to view API tokens All users, all users within a specific group
okta.groups.manage Allows the admin to fully manage groups in your Okta org All groups, a specific group
okta.groups.create Allows the admin to create groups All groups
okta.groups.members.manage Allows the admin to only manage member operations in a group in your Okta org All groups, a specific group
okta.groups.read Allows the admin to only read information about groups and their members in your Okta org All groups, a specific group
okta.groups.appAssignment.manage Allows the admin to manage a group's app assignment (also need okta.apps.assignment.manage to assign to a specific app) All groups, a specific group
okta.apps.read Allows the admin to only read information about apps and their members in your Okta org All apps, all apps of a specific type, a specific app
okta.apps.manage Allows the admin to fully manage apps and their members in your Okta org All apps, all apps of a specific type, a specific app
okta.apps.assignment.manage Allows the admin to manage assignment operations of an app in your Okta org and view the following provisioning errors: app assignment, group push mapping, and Error Profile push updates. All apps, all apps of a specific type, a specific app
okta.apps.clientCredentials.read Allows the admin to view information about client credentials for the app All apps, all apps of a specific type, a specific app
okta.profilesources.import.run Allows the admin to run imports for apps with a profile source, such as HRaaS and AD/LDAP apps. Admins with this permission can create users through the import. All apps, all apps of a specific type, a specific app
okta.authzServers.read Allows the admin to read authorization servers All authorization servers, a specific authorization server
okta.authzServers.manage Allows the admin to manage authorization servers All authorization servers, a specific authorization server
okta.customizations.read Allows the admin to read customizations All customizations
okta.customizations.manage Allows the admin to manage customizations All customizations
okta.identityProviders.read Allows the admin to read Identity Providers All Identity Providers
okta.identityProviders.manage Allows the admin to manage Identity Providers All Identity Providers
okta.workflows.read Allows the admin to view delegated flows All delegated flows, a specific delegated flow
okta.workflows.invoke Allows the admin to view and run delegated flows All delegated flows, a specific delegated flow
okta.governance.accessCertifications.manage Allows the admin to view and manage access certification campaigns All access certifications
okta.governance.accessRequests.manage Allows the admin to view and manage access requests All access requests
okta.apps.manageFirstPartyApps Allows the admin to manage first-party apps All access requests
okta.agents.manage Allows the admin to manage agent communication and agent updates All agents
okta.agents.register Allows the admin to register agents and domains All agents
okta.agents.view Allows the admin to download agents and view agent statuses All agents
okta.directories.manage
Allows the admin to manage all directory integration settings of an app instance All directory integrations, a specific type of directory integration, a specific directory integration
okta.directories.read
Allows the admin to view the directory integration settings of an app instance All directory integrations, a specific type of directory integration, a specific directory integration
okta.devices.manage
Allows the admin to manage devices and perform all device lifecycle operations All devices
okta.devices.lifecycle.manage
Allows the admin to perform any device lifecycle operations All devices
okta.devices.lifecycle.activate
Allows the admin to activate devices All devices
okta.devices.lifecycle.deactivate
Allows the admin to deactivate devices. When you deactivate a device, it loses all device user links. All devices
okta.devices.lifecycle.suspend
Allows the admin to suspend device access to Okta All devices
okta.devices.lifecycle.unsuspend
Allows the admin to unsuspend and restore device access to Okta All devices
okta.devices.lifecycle.delete
Allows the admin to permanently delete devices All devices
okta.devices.read
Allows the admin to read device details All devices
okta.iam.read Allows the admin to view roles, resources, and admin assignments All Identity and Access Management resources
okta.realms.manage
Allows the admin to view, create, and manage realms All realm resources
okta.realms.read
Allows the admin to view realms All realm resources
okta.support.cases.manage Allows the admin to view, create, and manage Okta Support cases All Okta Support cases opened by the admin

Resources

Okta resources are identified by either an Okta Resource Name (ORN) or an Okta API REST URL.

Note

Not all Okta resources have a corresponding Okta API.

Okta Resource Name (ORN)

The Okta Resource Name (ORN) uniquely identifies an Okta resource and has the following formats:

  • orn:{partition}:{service}:{yourOrgId}:{objectType}:{objectId}:contained_resources
  • orn:{partition}:{service}:{yourOrgId}:{objectType}:{appName}:{objectId}
  • orn:{partition}:{service}:{yourOrgId}:contained_resources
ORN variable Description
{partition} The Okta environment partition specific to your org (oktapreview for Preview environments and okta for Production environments)
{service} The service that the resource belongs to
{yourOrgId} The identifier for the tenant that's using the service. This is typically your org ID.
{objectType} The resource object that belongs to the service category
{objectId} The specific object identifier for objectType. For example, if you want to define a specific group for your resource, use orn:{partition}:directory:{yourOrgId}:groups:{groupId}.
{appName} The key name that describes the app definition. For example, if you want to define all apps with a specific app definition for your resource, use orn:{partition}:idp:{yourOrgId}:apps:{appName}.
contained_resource An optional literal that targets all resources within the container resource (only for supported resources). For example, orn:{partition}:directory:{yourOrgId}:groups:{groupId}:contained_resources targets all users within a specific group.

Supported resources

Directory service

Resource ORN Okta API REST URL
All users orn:{partition}:directory:{yourOrgId}:users https://{yourOktaDomain}/api/v1/users
All groups orn:{partition}:directory:{yourOrgId}:groups https://{yourOktaDomain}/api/v1/groups
A specific group orn:{partition}:directory:{yourOrgId}:groups:{groupId} https://{yourOktaDomain}/api/v1/groups/{groupId}
All users within a specific group orn:{partition}:directory:{yourOrgId}:groups:{groupId}:contained_resources https://{yourOktaDomain}/api/v1/groups/{groupId}/users
All devices
orn:{partition}:directory:{yourOrgId}:devices https://{yourOktaDomain}/api/v1/devices
All realms orn:{partition}:directory:{yourOrgId}:realms https://{yourOktaDomain}/api/v1/realms
A specific realm orn:{partition}:directory:{yourOrgId}:realms:{realmId} https://{yourOktaDomain}/api/v1/realms/{realmId}

Identity Provider service

Resource ORN Okta API REST URL
All apps orn:{partition}:idp:{yourOrgId}:apps https://{yourOktaDomain}/api/v1/apps
All Identity Providers orn:{partition}:idp:{yourOrgId}:identity_provider https://{yourOktaDomain}/api/v1/idps
All apps of a specific type orn:{partition}:idp:{yourOrgId}:apps:{appType} https://{yourOktaDomain}/api/v1/apps/?filter=name+eq+%22{targetAppType}%22
A specific app orn:{partition}:idp:{yourOrgId}:apps:{appType}:{appId} https://{yourOktaDomain}/api/v1/apps/{appId}
All authorization servers orn:{partition}:idp:{yourOrgId}:authorization_servers https://{yourOktaDomain}/api/v1/authorizationServers
A specific authorization server orn:{partition}:idp:{yourOrgId}:authorization_servers:{authorizationServerId} https://{yourOktaDomain}/api/v1/authorizationServers/{authorizationServerId}
All customizations orn:{partition}:idp:{yourOrgId}:customizations

Workflow service

Resource ORN Okta API REST URL
All delegated flows orn:{partition}:workflow:{yourOrgId}:flows
A specific delegated flow orn:{partition}:workflow:{yourOrgId}:flows:{flowId}

Governance service

Resource ORN Okta API REST URL
All access certifications orn:{partition}:governance:{orgId}:certifications
All access requests orn:{partition}:governance:{orgId}:requests

Identity and Access Management service

Resource ORN Okta API REST URL
All Identity and Access Management resources orn:{partition}:iam:{orgId}:contained_resources

Support service

Resource ORN Okta API REST URL
All Okta Support cases opened by the admin orn:{partition}:support:{orgId}:cases