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:
-
Standard roles
: Standard admin roles contain sets of predefined permissions to resources that are provided by default in your Okta org. See
Standard administrator roles and permissions
for a list of permissions included in each standard admin role.
For standard role assignments, see the following principal-specific assignment APIs:
-
Custom roles
: You can create admin roles in your Okta org with specific
permissions
to access specific Okta
resources
.
For custom role assignments, follow these steps:
- Create a custom role .
- Create a resource set .
- Create a resource set binding with your custom role.
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. For a more detailed catalog of all available permissions, see Permissions.
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 |