Federated claims with entitlements

This guide describes how to configure your app to pass entitlements in your tokens using federated claims.

Learning outcomes

Understand the purpose of federated claims with entitlements.
Understand how to configure federated claims for a SAML and an OpenID Connect (OIDC) app.

What you need

Okta Developer Edition organization (opens new window)
The Identity Governance feature enabled for your org. Contact Okta Support (opens new window) to enable this feature.
The Entitlement SAML Assertions and OIDC Claims feature enabled for your org. To enable this feature, go to Settings > Features, locate the Entitlement SAML Assertions and OIDC Claims feature, and enable.
An existing SAML or OIDC app
A test user assigned to the SAML or OIDC app

Overview

Federated claims create a more consistent experience for the configuration of claims across protocols. These claims unify the inconsistencies in both the persistence and the generation of token claims because they can be consumed by apps with different protocols.

A federated claim takes the form of a name and an expression that references principal (user) information. The claim is included in tokens produced by federation protocols. Okta supports SAML and OIDC apps. Federated claims are inserted into either an OIDC ID token or a SAML assertion.

Entitlements

An entitlement is a permission that allows users to take specific actions within a resource, such as a third-party app. In the Identity Provider org (Okta), app entitlements help you manage different levels of permissions that users can perform within a third-party app.

When a user is assigned to an app that's configured to use entitlements, they may be granted one or more entitlements. Each entitlement that they're granted may have one or more values, depending on the entitlement definition (String or String Array).

There are two important properties associated with entitlements:

name: The display name for an entitlement. This is a human-friendly name that's for display purposes only.
externalValue: The value of an entitlement. Think of this value as the system/external representation of the entitlement. Use this value in your EL expression to communicate to the Service Provider (SP) app which entitlement that the principal (user) has been granted.

Other attributes included with an entitlement are the value or values that it may contain. These are the specific values that the principal (user) has for each entitlement. Values within an entitlement may be either a single string or an array of strings. These values have two important attributes, similar to the entitlement itself:

name: The display name of the entitlement value
externalValue: External system representation of the value

Expression Language and entitlements

The integration of entitlements into Expression Language in Identity Engine is on the appuser context. When you configure an entitlement claim for an app, the expression states which entitlement the SP should evaluate for the principal and the app.

If the externalValue of an entitlement is permission, then your EL expression would be appuser.entitlement.permission, because entitlement.externalValue = permission. At evaluation time, the results of the expression are the entitlement values that the principal has been granted for the entitlement referenced in the expression.

The following is an example JSON body of a POST request to https://{yourOktaDomain}/api/v1/apps/{appID}/federated-claims to create an entitlement:

  {
     "name": "entitlement_claim_name",
     "expression": "appuser.entitlements.example_entitlement"
  }

Configure entitlements

The following sections are an example flow for setting up and using entitlements for your SAML or OIDC app.

Update your app to support entitlements

Note: Identity Governance doesn't support Federated Broker Mode for OIDC apps.

Go to Applications > Applications and select the app that you want to define entitlements for.
On the General tab, scroll down to the Identity Governance section and click Edit.
Select Enabled to enable the Governance Engine, and then click Save. The Governance tab should appear within a few seconds. If it doesn't, refresh the page.

Define entitlements for the app

Note: Entitlements that you create here are what you use in the EL expressions that then insert the claims into the attribute statement or ID token.

While still in the app that you updated in the previous section, select the Governance tab.
On the Entitlements tab, click Add Entitlement and define the entitlement properties:
- Enter a Display name for the entitlement. In this example flow, enter Permission.
- Enter a Variable name for the entitlement. In this example flow, enter permission. Use this attribute in your EL expression when you configure an entitlement claim for the app.
Note: You can't edit a variable name after you create it.
- Set the Entitlement Type (Data Type). The entitlement can either be a static string (String) or a string array (String Array). In this example flow, select String Array.
- Optional. Enter a Description of the entitlement.
Click Next.
Define entitlement attributes. You can define one or more values that can then be assigned to the user. Each value must be unique:
- Enter a Display name for the entitlement value. In this example flow, enter Read.
- Enter a Variable name for the entitlement value. In this example flow, enter Read. This value is what appears in the attribute statement or ID token.
- Optional. Enter a Description of the entitlement value.
Click + Add value and repeat the previous step for the Write and Delete attribute values for this example flow.
Click Save entitlement.

Assign entitlements to a user

Note: If you created an app from scratch, assign a user to the app for testing.

On the Assignments tab, select View access details from the right-hand menu for your test user.
Click Edit access, and then click Customize entitlements to customize the entitlements for the user. The entitlement that you created in the previous section appears.
Select the permissions that you want to assign to the user. In this example flow, select Read, and then Write.
Click Save, and then Save again.

Configure an entitlement claim for the app

Select the Sign On tab, scroll down to the SAML Attributes (SAML) or Claims (OIDC) section, and click Edit.

Note: If you have the Identity Threat Protection (ITP) feature enabled for your org, select the Authentication tab.
Select Add expression to configure the appuser entitlement claim for the app.
In the dialog, give the entitlement claim a name. In this example flow, enter PermissionAssignment.
In the Expression field, enter appuser.entitlements.permission as the EL expression. The permission attribute is the variable name (externalValue) that you assigned when you defined entitlements for the app.
Click Save.

Test the configuration

To test your configuration, federate into your app to obtain the attribute statement or ID token.

Obtain the SAML attribute statement

Access the SAML app from the End-User Dashboard and sign in as your test user. Use your browser's dev tools window or some other tool to extract the SAML response. Then, use a tool such as the SAML Tokens tool (opens new window) to view the attribute statement. The statement should include the permissions that you assigned to the test user.

Example

        <saml2:AttributeStatement xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">
            <saml2:Attribute Name="PermissionAssignment" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
                <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">
                    read
                </saml2:AttributeValue>
                <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">
                    write
                </saml2:AttributeValue>
            </saml2:Attribute>
        </saml2:AttributeStatement>

Obtain an ID token

Obtain an ID token by making the appropriate authorization requests, depending on the grants that you enabled for your app. Then, use a tool such as jwt.io (opens new window) to decode the ID token and view the entitlement that you granted to the user.