How-tos

13 mins read

Set Up Okta for Authentication

Learn how to configure Okta and Cloudentity to enable your users to sign in using Okta IDP.

Integration Pattern

In case of OIDC integration, Cloudentity integrates with Okta in a specific way. Instead of using a single application in Okta to authenticate the users, Cloudentity creates an application in Okta for each application registered in Cloudentity. This allows to keep the per-application rules configuration in Okta while providing the seamless experience for clients using Cloudentity. To make this integration pattern work, Cloudentity first needs a service application in Okta with application management rights to create those applications on Cloudentity’s behalf.

You can integrate Cloudentity with Okta IDP using either OIDC or SAML, as explained in the below instructions:

About Okta as IDP

Okta is natively supported by Cloudentity as an OIDC Identity Provider, which means that it has a dedicated connection template in Cloudentity for your convenience. Okta applications implement the OIDC protocol, providing the proof of user authentication to Cloudentity within an ID Token and Access Token.

Cloudentity uses the private_key_jwt authentication flow to authenticate with Okta. For more information about this flow, read Client authentication using private_key_jwt.

Okta and SAML

Okta applications can also use the SAML protocol, but this integration is not natively supported by Cloudentity yet. If necessary, you can use the generic SAML connector to bind Okta apps via SAML. For more information, read Connecting to Okta IDP using SAML 2.0.

Connect Okta with OIDC

Prerequisites

  • You have an Okta developer account.

  • You have a service application registered in Okta. For help, follow Okta documentation for creating a service app.

    Note

    Creating an application in Okta with access to Okta application management APIs requires private_key_jwt as the authentication method. To use this method, a public/private key pair is needed. When following the above instruction, make sure to create a PEM private key from the key pair using any tool of your choice.

Grant Scopes for Okta App

  1. In the Okta developer portal, go to Applications -> YOUR_APP -> Okta API Scopes and grant the following scopes:

    • okta.apps.manage
    • okta.groups.read

    Note

    Keep your Okta application page open in your browser so that you can check its details when needed in the subsequent steps.

Basic Configuration

  1. In your workspace landing page, select Identity Providers > Create Connection to add a new connection.

  2. In the Create Connection page, select Okta from the list of the predefined IDP templates and click Next.

  3. Fill in the form.

    Parameter Description
    Name Name for your Cloudentity’s Okta connection. This name allows users to identify the IDP they need to authenticate with.
    Domain Okta domain where the service app is registered. Do not include the protocol - the domain format must be similar to dev-136121869.okta.com.
    Client ID Client ID of the OAuth application registered in Okta
    Client private key Client private key used by Cloudentity to sign the JWT. Must be in PEM format.

  4. Optionally, enable Authentication context caching.

    Tip

    You can enable the authentication context caching if you wish to store the user’s authentication context locally. If you do, specify the cache Time To Live as well. Learn more by reading Stateful authorization with Cloudentity.

  5. Save your changes. You can now configure the advanced settings for your IDP or try it out right away.

Advanced Configuration

Advanced settings contain optional features which may be necessary to use in specific cases. To configure your new IDP advanced settings

  1. From the Identity Providers > YOUR_IDENTITY_PROVIDER > Configuration page, select Advanced settings at the bottom.

  2. In the Scopes field, add additional scopes to be requested when authenticating to the IDP (by default openid, email, and profile scopes are requested).

    Note

    Since multiple clients can use the same IDP for user authentication, you may need to further restrict specific client’s ability to request a given scope. For more information, read about Configuring applications in Cloudentity.

  3. In the Authentication Method Reference you can select an authentication method to be written into the amr object returned by the IDP. The amr object is written if it doesn’t exist. If it exists, its values are replaced with the selected item.

    Tip

    You can also use an extension script to modify amr values. If you do, keep in mind that the script is executed after the amr injection from this field, so the values injected by the script are final.

  4. Enable the Use Org authorization server option to use Okta’s Org Authorization Server. The default custom authorization server is used otherwise. To use your own Okta server, enter the server ID in the Authorization server ID field. For more information, read Okta documentation on authorization servers.

  5. Enable the Get user info option to get the user’s group membership information.

  6. Select Save.

Add custom OIDC IDP attributes

If your IDP returns custom claims outside of the standard OIDC scope, make sure to add them to the IDP connector so that they can be recognized and mapped to the authentication context. Some IDPs (for example Cognito) may require you to set custom attribute permissions first.

  1. Go to Identity Providers and select an IDP from the list.

  2. Open the Attributes page. A standard list of OIDC attributes returned by this IDP appears.

  3. Select Add attribute.

  4. In Source, select the data source for the custom attribute

    Source Description
    Access token Get data from the access token received from the IDP
    ID token Get data from the ID token received from the IDP
    User info Get data data returned by the OIDC user info endpoint (note that this must be explicitly enabled on the IDP connector)

  5. Fill in the rest of the form.

    Option Description
    Claim name Name of your custom attribute matching the incoming IDP claim
    Display name User-friendly name for the custom attribute
    Data type Data type matching that of the incoming IDP claim

    Claim names with a . character

    If the incoming attribute has a . character in the name, the dot must be explicitly escaped using \. when defining the IDP attribute. For example, claim name https://example.com/groups must be entered as https://example\.com/groups.

  6. Save your changes and proceed to mapping the attributes to the authentication context.

Map IDP attributes to authentication context

If you’ve added custom attributes for an IDP, you need to make sure they are mapped to the authentication context. You can do it either from the IDP configuration page (as explained here) or use Data Lineage instead.

Default OIDC/SAML attributes are mapped out of the box.

  1. Go to Identity Providers and select an IDP from the list.

  2. Open the Mappings page. A standard attribute mapping for this IDP appears.

  3. Select Add mapping and map any custom IDP attributes to an existing authentication context attribute.

    Note

    If you need to create new authentication context attributes, read Setting up authentication context.

  4. Optionally, assign a post-authentication extension to modify your authentication context before issuing the token to the client. Attributes returned by the script do not need to be separately mapped to the authentication context.

  5. Save your changes. Your mapped custom attributes should now be shared in the ID token issued to your client application, given that the target application requests them (you can check this in Data Lineage).

Test your IDP

Prerequisites

  • Your IDP is enabled for user authentication.
  • Demo workspace is created with the Demo Portal connected.

Test

  1. Open the Demo Portal (Data lineage -> Demo Portal -> Launch).

  2. Select LOGIN TO DEMO APP.

  3. Select your configured IDP and, next, authenticate in IDP.

Result

Cloudentity displays the consent page that lists data scopes to be shared with the application. When you proceed to the application (ALLOW ACCESS), the PII data coming from Okta is delivered through the access token and the ID token generated by Cloudentity.

Read more

For information on granting and managing Cloudentity consents, see Cloudentity OAuth consents.

Connect Okta with SAML

Security Assertion Markup Language (SAML) is an XML-based open standard that allows to transfer user’s identity data between the identity providers and the service providers.

SAML has its benefits that include the following:

  • Improved user experience

    SAML allows the users to use the Single Sign On (SSO). The user can authenticate with the IDP and then access the service protected by Cloudentity without additional authentication.

  • Reduced costs of administration for service providers

    SAML reuses a single act of authentication for multiple times, which may reduce costs of maintaining account data.

  • Risk transfer

    Using SAML shifts the responsibility for identity management and IAM-related risks from the service provider to the identity provider.

Prerequisites

Connect Okta SAML IDP

  1. In Cloudentity, go to Identity Providers > Create Connection.

  2. Choose SAML and select NEXT.

  3. Follow Okta’s documentation to create a SAML application in Okta. Perform Task 1 and Task 2, click Next, then come back to this instruction.

  4. In the Configure SAML tab, select Download Okta certificate.

  5. Copy the contents of the downloaded .cert file.

    Example

    The certificate should look similar to the following:

    -----BEGIN CERTIFICATE-----
MIIDvDCCAqSgAwIBAgIGAXnRtHz2MA0GCSqGSIb3DQEBCwUAMIGeMQswCQYDVQQGEwJVUzETMBEG
A1UECAwKQ2FsaWZvcm5pYTEWMBQGA1UEBwwNU2FuIEZyYW5jaXNjbzENMAsGA1UECgwET2t0YTEU
MBIGA1UECwwLU1NPUHJvdmlkZXIxHzAdBgNVBAMMFmNsb3VkZW50aXR5LXdrb3Rsb3dza2kxHDAa
BgkqhkiG9w0BCQEWDWluZm9Ab2t0YS5jb20wHhcNMjEwNjAzMTE0NzU3WhcNMzEwNjAzMTE0ODU3
WjCBnjELMAkGA1UEBhMCVVMxEzARBgNVBAgMCkNhbGlmb3JuaWExFjAUBgNVBAcMDVNhbiBGcmFu
Y2lzY28xDTALBgNVBAoMBE9rdGExFDASBgNVBAsMC1NTT1Byb3ZpZGVyMR8wHQYDVQQDDBZjbG91
ZGVudGl0eS13a290bG93c2tpMRwwGgYJKoZIhvcNAQkBFg1pbmZvQG9rdGEuY29tMIIBIjANBgkq
hkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA0bYLhHZXo/oKxMtKMUUaAmkbgr0U9f/KYBosVQmTPoKe
S/dg3OQYEmUozVbu07COPdJ3gz8CcXf0NIxjhf9Fso2vrbRfAisdxJjh/ec0Q2YR5hisTWGF0ZCZ
YoTiI2pGnCmnqLhBLuEdvew+hhqi3knZ2yoobiUuwj0UXOzOW4RmaPRCmu1MvJl1BWJ9IykQAfEM
L61fr1fpfymZ857MDmGPp7XnHCz/6duZ4yfzqV2QRNvP6kM/DesWvakO/fMEbc8Lkv4pKRfltWcq
yF4jCxObA9NxVf8lEaIJ74QqMo7uUs4wXnld9ff5I1D9ygjwO114yV41TdZTTqQMnXbGGQIDAQAB
MA0GCSqGSIb3DQEBCwUAA4IBAQBAvmbUn7pcTn5XKtW+HnzYOUdtqHq5Sg8KROaRFvMpQylrRqJe
t2qtRhs9k17pHyGCzKRZUnGS8Jj/X1ZWa1M8fAlzb33chCNKlz8Ei34r9Fk7j6FmvgmAZwZIwpL1
Ffss3dJ0eGyWMWtSO2ifPrV3jZ85vDAw3iFToujosxJHuEOU6pIPFS3eZ0TfbrRZJiKDkX08ISLg
P4hu3khLd5bRx4BvLKGlPppF2ls4str4pjBiC4DuUNVo+C7XAQjyjdCv8P2TQZKQeo8OkpRM1EW3
DpRLRM3dtzJ7xbOPZBb5tFAuLr/sHdqsQ5k/WUKu5srZpS+oGN6Gs/ScO2RwGZnN
-----END CERTIFICATE-----

  6. Fill in the SAML connector form in Cloudentity.

    Field Description
    Name Name of your connector. This name is displayed in the user authentication UI.
    Sign-in URL URL pointing to your Okta SAML IDP application’s SSO endpoint. Enter an initial dummy value to pass form validation if you don’t have this application yet.
    IDP certificate Certificate of your SAML IDP application. You need to obtain it from the application itself.
    Identifier source Defines how the user identifier is extracted from the SAML assertion received from the IDP. If you select Subject as the identifier source, the identifier is retrieved from <saml2:Subject>. If you choose Attribute, you need to enter a user attribute name into the Identifier attribute field. If you select the attribute as the identifier source, the identifier is retrieved from <saml2:AttributeStatement>. Any attribute from <saml2:AttributeStatement> can be used for that purpose.

  7. Select SAVE.

    Result

    Your new SAML identity provider is created and listed in the Consumer Identity Providers view.

    Entity issuer and Redirect URL (or Assertion Consumer Service (ACS)) are generated in Cloudentity. Use these values to finish the configuration on the SAML application side.

  8. Copy the Entity issuer value from Cloudentity and paste it in the Okta’s Audience URI field.

  9. Copy the Redirect URL value from Cloudentity and paste it in the Okta’s Single sign on URL field.

  10. Configure the rest of the fields as needed and select Next. If necessary, use Okta SAML documentation for help.

  11. Provide your feedback for Okta when prompted and select Finish.

    Result

    Your application is created.

    You are now able to provide a correct Sing in URL in your Cloudentity SAML IDP configuration.

  12. Click View Setup Instructions.

  13. Copy the Identity Provider Single Sign-On URL value.

  14. Go to Cloudentity > Identities > Your SAML IDP.

  15. Paste the URL in the Sign in URL and select Save.

    Result

    Your SAML IDP is configured and ready to be used.

Advanced Configuration

Advanced settings contain optional features which may be necessary to use in specific cases. To configure your new IDP advanced settings

  1. From the Identity Providers > YOUR_IDENTITY_PROVIDER > Configuration page, select Advanced settings at the bottom.

  2. In the Authentication Method Reference you can select an authentication method to be written into the amr object returned by the IDP. The amr object is written if it doesn’t exist. If it exists, its values are replaced with the selected item.

    Tip

    You can also use an extension script to modify amr values. If you do, keep in mind that the script is executed after the amr injection from this field, so the values injected by the script are final.

  3. Optionally, enable the Skip inResponseTo option. This is not recommended since it lowers the security level of your system, as the login is treated as IDP-initiated. You may need to turn this flag on when the InResponseTo parameter is not returned by the IDP.

  4. Select Save.

Add SAML IDP attributes

Make sure to add attributes sent by your SAML IDP to the IDP connector so that they can be recognized and mapped to the authentication context.

Consider the example below. All attributes within <saml2:AttributeStatement> can be extracted and mapped to the authentication context.

<?xml version="1.0" encoding="UTF-8"?>
<saml2:Assertion ID="id12606633554344727301514261" IssueInstant="2022-01-12T17:04:07.362Z" Version="2.0"
    xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">
    <saml2:Issuer Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity">http://www.example.com/exk3ip7ehfTC30ReG5d7</saml2:Issuer>
    <saml2:Subject>
        <saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">example@mail.com</saml2:NameID>
        <saml2:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
            <saml2:SubjectConfirmationData NotOnOrAfter="2022-01-12T17:09:07.362Z" Recipient="https://cloudentity-gkossobudzki.us.authz.stage.cloudentity.io/cloudentity-gkossobudzki/demo/login"/>
        </saml2:SubjectConfirmation>
    </saml2:Subject>
    <saml2:Conditions NotBefore="2022-01-12T16:59:07.362Z" NotOnOrAfter="2022-01-12T17:09:07.362Z">
        <saml2:AudienceRestriction>
            <saml2:Audience>c7bhamiqs3kro24r4peg</saml2:Audience>
        </saml2:AudienceRestriction>
    </saml2:Conditions>
    <saml2:AuthnStatement AuthnInstant="2022-01-12T17:04:07.362Z" SessionIndex="id1642007047361.940296625">
        <saml2:AuthnContext>
            <saml2:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport</saml2:AuthnContextClassRef>
        </saml2:AuthnContext>
    </saml2:AuthnStatement>
    <saml2:AttributeStatement>
        <saml2:Attribute Name="employeeId" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
            <saml2:AttributeValue
                xmlns:xs="http://www.example.com/2001/XMLSchema"
                xmlns:xsi="http://www.example.com/2001/XMLSchema-instance" xsi:type="xs:string">JoeDoe123
            </saml2:AttributeValue>
        </saml2:Attribute>
        <saml2:Attribute Name="mail" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
            <saml2:AttributeValue
                xmlns:xs="http://www.example.com/2001/XMLSchema"
                xmlns:xsi="http://www.example.com/2001/XMLSchema-instance" xsi:type="xs:string">test@example.com
            </saml2:AttributeValue>
        </saml2:Attribute>
        <saml2:Attribute Name="https://example.com/groups" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
            <saml2:AttributeValue
                xmlns:xs="http://www.example.com/2001/XMLSchema"
                xmlns:xsi="http://www.example.com/2001/XMLSchema-instance" xsi:type="xs:string">administrators
            </saml2:AttributeValue>
            <saml2:AttributeValue
                xmlns:xs="http://www.example.com/2001/XMLSchema"
                xmlns:xsi="http://www.example.com/2001/XMLSchema-instance" xsi:type="xs:string">super_users
            </saml2:AttributeValue>
        </saml2:Attribute>
    </saml2:AttributeStatement>
</saml2:Assertion>

  1. Go to Identity Providers and select an IDP from the list.

  2. Open the Attributes page. A standard list of attributes returned by this IDP appears.

  3. Select Add attribute.

  4. Fill in the attribute form.

    Source Description
    SAML assertion attribute name Attribute received within the SAML assertion sent by the IDP, for example employeeId, mail or groups from the above sample.
    Display name Name representing this attribute in Cloudentity
    Data type Data type of the incoming SAML attribute

    Claim names with a . character

    If the incoming attribute has a . character in the name, the dot must be explicitly escaped using \. when defining the IDP attribute. For example, claim name https://example.com/groups must be entered as https://example\.com/groups.

  5. Save your changes and proceed to mapping the attributes to the authentication context.

Map IDP attributes to authentication context

If you’ve added custom attributes for an IDP, you need to make sure they are mapped to the authentication context. You can do it either from the IDP configuration page (as explained here) or use Data Lineage instead.

Default OIDC/SAML attributes are mapped out of the box.

  1. Go to Identity Providers and select an IDP from the list.

  2. Open the Mappings page. A standard attribute mapping for this IDP appears.

  3. Select Add mapping and map any custom IDP attributes to an existing authentication context attribute.

    Note

    If you need to create new authentication context attributes, read Setting up authentication context.

  4. Optionally, assign a post-authentication extension to modify your authentication context before issuing the token to the client. Attributes returned by the script do not need to be separately mapped to the authentication context.

  5. Save your changes. Your mapped custom attributes should now be shared in the ID token issued to your client application, given that the target application requests them (you can check this in Data Lineage).

Connect Extensions to your IDP

  1. Go to Identity Providers > YOUR_IDP > Extensions.

  2. Assign a Post Authentication script to the IDP. This script will be executed upon user authentication via this IDP.

  3. Connect your application to the IDP in the Post Authentication application field. Users will be redirected to this application upon authentication via this IDP.

    Feature flag

    Post Authentication applications must be explicitly enabled in your tenant using the custom_apps feature flag.

Test Okta SAML IDP Integration

Prerequisites

  • Your IDP is enabled for user authentication.
  • Demo workspace is created with the Demo Portal connected.

Test

  1. Open the Demo Portal (Data lineage -> Demo Portal -> Launch).

  2. Select LOGIN TO DEMO APP.

  3. Select your configured SAML IDP and, next, authenticate in IDP.

Result

Cloudentity displays the consent page that lists data scopes to be shared with the application. When you proceed to the application (ALLOW ACCESS), the PII data coming from Okta is delivered through the access token and the ID token generated by Cloudentity.

Read more

For information on granting and managing Cloudentity consents, see Cloudentity OAuth consents.

Updated: Feb 14, 2023