OutSystems allows you to use OKTA for authenticating the end users of your OutSystems applications. This authentication method is configured in a way that is quite similar to the SAML 2.0 one.
The limitations of the current SAML 2.0 implementation also apply to the OKTA authentication method. Be sure to check them when using OKTA end user authentication.
To set up OKTA authentication for end users do the following:
Sign in to the OKTA administration page and make sure that you're using the "Classic UI" view. Select Applications > "Applications" to open the Applications screen, and then click Add Application.
Click Create New App.
Select the platform
Weband the sign-on method
SAML 2.0. Click Create.
Enter a name for your application and (optionally) select an app logo. Click Next.
In the Users application, choose
OKTAin Authentication and fill the 1. Service Provider Connector Settings.
We suggest that you use the following values for the fields in the Attribute Statements (Claims) section:
Given Name Attribute =
Surname Attribute =
Email Attribute =
Username Attribute =
External Id Attribute =
Download the keystore certificate by clicking (Keystore certificate).
This file will be used later when doing the configurations in the OKTA portal (step 9).
In the OKTA portal, configure the fields in General > "SAML Settings" by entering the values for the Single sign on URL and Audience URI (SP Entity ID) fields as displayed or as configured before in the Users application (step 5).
Before continuing, click Show Advanced Settings to show some more fields that you will need to configure.
Select the Enable Single Logout checkbox and fill in the Single Logout URL and SP Issuer fields with the corresponding values from the Users application.
Fill in the SP Issuer field with the same value you entered for the Audience URI (SP Entity ID) field (step 7).
Upload the certificate file downloaded from the Users application (step 6) in the Signature Certificate field.
In the "Attribute Statements" section, add an attribute for each claim configured in the Users application by clicking Add Another until you have a total of four lines of attribute statements.
Fill in the Name and Value fields of the four rows according to the following suggested values:
given(i.e. the value previously entered in Users) / Value =
surname/ Value =
username/ Value =
After creating and filling in the fields, click Next.
Answer the question Are you a customer or a partner? accordingly to your situation and click Finish.
Right-click the Identity Provider metadata link and select Save Link As to download the Identity Provider (IdP) metadata file.
In the Users application, upload the metadata file obtained in the previous step by clicking Upload from IdP/Federation Metadata XML and then click Save.
Make sure you assign your new OKTA application to a user or a group to be able to proceed. You can do this operation in the OKTA portal. Check OKTA's documentation for more information.
Test your new authentication settings by logging in the Users application again.
Logout of the Users application if you're logged in.
The Users application will redirect you to an OKTA login page. Enter your OKTA user credentials.
If the authentication is successful, you will be redirected to the Users application.
You may get an "Invalid Permissions" message if the OKTA user is logging in for the first time, since the user is provisioned in OutSystems at this point and it still doesn't have any associated roles. You will need to configure the user roles after the user's first login.
If the authentication is unsuccessful, double-check your configuration settings.
Note: If you're using an older version of OutSystems UI you will need to change the logout flow of your OutSystems applications, as described for the SAML 2.0 authentication method. Check Change the Logout flow of your OutSystems applications for more information.
Troubleshooting OKTA authentication issues
Since the OKTA end user authentication method is very similar to the SAML 2.0 one, you can troubleshoot them in the same way:
- Check the SAML Message Logs page for detailed information on OKTA messages exchanged for end user authentication.
- Use the same method for accessing the Users application when you're locked out due to incorrect configuration settings in end user authentication.