Skip to main content
Skip table of contents

Configure OKTA SAML 2.0 integration

Okta can integrate with SAML 2.0 applications as an IdP that provides SSO to external applications. Okta also supports MFA prompts to improve your 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.


Steps

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

CODE 
//  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

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

Create AppBase SAML AuthConfiguration

  1. On 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 assigned by the SCIM service.

  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.

Configure SCIM synchronization in Generic - None OIN (OKTA integration Network) application

Prerequisites: At this point, you must have successfully configured AppBase SAML type "Auth Configuration" to interact with OKTA.

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.

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 the SCIM for your OKTA Application.

  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.

    Eventually, it will be necessary to delete some existing default attributes from the list and add some 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 configuration.

    Ensure that only the attributes listed above are in the configuration and all are set to Create and update.

  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 troubleshooting on AppBase, find helpful information on the SCIM Provisioning Errors page and AppBase I01\SCIM.log files.


JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close