This article provides background on the required roles and permissions for the Lumos Okta integration.
There's no minimum plan or subscription required to connect the Okta integration. Super Administrator is recommend for full functionality, with options to configure the integration in a read-only manner.
If you choose to connect to Okta via an API token, it's important to note that an Okta API token inherits the permissions of the Okta user account that creates it. We recommend creating a dedicated Okta user account to connect the integration to Lumos, so that permissions aren't tied to a specific employee.
Using a Super Administrator role in Okta for the integration user will get you up + running in Lumos as quickly as possible!
If you want to limit scopes, you can create a custom Okta admin role for your integration.
However, it's worth noting that custom admin roles currently don't allow you to modify group memberships of Okta users who are super administrators. Any attempt to add or remove Super Administrators from Okta groups via Lumos will fail if you use a custom admin role. A Super Administrator role is also needed to list Admin roles in Okta. This is required if you want to view Okta admin roles in Lumos, which you might do during an Access Review. See 📄 Using Lumos for Access Reviews
To unlock the full functionality of Lumos, we need the following Okta roles:
Group Membership Administrator with the following options
Can administer all groups: Manage users, their profiles, and their credentials
Note: You can specify individual groups after selecting this role, but will need to maintain the list.
Application Administrator with the following options:
Can administer all applications: View and manage user permissions in an application.
Note: You can specify individual apps after selecting this role, but will need to maintain the list.
Report Administrator
The custom role needs the following permissions to unlock as much Lumos functionality as possible:
User Permissions
Edit users' lifecycle states
View users and their details
Edit users’ application assignments
Edit users' group membership
Group Permissions
View groups and their details
Manage group membership
App Permissions
Manage applications
View applications and their details
Edit application's user assignments
Read-Only Configuration
It's possible to connect Okta to Lumos with read only access, but you'll be unable to make any changes to users, groups, or applications. Additionally, Okta Admin Groups will not be synced without Super Admin.
This will prevent you from using the AppStore or removing app access automatically after an access review.
To do this, you will need the 2 roles:
Read Only Admin
A custom role with the following permissions and access to all resources:
View users' profile attributes
View applications and their details
View applications user assignments
The following scopes are requested via the OAuth integration. The user completing the OAuth connection must have the authorization (role + permissions) to grant the scopes being requested.
Any *.manage scope can be replaced with a read scope if read-only permissions for Lumos are desired.
When listing these scopes to connect the integration app within Lumos, be sure to use an empty space to separate each scope (not a comma).
More context on the scopes in Okta can be found here.
Scope | Context | Notes |
| Allows the app to create new users and to manage all users' profile and credentials information. | Can be replaced with |
| Allows the app to create and manage Apps in your Okta organization. | Can be replaced with |
| Allows the app to manage existing groups in your Okta organization. | Can be replaced with |
| Allows the app to read administrative role assignments for users in your Okta organization. | Â |
| Allows the app to read information about System Log entries in your Okta organization. | Â |
| Allows the app to read information about Schemas in your Okta organization. | Â |
The following scopes are requested via the API Services integration. The user completing the API Services connection must have the authorization (role + permissions) to grant the scopes being requested. In order to allow full syncing and provisioning capabilities, Super Administrator is required.
More context on the scopes in Okta can be found here. The following are scopes requested by Lumos:
Context | Notes | |
| Allows the app to create new users and to manage all users' profile and credentials information. | Can be replaced with |
| Allows the app to create and manage Apps in your Okta organization. | Can be replaced with |
| Allows the app to manage existing groups in your Okta organization. | Can be replaced with |
| Allows the app to read administrative role assignments for users in your Okta organization. | Â |
| Allows the app to read information about System Log entries in your Okta organization. | Â |
| Allows the app to read information about Schemas in your Okta organization. | Â |
Read Only Option
Lumos allows connecting a read-only scoped version using Okta's API Services.
To do this, you will need to create another role with permissions that are not granted through the Read-Only Admin role, with access to all resources:
View users' profile attributes
View applications and their details
View applications user assignments
Assign both the Read-Only Admin as well as the created role above to the user that will be used in connecting the integration.
If attempting to connect the integration as read only, enter the following in the scopes field:
okta.users.read okta.apps.read okta.groups.read okta.roles.read okta.logs.read okta.schema.read
Note, without Super Admin, Lumos cannot ingest Okta Admin Roles. If you would like to track those, the connecting user must be a Super Admin. Okta limits access to the approved scopes, which means that access for Lumos would be limited to only read operations, even with Super Admin as the configured role.
With this configuration, Lumos will not be able to make any changes in Okta directly. This may block further usage of AppStore and automated workflow usage.