Introduction

Okta Identity Governance (OIG) Entitlement Management feature supports managing entitlements out of the box for these provisioning-enabled apps in the Okta Integration Network (OIN). This list will grow with time; however, it is also possible to manage entitlements to applications not in this list using its APIs.

This knowledge article details how this can be done. This article assumes familiarity with Okta’s Workforce Identity Cloud platform including the Okta Admin console, Okta Workflows, and OIG. This article does not cover the basics of the Entitlement Management capability itself. Readers are advised to read this blog post for an introduction. This article specifically deals with how to implement similar Entitlement Management capabilities for applications not in the provisioning-enabled list using its APIs. Though this article uses Okta Workflows for processing event hooks, it is not required to do so. You can use your own custom-built and self-hosted event hooks; however, using Okta Workflows simplifies things as it is a no-code platform, and the workflows built by you are hosted by Okta. In addition, Okta Workflows is offered alongside OIG as a bundle, making it a convenient and simpler solution option.

In OIG, entitlements can be managed using Entitlement policies that assign entitlements to users using Okta Expression Language or using Entitlement bundles which are requested by users using OIG Access Requests. This article covers both of these scenarios in the context of custom or BYO entitlements.

Configuration/Set up

As a first step, create the application in Okta. This article uses a custom SAML application. Note that not all applications support Entitlement Management; for example, bookmark and SWA apps do not support Entitlement Management at the time of writing this article. Refer to the limitations section in the Entitlement Management documentation. In addition, the actual SAML configuration has not been done for this example, as the SSO capability will not be tested, but for an actual production application, this is assumed to be configured and working. The Governance Engine needs to be enabled in the General tab of the application configuration, as shown in this screenshot. Also, take note of the prerequisite mentioned in the screenshot.
 

Once the Governance Engine is enabled, the new Governance tab will display.

The Governance tab contains Entitlements, Entitlement bundles, and Entitlement Policies. They will initially be empty. Entitlements can be created directly from this Governance tab in the admin UI or using the OIG APIs. In a BYO entitlement scenario, this is typically done using the OIG APIs and Okta Workflows, where an Okta workflow would discover the entitlements in the application (using the application’s APIs to retrieve entitlements) and import those entitlements in Okta using the OIG APIs. In this article, Postman will be used to create some dummy entitlements using the OIG APIs. View the API reference documentation for the OIG APIs at Okta Identity Governance API.

The API calls in the screenshots below create some dummy license and role entitlements. These entitlements will be used throughout this article in entitlement policies, bundles, and access reviews to understand how BYO entitlements can be managed.

The entitlement values array highlighted in the screenshots has an externalValue field that uniquely identifies the entitlement in the application and is retrieved from the application, typically using the application’s APIs. The examples in this article use some dummy (but unique) values for this field. Okta generates a unique ID for the entitlement and also a unique ID for each of the entitlement values, which is located in the response to these API calls. The screenshot below shows the response to the API call that created the license entitlements for illustration.

Once these entitlements are created using the APIs, they are displayed in the Governance tab of the application.

As mentioned before, these entitlements could have been created directly in the UI using the Add entitlement button shown in the screenshot, but APIs are typically used to import custom entitlements from target applications into Okta at scale.
 

Now that the entitlements have been imported into Okta, the next step is to create a couple of entitlement policy rules to assign these entitlements to users. Entitlement policy rules can be created in the Policy tab. There is a default entitlement policy, to which rules can be added using the Add rule button. These rules use Okta Expression language to assign entitlements to users.

In this article, two simple rules are used, one for admins and one for regular users. The first rule checks a user profile attribute to assign entitlements to admin users, and the second rule is set to true for illustration purposes. It serves as a catch-all rule that always evaluates to true and hence applies to all users. These rules need to be configured to model your business rules for assigning entitlements to users.

When editing the policy to add rules, it goes to a draft state, and a policy needs to be applied to activate it.

The next step is to assign users to this application. When users are assigned to this application, the entitlement policy rules would get evaluated and entitlements would be assigned to users based on these rules. Thus, users can be assigned entitlements based on entitlement policy rules. However, there is another way in which users can get entitlements – through entitlement bundles.

Entitlement bundles, as the name suggests, are bundles of entitlements, and users would request these entitlement bundles as part of OIG Access Requests. Note that entitlement bundles cannot be assigned through entitlement policy rules. They need to be requested as part of OIG Access Requests. Access Requests cannot grant individual entitlements like entitlement policy rules do; they can only grant entitlement bundles. These are limitations in the platform at the time of writing this article. In this example, a couple of entitlement bundles are created to be used in access requests later.

Two entitlement bundles are created, one for admin users and one for regular users. These bundles grant the same entitlements as the entitlement policy rules, but are used just to illustrate how BYO entitlements can be managed when entitlement bundles are used.

Now that the entitlements, bundles, and policies are set up, this will illustrate the different ways by which entitlements can be granted to users in Okta and how Okta can provision these entitlements to users in the target application in each of these scenarios.
 

Assigning entitlements to users – different scenarios

Entitlement policies

The following will demonstrate how entitlements can be assigned to users through entitlement policy rules. To do so, users need to be assigned to the application. Two example users will be used for testing – Gusto Simpson, whose title attribute is set to “Admin,” and another user – Shell Simpson, whose title attribute is empty.

Gusto Simpson is assigned to this application. With the governance engine enabled, the Policy or Custom values for the entitlement assignment method can be selected when assigning the user to the application. Groups can be assigned to the application, but in this example, individual users are assigned.

Once the user is assigned, the Entitlement is set to Policy in the Assignments tab. This indicates that Policy has assigned the entitlements for this user. 

To see all the entitlements of the user, click on the 3 dots and select View entitlements. In this case, all of them are assigned by the entitlement policy, hence the source is Policy. A user can have entitlements coming from multiple sources, such as Policy and Access Requests. This scenario is described later in the article.
 

One thing to note is that both the entitlement policy rules were evaluated for this user, even though the first rule was a match. Entitlement policy rules are evaluated differently when compared to Okta authentication policy rules, as the evaluation does not stop when a rule is matched; it goes on to evaluate all the rules and entitlements for the user are assigned from all matching rules.

When entitlements are assigned to a user, the event resource.user_entitlements.update is logged in the Okta System log.

Looking into the DebugContext, a GrantId, GrantAction, and GrantSource are displayed for this entitlement grant.

Now that the entitlements from the policy have been assigned to the user in Okta, these entitlements need to be propagated to the target application. This can be done using an event hook that subscribes to this event. Event hooks can be implemented using Okta Workflows or custom-built and self-hosted. In this article, an Okta Workflow is used to implement the event hook.  Event hook filtering is set up to filter the resource.user_entitlements.update event by application, so that the event hook is called only when the event is fired for this application and not for other applications in the Okta tenant. This article does not cover the steps required to set up an event hook. 

The following shows the Okta Workflow used to implement the event hook. The workflow looks like this (divided into two screenshots for readability):

At a high level, the workflow does the following:

• Reads the GrantId from the DebugContext.
• Calls the GetGrant OIG API using the GrantId with the ?include=full_entitlements query parameter to get the grant details, including the entitlements granted by the grant.
• Obtains the userId and applicationId from the response of the GetGrant API. The userId is in the targetPrincipal.externalId field, and the applicationId is in the target.externalId field in the response to the GetGrant API.
• It then calls the Get Principal Entitlements OIG API filtered by the userId and applicationId. This returns the principal entitlements of the user for this application.
• After this, the Workflow needs to call the relevant APIs of the target application to sync/provision these principal entitlements into the target application. This depends on the APIs exposed by the application in question for provisioning entitlements and is not shown in the Workflow.

NOTE: This article does not go over creating users in the application when users are assigned to the application in Okta, updating user profile attributes, etc. These can be done by calling the application’s APIs. This article discusses only what is involved in the provisioning of entitlements in the application.

The following occurs within the workflow. The response to the GetGrant API is shown below:

The highlighted sections in the screenshot show the applicationId, userId, and the array of entitlements granted by this grant. In this case, the entitlements array has two elements, one for licenses and one for roles. In each of these entitlements, there is an array of values with two elements in each value array (for the two licenses and two roles respectively).

The workflow then uses the applicationId and the userId to call the GetPrincipalEntitlements API. The response to this API is shown below:

This call returns the full set of entitlements the user has in this application. In this case, this is the same as the entitlements returned by the GetGrant API covered before, but it is not always the case. This is because the GetPrincipalEntitlements API returns not just the entitlements from this grant, but also from other active grants that the user may have (for example, a user may have multiple active grants, one from a policy and others from one or more entitlement bundles (this scenario will be covered later in this article)). Hence, it is recommended to use the principal entitlements as the source of truth to provision entitlements in the target application. This will become clearer later when reviewing an example of a user who has multiple active grants.

At this point, the workflow should call the target application’s APIs to provision the entitlements returned by the GetPrincipalEntitlements API response. This would entail removing the entitlements not in the list of the user’s principal entitlements and adding the entitlements in this list in the target application using the target application’s APIs. To do this, the application needs to expose APIs to retrieve the entitlements for a user, add an entitlement for a user, and remove an entitlement for a user. Most applications that provide APIs to manage entitlements should expose these capabilities via APIs. (As an example, Microsoft 365 provides Graph APIs to get all licenses for a user, assign a license to a user remove a license from a user, and likewise for roles).
 

Also note that when assigning the user to the application earlier, the entitlement assignment method selected was Policy. Custom can also be selected for the entitlement assignment method. If custom is selected, the entitlements to assign to the user need to be selected, and the entitlements will not be assigned by the entitlement policy rules. This would then generate the same event type in the Okta system log (with a GrantSource of CUSTOM instead of POLICY), which can be processed by the same workflow to provision those entitlements in the target application. However, Organizations would typically use entitlement policy rules to assign entitlements to users, as these rules represent the business rules for the Organization that govern which users should get what entitlements.
 

Change in policy rules

The following is an example of how users' entitlements are affected when there is a change in policy rules, (such as adding new rules, changing or deleting existing rules, etc). 

In this example, the entitlement policy rule is edited so that regular users get only the basic license, not the app user role. The role entitlement is removed from this rule by clicking the trash icon, then saving the rule and applying the policy.

The modified policy rule looks like this:

The user’s role entitlement has been updated in the app assignment. The App User role has been removed.

This change generates the same system log event type in Okta again with a GrantAction of ALLOW like the last time.

The following shows the execution history of the workflow that runs again in response to this event. The GetGrant API call is highlighted in the screenshot below:

Below is the response from the GetGrant API call. The App User role has been removed from the list of entitlements in the grant due to the entitlement policy change that was made.

The response from the GetPrincipalEntitlements API would return the same set of entitlements.
 

Lastly, when users are unassigned from the application (either individually or by unassigning a group from the application), this would also generate the same event type in the Okta system log. It would be processed by the workflow, but in this case, the principal entitlements of the user would be empty (as Okta removes all the entitlements of the user for the application when the user is unassigned from the application). This is shown below, and in this case, the workflow needs to implement the logic to remove all the entitlements for the user in the application by calling the application’s APIs (not included in this article).

Next, the article reviews the method of assigning entitlements to users, which is through entitlement bundles using OIG Access Requests. (Note that the policy rule is reverted to what it was before, i.e., add the App User role back to the policy rule that grants entitlements for regular users).

Entitlement bundles

Two entitlement bundles were created in the Configuration/Set Up section of this article. Before using entitlement bundles, a regular user (non-admin with an empty title) will be assigned to the application before the user gets entitlements from an entitlement bundle. This will cause the policy to assign some entitlements to the user first, which will allow for testing the scenario where a user has multiple active grants (from both policies and entitlement bundles).
 

The user Shell Simpson has been assigned to the app, and she gets these entitlements through the entitlement policy rules as she is a regular user.

A request type exists in Okta Access Requests to request access to the admin entitlement bundle, which looks like this.

This is a standard request type, except for the Grant access to entitlement bundle action selected in the screenshot. This is a new type of Action available to use in request types to assign an entitlement bundle to a user. This request type requires manager approval before the user can be granted the admin entitlement bundle.
 

Shell requests access to this entitlement bundle through Okta Access Requests, and her manager approves it. This is standard Okta Access Requests functionality and is not covered in detail in this article. Please refer to Okta Access Requests for an overview. After manager approval, Shell is granted the admin entitlement bundle, and her entitlement type changes to Custom in the assignment (as she now has entitlements granted outside of the entitlement policy). She has entitlements sourced from both the entitlement policy and the Access Request, as shown below:

When Shell is granted the admin entitlement bundle, the same event type is logged in the Okta system logs (resource.user_entitlements.update), which again triggers the workflow. The DebugContext of the event looks a bit different this time.

The event again has a GrantId, but the GrantSource is ENTITLEMENT_BUNDLE instead of POLICY. The following shows the workflow's execution history. The response to the GetGrant API call (with the ?include=full_entitlements query parameter) is highlighted below. The grantType is ENTITLEMENT-BUNDLE, and the entitlementBundleId is now available in the response.

The entitlements array in the GetGrant API response contains the entitlements granted through this entitlement bundle. The grant in this particular system log event is specific to the entitlement bundle and does not cover the entitlements that Shell has been granted by the entitlement policy, which is why the GetGrant API response for this grantId does not contain the other entitlements granted through the entitlement policy. However, when reviewing the response of the GetPrincipalEntitlements API call, all the entitlements that Shell has, both from the entitlement policy as well as from the entitlement bundle, are displayed. Highlighted below is the call to the GetPrincipalEntitlements API and its response. As mentioned before, the workflow needs to have the logic to update the entitlements in the target application via its APIs (not included in this article) using the user’s principal entitlements as the source of truth. That would then provision the entitlements the user was granted through this bundle in the target application.

Shell has two active grants, one from the Entitlement policy and another from the Entitlement bundle. Call the List All Grants API filtered by the application and user to see all the entitlement grants a user has for an application. The response to this API call is shown below.

There are two active grants each with a unique grantId returned by this API call, the first one is of grantType POLICY and the second one is of grantType ENTITLEMENT-BUNDLE (which also has the entitlementBundleId). The Get Grant API can be called with each of these grantIds (with the include=full_entitlements query parameter) to see the entitlements granted by each of these grants. NOTE: A user can also have more than one entitlement bundle, each with its own active grant. Thus, a user can have many active grants.
 

The following shows the impact of updating an entitlement bundle and how it affects the entitlements of a user who has been granted the bundle. The Admin entitlement bundle will be updated in the Okta Admin UI to remove the Premium license entitlement by clicking on the trash icon shown below and then saving the bundle.

When looking at Shell’s entitlement assignment, the Premium License entitlement has been removed due to the change that was made.

 

This again generates the same event type in the Okta system log with GrantAction ALLOW and GrantSource ENTITLEMENT_BUNDLE.

When looking at the execution history of the workflow that processed this event, the response to the GetGrant API call is shown. 

The entitlements array now does not include the Premium license entitlement, as it has been removed from the entitlement bundle. The response to the GetGrant API call for this grant includes only the Super Admin role entitlement. However, it cannot be determined what entitlement was removed by looking at this grant.

It should now be clear why it is recommended to use the user’s principal entitlements as the source of truth to update the entitlements in the target application. If the entitlements from the GetGrant API call are used to make this update, it is not apparent that the Premium license entitlement needs to be removed in the application. (It is also not possible to take the approach of removing all the entitlements not present in this grant, as that would remove the entitlements from other active grants from other entitlement bundles and the entitlement policy). Thus, using the user’s principal entitlements as the source of truth to update the entitlements in the target application is reliable for all scenarios, as it includes the user’s entitlements from all active grants. In this scenario, the list of principal entitlements would not have the Premium license entitlement, and hence, our workflow using that as the source of truth needs to remove that entitlement in the target application.
 

Access Certifications

In this section, an access certification campaign will be created to review users’ entitlements in the application. This scenario will cover when a reviewer revokes a user’s entitlements acquired through an entitlement bundle and through a policy and how this can be remediated in the application. (Note the Premium license entitlement was added back to the Admin entitlement bundle).

This article does not cover access certification campaigns in detail; refer to the production documentation or other blog articles. An access certification campaign is created to review the user’s entitlements in the application and set the remediation rules to remove access from the user when the reviewer revokes access. This will then attempt to remove the entitlements from the user when a reviewer revokes those entitlements.

The reviewer is set to the user’s manager. After launching the campaign, this example shows logging in as the reviewer to perform the review. Marge Simpson is configured as the manager for Shell Simpson. The image below shows the manager user profile attributes for Shell Simpson

After logging in as the manager, Marge Simpson, go to the Okta Access Certification Reviews dashboard and view the pending reviews. Marge will be able to view and review the entitlements each user has for the application. When Marge selects the row with the entitlement bundle, she can see the entitlements that Shell has acquired from the bundle and all of her active entitlements (coming from all active grants).
 

Once the entitlement bundle is revoked, there are a few events logged in the Okta system log – one for the access certification review decision and another for the access certification review remediation. The access certification review remediation is successful, which means the entitlement bundle has been removed from the user (as the campaign was configured to remove access from the user when the reviewer revokes access). As the user’s entitlements have been updated, this also logs the user entitlement updated successfully event in the system log. 

When expanding the event, the GrantAction this time is DENY, and GrantSource is ENTITLEMENT_BUNDLE.

Looking at the execution history of the workflow triggered by this event, in the response to the GetGrant API call, the action is set to DENY, and this time, the entitlements array contains the entitlements that were denied or revoked: 

Logic can exist in the Workflow to check if the action is DENY, and if so, remove the entitlements in the entitlements array of the GetGrant API response from the target application by calling the application’s APIs. However, the logic that exists in the workflow currently will work as-is, as the user’s principal entitlements will not have the revoked entitlements, and since the workflow is set to use that as the source of truth to update the entitlements in the application, these revoked entitlements would be removed in the application.
 

In the response to the GetPrincipalEntitlements API call in the flow execution history, the user’s principal entitlements contain the Basic license and the App User role as expected (as the other two entitlements were revoked).

The following shows what occurs when a reviewer revokes an entitlement granted by a Policy instead of revoking an entitlement bundle.
 

As Marge Simpson, revoke the Basic License entitlement for Shell Simpson that has been granted by the entitlement policy.

After revoking the entitlement, if looking at the closed reviews for the access certification campaign, Okta could not remove the entitlement for the user in response to the reviewer revoking this entitlement, and it has been marked for manual remediation. This is because the entitlement has been assigned by Policy.

In the Okta system logs, the access certification review decision (REVOKE) was processed successfully, however, the access certification review remediation was skipped, unlike the last time when it was successful, which is why manual remediation is required. This is due to the entitlement being assigned by Policy.

This time, the user entitlement updated successfully event was not logged as the user’s entitlement was not removed.
 

It is important to review entitlements granted through all sources (Policy, Custom, and entitlement bundles) and organizations are often required to for audit and compliance purposes. When an entitlement granted through a policy is revoked, it is better to remediate it manually. Policy grants reflect an organization’s business rules and if a user was granted an entitlement by a policy that needs to be revoked, the policy rules need to be reviewed for any errors that granted the entitlement in the first place. If the admin chooses to modify the policy rules to revoke the entitlement, that would log the user entitlement updated successfully event in the system log, which would be processed by the workflow to revoke the entitlement in the target application. (This scenario was covered in this article).

Access reviews for entitlements assigned by selecting Custom as the entitlement assignment method was not covered, but that would work the same way as entitlements granted by entitlement bundles. When a reviewer revokes a custom entitlement, that would generate the same event type in the system log, which would trigger the workflow to revoke the entitlement in the target application.
 

Conclusion

This article covered how entitlements can be managed for applications for which Okta Identity Governance’s Entitlement Management capability is not supported out of the box in the Okta Integration Network. The article looked at different ways that entitlements can be assigned, such as entitlement policy, custom, and entitlement bundles. It discussed how provisioning entitlements can be automated in the target application for each of these scenarios. The article also covered how updates to entitlements triggered by changes to entitlement policy rules, entitlement bundles, or custom entitlements can be propagated to the target application. Finally, it reviewed how revocation of entitlements by unassigning users from applications or through access reviews can be propagated to the target application. Thus, similar Entitlement Management capabilities can be implemented for custom applications, as Okta supports out-of-the-box for a limited number of OIN apps. This can also be implemented using the enhanced SCIM 2.0 support for Entitlement Management. This article covered how this can be implemented using Okta event hooks and Okta Workflows.
 

Related References

• Managing custom entitlements or Bring Your Own (BYO) entitlements using Okta Identity Governance (OIG) Entitlement Management (original post by Sathish Balasubramaniyan)