Configuring Okta in Jitterbit App Builder

Okta is an Identity Provider (IdP) which supports SAML Single Sign-On (SSO) authentication. App Builder integrates with Okta as a Service Provider (SP). Each App Builder instance must be integrated with Okta and vice versa. There are three main tasks involved:

1. Register App Builder as an Okta application.
2. Configure Okta as an App Builder security provider.
3. Map App Builder users to Okta identities.

It's assumed that your organization already has an existing Okta account.

The instructions below will refer to the following properties:

Register App Builder as an Okta application

The following Okta document describes how to register a SAML application: https://developer.okta.com/standards/SAML/setting_up_a_saml_application_in_okta

1. During the setup process, you will be prompted for the following information:

   • Name: App Builder environment name.\

     Example: App Builder Development

   • Single sign-on URL: Corresponds to the Assertion Consumer Service URL.\

     Example: https://example.com/App Builder/signin-Okta

   • Audience URI: Although the audience URI is arbitrary, Okta and App Builder must use the same Audience URI. Consider using the the App Builder App URL.\

     Example: https://example.com/App Builder/.

   • Name ID format: EmailAddress

   • Application username: Okta username

2. You may supply optional Attribute Statements or Group Attribute Statements claim mappings. Commonly mapped claims include:

   • Email Address - http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
   • Group Membership - http://schemas.xmlsoap.org/claims/Group

   Note

   See Claims for additional information regarding claims.

3. Click Next, select I'm an Okta customer adding an internal app, and click Finish.

4. Once the Okta application has been created, copy and store the following values for reference later:

   • Metadata URL. Example: https://www.okta.com/app/abcdef012345/sso/saml/metadata
   • Sign on URL. Example: https://example.okta.com/app/abcdef012345/sso/saml
   • Issuer. Example: http://www.okta.com/abcdef012345

Configure Okta as an App Builder security provider

To configure Okta as an App Builder security provider, start by signing into App Builder as an administrator.

1. Navigate to the IDE
2. Select the Security Providers button
3. In the User Authentication panel, click the + User Authentication button

4. Provide the following:

   • Name: Security Provider Name (see above)\

     Example: Okta

   • Type: SAML

   • Enabled: Check

5. Click the Save button

6. In the Tokens section, provide the following:

   • Audience: Audience URI (see above)

     Example: https://example.com/App Builder/

   • Recipient: Single sign-on URL (see above)

     Example: https://example.com/App Builder/signin-Okta

   • Issuer: Issuer (see above)

     Example: http://www.okta.com/abcdef012345

7. Click the Save button

8. In the Provisioning section, confirm the following settings:

   • User Provisioning: Check
   • Supplies Group Membership: Check
   • Store Claims: Check

9. In the Endpoints panel, click the + Endpoint button

10. Provide the following:

    • Type: Metadata Endpoint

    • URL: Metadata URL (see above)

      Example: https://www.okta.com/app/abcdef012345/sso/saml/metadata

11. Click the Save button

12. In the Claims panel, you will need to map any claims from Okta in App Builder. For example, to map the Group and E-mail Address claims, click the + Claim button

13. Provide the following:

    • Identifier: Claim type name.

      Example: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/Group

    • Usage: Claim type usage.

      Example: Group

14. Click the Save button

15. Exit the Claim screen and click the + Claim button from the Claims panel

16. Provide the following:

    • Identifier: Claim type name.

      Example: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress

    • Usage: Claim type usage.

      Example: E-mail Address

17. Click the Save button

18. In the Sign In section, check to enable Show On Login Form. This enables a Sign in with Okta button to display on the App Builder login page.
19. Click the Save button

Map App Builder users to Okta identities

With user provisioning

If you've enabled user provisioning as described above and attempt to sign in, you may be redirected back to the App Builder login form with the following message:

The user account (arthur.dent@example.com) has not been granted access to an application.

Although App Builder was able to successfully provision the user, the user does not have access to any App Builder applications by default. Assuming the Okta user has been added to one or more groups and that Supplies Group Membership is enabled (as described above), you will need to map the Okta security groups to App Builder security groups.

To map Okta security groups to App Builder security groups, start by signing into App Builder as an administrator.

1. Navigate to the IDE
2. Click the User Management button
3. Click the Identities tab
4. In the Provider Groups panel, locate the Okta group and click the Details icon (Popup)
5. Click the Edit button
6. From the Group list, select the App Builder group
7. Click the Save button

Please see the User and group provisioning for additional information.

Without user provisioning

If you have not enabled user provisioning, authentication will have failed with a message similar to the following:

Although you've successfully authenticated with Okta, the account arthur.dent@example.com (arthur.dent@example.com) is not associated with a local account.

In the message above, arthur.dent@example.com is the Okta User Name (called "name" in claims authentication). The part in parenthesis is the Okta Name Identifier (called the "name identifier" in claims authentication). You'll need these two pieces of information for the next step.

To map an App Builder user account to an Okta identity, start by signing into App Builder as an administrator:

1. Navigate to the IDE
2. Click the User Management button
3. In the Users panel, locate and select the user you would like to map
4. In the Identities panel, click the + Identity button

5. Provide the following:

   • Provider: Security Provider Name\

     Example: Okta

   • Name: Okta User Name (see above)

   • Identifier: Okta Name Identifier (see above)

6. Click the Save icon (Check)

Troubleshooting

The user is redirected back to the login page after signing in.

If User Provisioning has been enabled, then the user may have been created but not assigned to any groups or the groups that the user has been assigned to have not been granted access to any App Builder applications. The only group assigned to new users by default (i.e. has the Grant On User Create option enabled) is the Users group. This group is not granted access to any applications by default.

If the Supplies Group Membership option has been enabled, App Builder will have registered the Okta groups. Sign in as an administrator and map the Okta groups to App Builder security groups. If the Supplies Group Membership option has not been enabled, the Okta security provider will not have any groups. Sign in as an administrator and define one or more Okta security provider groups with the Grant On Identity Create option enabled and map the provider groups to App Builder security groups.

If the Require HTTPS security provider has not been enabled, the user may initiate the SAML SSO process from a non-secure URL (e.g. http://example.com/App Builder/). However, the Identity Provider will return the user to the secure Assertion Consumer Service (ACS) URL (https://example.com/App Builder/signin-Okta). App Builder authenticates the user in the context of the secure URL before returning the user to the non-secure URL. In effect, the user has two separate sessions. To address this issue, enable the Require HTTPS security provider.

The Okta application may be deactivated.

Error: "the audiencerestrictioncondition was not valid because the specified audience is not present in audienceuris."

This error indicates that the audience URI does not match. Ensure that the Audience property has been explicitly set. If not set, it will default to the current URL, which may vary by user. The value is case-sensitive.

Error: "an unhandled exception was caught at the end of the pipeline."

This error can indicate a mismatch between the configured Recipient value and the expected Recipient value in App Builder. Ensure that the Recipient value is configured properly.