Configure OKTA SAML 2.0 integration

OKTA can integrate with SAML 2.0 applications as an IdP that provides SSO to external applications. It also supports MFA prompts to improve application security.

When users request access to an external application registered with Okta, they're redirected to Okta. As the IdP, Okta then delivers a SAML assertion to the browser. The browser uses the assertion to authenticate the user to the SP.

1. The user attempts to access applications protected by Okta using SAML for SSO.
2. Client applications act as SAML Service Providers and delegate the user authentication to Okta. The client applications send a SAML assertion to Okta to establish the user session.
3. Okta acts as the SAML IdP and uses SSO and MFA to authenticate the user.
4. Okta returns an assertion to the client applications through the end user's browser.
5. The client applications validate the returned assertion and allow the user access to the client application.

Configure Okta to AppBase SSO with 'Eccentex AppBase' OIN (OKTA integration Network) Application

Create AppBase SAML AuthConfiguration

1. Go to App Studio →  User Management → Auth Configurations.
2. Click the Add SAML button to create a new SAML configuration.
   

   

3. Fill out all fields as described in the following screenshot. Some fields are configured automatically by AppBase based on the installation hostname. Pay attention to highlighted fields.

   

   Since you don't have actual values from OKTA, you can fill mandatory fields with dummy values and replace them later when you get the OKTA values.

   

4. Since you created the AppBase SAML Auth configuration for your tenant, you can access it using the URL https://abcde.appbase.com/Ecx.Web/Account/asc?tenantCode=TENANTxx&authCode=1111111-2222-3333-4444-1A1A1A1A1A1A1A1A where abcde.appbase.com is your website name; tenantCode is the tenant code; authCode is your SAML Auth Configuration code.
5. To find out the tenantCode and authCode go to the SAML configuration detail page. Use the Code value for the authCode url parameter. Find your domain parameter in the URL. It would most likely look like "d=XXXX." The tenant code is "XXXX." See the image below.
   

   

OKTA App Setup

1. Login into the OKTA Admin panel.
2. Click the Browse App Catalog button in the OKTA Admin → Applications section.
   

   

3. Type Eccentex AppBase in the search box to find our application and select it.
   

   

4. Click on the Add Integration button.
   

   

5. On the General Settings tab, click on the Done button.
   

   

6. In the App Settings page, type in your values into the application configuration, and click the Save button.
   

   

7. Go to the Assignments section on the OKTA App configuration.
8. Click the Assign dropdown list and select Assign Groups item.
   

   

9. Click the Assign link close to the required group name and click the Done button when finish.
   

   

10. Open your app metadata URL.
11. Click on the Sign On section of your OKTA App, copy the Metadata URL Navigate to this URL in a new browser window to find the required values to finish the AppBase configuration.

    

12. On AppBase, click the Edit button of your SAML Configuration and finish the configuration using the values from OKTA App metadata.
    

    

13. Replace the dummy placeholders inserted in a previous step with the HTTP-POST URL obtained from the metadata file. Use the screenshot below as a reference.
    

    

14. When finished, click the Save button.

15. In OKTA, under the SAML Signing Certificates download the OKTA certificate by clicking the Actions dropdown list and select the Download certificate option.

    

    After the certificate is downloaded, change its original extension (.cert) to .cer

    

    
    

16. On AppBase, click the Edit button of your SAML Configuration and finish the configuration as described in the below screenshot.
    

    

17. When finished, click the Save button.
18. Under the User Roles tab, assign the default roles by pressing the Edit button. We recommend assigning only the System: Allow My workspace role and managing all other groups/roles related to business logic via SCIM or LDAP synchronization.
19. Select the role (1), then click the Add button (2)
20. Click the Save button (3).
    

    

Configure Okta to AppBase SSO with Generic- None OIN (OKTA integration Network)

Please disregard this whole section if you already configured SSO using 'Eccentex AppBase' OIN application and proceed to Configure SCIM synchronization section of this document, or continue with this section if you are planning to configure the OKTA Generic SAML App.

SSO Supported Features

The Okta/Eccentex AppBase SAML integration currently supports the following features:

• SP-initiated SSO
• IdP-initiated SSO
• JIT (Just-In-Time) Provisioning
• SCIM integration

Generate required certificates

AppBase SAML configuration requires a private .p12 certificate (MUST INCLUDE PRIVATE KEY) to sign AppBse SAML requests and a mutual .cer (public key) certificate to validate SAML requests signature provided by OKTA.

You can generate it with any tools available to you. If you don't know how to do it, here are OpenSSL tool instructions:

Use the OpenSSL utility to generate SHA-256 certificates. Run the following commands to prepare your certificates:

//  Generate private key, make sure that you save password
openssl req -x509 -newkey rsa:2048 -keyout appbase_private_key.pem -out CACert.crt -days 512 -config ..\openssl.cnf

//Export the public key
openssl x509 -inform PEM -in CACert.crt -outform DER -out appbase.cer

// Convert private key to .p12 format
openssl pkcs12 -export -out appbase.p12 -inkey appbase_private_key.pem -in CACert.crt

At the end, you should have the following files in your folder:

• CACert.crt – certificate authority
• appbase.cer – public certificate from Service Provider (AppBase) in DER format, must be passed to Okta admins
• appbase.p12 – private certificate (with password), you must upload it on the SAML Configuration page 
• appbase_private_key.pem – private certificate in PEM format. You don’t need this

Create AppBase SAML AuthConfiguration

1. On the top right, navigate to

   

   → App Studio.
2. Go to User Management → Auth Configurations. click the Add SAML button.
   

   

3. Fill out all fields as described in the following screenshot. Some fields of AppBase will be configured automatically based on your installation hostname. Since you don't have actual values from OKTA at this moment, you can fill mandatory fields with dummy values and replace them later with OKTA values. Pay attention to the highlighted fields.
   

   

OKTA SSO Setup

1. To find out your tenantCode and authCode navigate to your SAML configuration detail page. Use Code value for authCode URL parameter. Find your domain parameter in the URL. Most likely, it would look like "d=XXXXX." The tenant code is the "XXXXX" part. See the image below.
   

   

2. Since you created AppBase SAML Auth configuration for your tenant, you will be able to access it by URL:
   https://skim.appbase.com/Ecx.Web/Account/asc?tenantCode=TENANT1&authCode=1F368B20-5555-AAAA-6666-576CB48A566D
   where skim.appbase.com is your website name, tenantCode is your tenant code, and authCode is your SAML Auth Configuration code.
3. Login to your OKTA account as an administrator and go to Applications. Press "Create App Integration" button
   

   

4. Select "SAML 2.0"
   

   

5. Type "App Name" and press "Next" button
   

   

6. Compose your URL for the Single Sign-On URL field. https://skim.eccentex.com/Ecx.Web/Account/ASC?tenantCode=tenant1&authCode=ffae87f9-AAAA-5555-CCCC-a93884aed7cd where skim.eccentex.com is your website name,  tenantCode is your tenant code, and authCode is your SAML Auth Configuration code.
   

   

   
   
7. Configure all fields the same way you see them in the following screenshot.
   

   

   
   
8. Press Next button.
9. Press Finish button.
   

   

10. Click on the View SAML setup Instructions button.
    

    

11. Click the Download certificate button. If the file is downloaded with the .crt extension, rename it to *.cer.
    

    

    
    We can finish the AppBase Auth Configuration with these values and the Certificate.
12. Go to App Studio → User Management → Auth Configurations.
13. Select your configuration and click the Edit button.
    

    

14. Use the OKTA configuration URLs to complete the Auth Configuration setup.
    

    

15. Go to App Studio → User Management to configure the default groups and roles for your SAML Auth Configuration. They would be applied to newly onboarded users.

    

    If you are planning to use SCIM Synchronization, we recommend to add only the System: Allow My Workspace(System, Configuration Environment) role. All other business logic access will be managed automatically via groups the SCIM service assigns.

16. To configure the User Roles, click the Edit button, then select the role by clicking the checkbox (1) and using the Play Arrow button (2) to move the role to the Seeted Roles section, click the Save button (3) to save the configuration.
    
    

    

17. Close the tab.
18. Log out from AppBase.
19. Return to your OKTA admin console and assign the groups accessing this application.
    

    

20. Sign in with the OKTA account.
    

    

21. Find and click on your app.
    

    

22. Logout from AppBase.

Configure SCIM Synchronization

SCIM Prerequisites 

To configure SCIM, you must have configured the AppBase SAML type "Auth Configuration," which interacts with OKTA successfully.

SCIM Features

The following provisioning features are supported by Reftab at present:

• Push Users: Users in Okta that are assigned to the Reftab application within Okta are automatically added as users in Reftab
• Update User Attributes: When user attributes are updated in Okta, they will be updated in Reftab.
• Deactivate Users: When users are deactivated in Okta, they will be set to ‘disabled’ within Reftab – which prevents the user from logging into Reftab. 
• Push Groups: Groups and their users in Okta can be pushed to Reftab. (Group information from Okta can be used to map users to Reftab access roles.)

Enable SCIM for your AppBse SAML Auth configuration

1. On the top right, navigate to 

   

   → Manage Users

2. Go to User Management (1) → Auth Configurations (2), then find your auth configuration and open it by clicking on the name link (3)
   

   

3. Click the Enable SCIM button in the tab bar. On the popup window, confirm your action by clicking the Yes button.
   

   

Configure the User Attributes Mapping

1. Under the User Attributes Mapping tab, enable the synchronization. Use the following screenshot as a reference.
   

   

Create SCIM bearer authorization token in AppBase

1. Navigate to User Management (1) → SCIM Authorizations (2) and click the Add New button (3).
   

   

2. On the Issuer field, type a name of your choice. In our example, we entered 'okta.'
3. From the Auth Configuration dropdown, select the OKTA SAML single sign-on to synchronize via SCIM.
4. Choose an Expiration Date.
5. Inser a brief Description.
6. Save your configuration.
   

   

7. After successfully saving it, find the Auth configuration just created on the SCIM Authorizations list. Open the configuration by clicking the Show Token (1) button.
   

   

8. From the popup window, use the Copy to clipboard button to save the token in a safe place. It is needed in the following steps.
   

   

   

   SCIM authorization token is considered highly secure information. Please do not share it with anyone except authorized personnel in your organization.

   If you need to share it with someone authorized, use only secure tools approved by your company policy.

Configure SCIM using Eccentex AppBase OKTA  OIN (OKTA integration Network) application

1. Click on the Browse App Catalog button in OKTA admin → Applications section.
   

   

2. Type Eccentex AppBase In the search box, choose our application (Eccentex AppBase).
   

   

3. Click on the Add Integration button.
   

   

4. Click on the Done button.
   

   

5. Click on the Configure API Integration button under the Provisioning Section.
   

   

6. On the next window, select the Enable API Integrations checkbox (1).
7. Provide your SCIM base URL (2).
8. Provide the SCIM  authorization token (3).
9. Click the Test API Credentials button (4) when done.
   

   

10. Wait for the successful test confirmation message(1), then press the Save button (2).
    

    

11. Click the Edit button on Provisioning → To App Section.
    

    

12. Enable all the selected checkboxes shown in the image below, click the Save button.
    

    

13. Go to Assignments section of Okta app configuration and then on the Assign dropdown button, select the Assign to Groups item.
    

    

14. Assign all the required groups and click the Done button when finished.
    

    

15. Go to Push Groups section of the Okta app configuration and then click the Push Groups dropdown button, select the Find groups by name item.
    

    

16. To search for the groups, start typing the group name and choose all the required groups from the popup list.
17. Click the Save button when done.
    

    

Congratulations!. You have finished the configuration of Okta SCIM synchronization.

Some synchronization actions may take some time on the Okta side. Wait until the synchronization is complete.

Configure SCIM using OKTA Generic - None OIN (OKTA integration Network) application.

You may disregard this section if you have configured SCIM using the Eccentex AppBase OKTA OIN application in the previous step.

1. On OKTA, navigate to Application → Applications (1).
2. Open the OKTA application settings window (2).
3. Select the General (3) tab and on the App Settings section, click the Edit button (4).
   

   

4. On the Provisioning field, select the SCIM (1) option.
5. Save (2) your configuration.
   

   

6. In the Provisioning tab, complete all the fields as follows.
7. In the SCIM connector base URL, insert the SCIM endpoint URL.
8. In the Unique Identifier field for users, type userName.
9. In the Supported provisioning actions select the following actions : Push New Users, Push Profile Updates, and Push Groups.
10. For Authentication Method, select HTTP Header from the dropdown list.
11. In the Authorization field, insert the SCIM Authorization token obtained from AppBase in the previous step.
12. Test the configuration by clicking the Test Connector Configuration button
13. If the test is successful, click the Save button.
    

    

14. Following is an example of a successful connection test
    

    

15. Navigate to Provisioning → To App section of the Okta app configuration.

16. Configure the following mapping attributes as Create and update.

    

    Make sure that only the following attributes are present in the configuration and all of them are set to Create and update. Eventually, it will be necessary to delete some existing default attributes from the list or add attributes that are not present.

    1. Username
    2. Given name
    3. Family name
    4. Email
    5. Title
    6. Primary phone
    7. Street address
    8. Locality
    9. Region
    10. Postal Code
    11. Country

17. See the screenshot below for an example of the correct configuration.

    

18. In the Provisioning tab of the Okta App configuration, click the Edit button next to Provisioning to App.
    

    

19. Enable the Create Users, Update User Attributes, and Deactivate Users options.
    

    

20. Save the configuration by clicking the Save button.

21. Navigate to the Assignments tab of Okta app configuration.

22. Click on the Assign button and select the Assign Groups item.
    

    

23. In the popup window, assign the required groups and press the Done button when finished.
    

    

24. Navigate to the Push Groups tab of the Okta app and expand the Push Groups dropdown, click on the Find groups by name item.
    

    

25. Start typing the group name, and choose the required group from the popup list by clicking on its name.
    

    

26. Save when finished.
    

    

Congratulations! You have finished the configuration of Okta SCIM synchronization.

Some synchronization actions may take some time on the Okta side. Wait until the synchronization is complete.

Troubleshooting the SSO

If there are any issues, check the OKTA logs for the application. On AppBase, check for the I01\Ecx.Web log files.

Troubleshooting SCIM

To troubleshoot on AppBase, find helpful information on the SCIM Provisioning Errors page and AppBase I01\SCIM.log files.

SCIM Configuration Limitations

1. Querying groups with the GET method on the ~SCIM/GROUPS API endpoint will not return the membership values for the listed groups. See an example of a response in the following image:
   

   

2. While retrieving specific groups by ID via the GET method for the URL ~SCIM/GROUPS/XXXXXXIt returns an array with all the members assigned to the group or an empty array if no members are assigned to it.
   1. Example of response for Assigned members:
      

      

   2. Example of response for No members assigned: