Okta Capabilities
Last updated: October 8, 2024
After this article...
You'll understand the capabilities our Okta integration provides, and how Lumos interacts with the Okta API.
View users
The mapping between Okta user statuses and Lumos user account statuses is below.
Reconciling Account Status
When you're reviewing the Okta app in Lumos, you'll see a list of users and their Okta account status.
The table below provides a mapping between Okta user account status and Lumos user status.
Okta User Status | Lumos Account Status |
Suspended | Suspended |
Deprovisioned | Deprovisioned |
Deleted (Okta no longer has a user) | Deprovisioned |
Anything else (Active, Staged, etc.) | Active |
Reconciling Employment Status
If you're using Okta as a User Source (see📄 Importing User Sources), Lumos will set the Employment Status value for a Lumos User from Okta using the following logic.
Okta User Status | Lumos User Employment Status |
Suspended | Suspended |
Deprovisioned | Inactive |
Deleted (Okta no longer has a user) | Inactive |
Anything else (Active, Staged, etc.) | Active |
Okta API endpoint: https://developer.okta.com/docs/reference/api/users/#list-users (we parse the User's status field)
Since Okta doesn't return "Deprovisioned" users by default, we make dedicated API calls to retrieve these user identities as well (we modify the base query with the following filter: /users?filter=status eq "DEPROVISIONED"
View a user's entitlements
Lumos can retrieve the following user entitlements from Okta.
Role - The role(s) assigned to the user's Okta account.
Groups - The Okta Groups to which the user is assigned.
The Role column will only appear if your Okta API token was created by a Super Administrator!
Okta API endpoints:
Role: https://developer.okta.com/docs/reference/api/roles/#list-roles-assigned-to-a-user
Groups: https://developer.okta.com/docs/reference/api/users/#request-parameters-8
View last login
In Lumos, the Last Login value for an Okta user account represents the last time the user logged into...Okta.
Okta API endpoint: https://developer.okta.com/docs/reference/api/users/#list-users (we get the lastLogin for the user)
Suspend a user
AppStore | Offboarding | Access Reviews | License Management |
N/A | ✅ | ✅ | ✅ |
In Lumos, suspending a Okta user marks their Account Status as "Suspended".
In Okta, this action deletes their sessions and suspends their account. This prevents them from logging into Okta. A suspended user's group and app assignments are retained.
This action reclaims a license in Okta.
Okta API endpoints:
Clearing user sessions: https://developer.okta.com/docs/api/openapi/okta-management/management/tag/User/#tag/User/operation/revokeUserSessions
Suspending the user: https://developer.okta.com/docs/api/openapi/okta-management/management/tag/User/#tag/User/operation/suspendUser
Deprovision a user
AppStore | Offboarding | Access Reviews | License Management |
N/A | ✅ | ✅ | ✅ |
In Lumos, deprovisioning a Okta user marks their Account Status as "Deprovisioned".
In Okta, the user is unassigned from all apps and groups to which they're assigned, with the exception of the Everyone group (from which a user cannot be removed). After this, the user's Okta account is deactivated (set to DEPROVISIONED).
If your organization has a Group rule that assigns the user to two or more groups, the deprovision step will require manual steps. If you want the deprovisioning flow to ignore Okta errors related to managed group rules(s), please contact our support team.
This action reclaims a license in Okta.
Okta API endpoints:
Get all groups assigned to a user: https://developer.okta.com/docs/reference/api/users/#request-parameters-8
Delete user from a group: https://developer.okta.com/docs/reference/api/groups/#remove-user-from-group (this only operates on native Okta groups, not groups managed in other sources (like Active Directory).
Get all apps assigned to a user: https://developer.okta.com/docs/reference/api/apps/#list-applications-assigned-to-a-user
Delete user from an app: https://developer.okta.com/docs/reference/api/apps/#remove-user-from-application
Get apps assigned to a group: https://developer.okta.com/docs/reference/api/groups/#list-assigned-applications
Change user assignment type: https://developer.okta.com/docs/reference/api/apps/#assign-user-to-application-for-sso-and-provisioning (we specify {'scope': 'USER'} to change the user's assignment type on an app from group-based to individually-assigned if we're unassigning a user from an app and the app is assigned via a group that provides access to multiple apps [context])
Delete user: https://developer.okta.com/docs/reference/api/users/#delete-user (if we see the user is already `DEPROVISIONED`, we do nothing)
View managed application assignments and activity
Lumos surfaces all of the applications that you manage in Okta in the Apps tab and the users assigned to them in the Accounts tab for a given application.
For each Okta-managed application user account, Lumos shows the following key fields.
Account Status
The provisioning status of the user's account in the service provider, as reported by Okta.
Okta User Application Status | Lumos Account Status |
Staged | Staged |
Provisioned | Access Created |
Active | Active |
Inactive | Deprovisioned |
Deprovisioned | Deprovisioned |
N/A (Okta no longer returns an account to us, but it did at one point) | Suspended |
Okta API docs: https://developer.okta.com/docs/reference/api/apps/#application-user-status (this comes from the status for the user's application assignment)
Last Login
This represents the last time the user tried to log into an app via Okta.
A few notes on Last Login data for Okta-managed apps:
Successful and unsuccessful login attempts are both counted as "login" attempts
When you first integrate Okta with Lumos, we check the last 120 days of login attempts. After the first sync of login data, each subsequent sync looks for events since the last sync.
We only filter for SSO login attempts, so last login data will not be available for apps where SSO sign-in is not in place.
When you first integrate Okta with Lumos, we look back 120 days to pull login attempts.
Okta API endpoint: https://developer.okta.com/docs/reference/api/system-log/#list-events (we apply a filter to get SSO login attempts: filter=eventType+eq+"user.authentication.sso)
Groups
These are the Okta Groups to which an employee is assigned that grant access to this app. If this value is blank, the user is directly assigned to the app.
Okta API endpoints:
https://developer.okta.com/docs/reference/api/apps/#list-users-assigned-to-application
https://developer.okta.com/docs/reference/api/apps/#list-groups-assigned-to-application
https://developer.okta.com/docs/reference/api/groups/#list-groups (we filter and only show groups of the type OKTA_GROUP)
https://developer.okta.com/docs/reference/api/groups/#list-group-members
Assign users to managed applications and groups
AppStore | Offboarding | Access Reviews | License Management |
✅ | ❌ | ❌ | ✅* |
* Only in Inactivity Workflows
Lumos can automatically assign users to applications or groups managed in Okta in multiple contexts.
The table below summarizes the different scenarios where users can be added to Okta apps or groups in Lumos.
Situation | What happens | Okta API endpoint |
When someone is approved for access to a permission linked to an Okta group via the AppStore. | Lumos assigns the user to the Okta group | |
When someone is approved for access to an Okta app via the AppStore (not a permission). | Lumos assigns the user to the Okta app | |
When the removal workflow for an Inactivity Workflow includes an | Lumos assigns the user to the Okta group |
Unassign users from managed applications and groups
AppStore | Offboarding | Access Reviews | License Management |
✅ | ✅ | ✅ | ✅ |
Lumos can unassign users from Okta apps and groups that provide access to applications.
If you try to unassign a user from an Okta group that provides access to multiple apps via a group rule, the removal will fail in Lumos and removing access will require manual steps in Okta (Okta documentation).
The table below summarizes the different scenarios where users can be unassigned from Okta apps or groups in Lumos.
Situation | Outcome | Okta API endpoint |
When approved time-based access to a permission linked to an Okta group expires. | Lumos unassigns the user from the Okta group. | |
When approved time-based access to an Okta app (not a permission) expires. | Lumos unassigns the user from the Okta app. | |
When the removal workflow for an Inactivity Workflow includes a | Lumos unassigns the user from the Okta group. | |
When the removal workflow for an Inactivity Workflow includes an | Removal workflow:📄 Okta Capabilities |
|
When you click Deactivate Account > Unassign User from App for user account(s) when viewing a single Okta app (not in an access review) | Removal workflow:📄 Okta Capabilities |
|
When you perform an account access review (📄 Choosing Account or Permission Access Reviews) and you Reject Account Access for an account with an Okta Source and you choose the Deprovision removal method for the account (📄 Editing Access Review App Settings) | Removal workflow:📄 Okta Capabilities Note: If your Okta app is merged (📄 Merging Lumos Apps) with a Lumos app integration, choosing the Deprovision removal method will also result in Lumos removing access for the user's account in the integrated app using the most destructive removal method available. |
|
When performing a permission access review, you reject a permission tied to an Okta group. | Lumos unassigns the user from the Okta group when you execute automatic removals. | |
When performing an account access review, you modify permissions for an account and reject a permission tied to an Okta group. | Lumos unassigns the user from the Okta group when you execute automatic removals. |
Unassigning users from groups and apps safely
For some Okta unassignment workflows (noted in the table above), the Okta group from which a user is being unassigned provides access to multiple apps.
The removal workflow outlined below only applies to the rows in the table that are linked to this section! If you have questions, please reference the table above.
Since it's usually not intended to remove someone from a group that provides access to multiple apps, we execute the following removal workflow as a safeguard.
If the user is assigned to the Okta app directly (not via groups), Lumos un-assigns them from the application.
If the user is assigned to the app via an Okta group, and the group only provides the user access to that app, we'll unassign them from the group completely.
If the user was assigned to the app via an Okta group, and the group provides the user with access to multiple applications, we'll change the user's app assignment to a direct assignment (not group-based), then un-assign them from the app. This keeps the user in the group but removes their access to the app.
Okta API endpoints:
App Unassignment: https://developer.okta.com/docs/reference/api/apps/#remove-user-from-application
Group Unassignment: https://developer.okta.com/docs/reference/api/groups/#remove-user-from-group
User Assignment Change: https://developer.okta.com/docs/reference/api/apps/#assign-user-to-application-for-sso-and-provisioning (we specify {'scope': 'USER'} to change the user's assignment type on an app from group-based to individually-assigned. (Okta support article)