Configure Okta Authentication
Requires Platform Server Release Jul.2019 CP2 (11.0.542.0) or later.
OutSystems allows you to use Okta for authenticating the end users of your OutSystems applications. This authentication method is configured in a way that's quite similar to the SAML 2.0 one.
The limitations of the current SAML 2.0 implementation also apply to Okta. Be sure to check them when using Okta end user authentication.
Configuring Okta
To configure Okta authentication you must take these general steps:
- Configure general Okta authentication settings in Users app
- Create application in the Okta portal
- Configure SAML settings of Okta application
- Finish configuration in the Users app
- Assign user or group to Okta application
- Test your configuration
- Configure user roles in the Users app
- Perform some final checks and configurations
The following sections describe these steps in detail.
Configure general Okta authentication settings in Users app
-
In the Users application, click Configure Authentication in the right sidebar.
-
In Authentication choose
OKTA
(A). -
Fill the 1. Service Provider Connector Settings (B). OutSystems suggests that you use the following values for the settings under Attribute Statements (Claims):
Given Name Attribute =
given
Surname Attribute =surname
Email Attribute =email
Username Attribute =username
External Id Attribute =username
-
Click Download KeyStore Certificate to download the certificate PEM file.
Create application in the Okta portal
-
Sign in to the Okta portal and click Admin to go to the Developer Console.
-
Switch to the Classic UI view. Place your mouse cursor over Developer Console at the top of the page and select Classic UI.
-
Select Applications > Applications to open the Applications screen.
-
Click Add Application.
-
Click Create New App.
-
Select the platform
Web
and the sign-on methodSAML 2.0
. Click Create. -
Enter a name for your application and (optionally) select an app logo.
-
Click Next.
Configure SAML settings of Okta application
-
Configure the fields in General > SAML Settings.
Enter the values for the Single sign on URL and Audience URI (SP Entity ID) fields according to what's configured in the Users application.
-
Click Show Advanced Settings to show some more fields that you must configure.
Two particular configuration settings in Okta depend on the value of a setting in the Users app.
Get back to the Users app, scroll to the 1. Service Provider Connector Settings section, and click Show Advanced Options.
If the option Accept Only Signed Login Responses is enabled, activate the corresponding options in Okta:
-
Set the Response and Assertion Signature fields to Signed.
-
-
Select the Allow application to initiate Single Logout checkbox.
-
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. -
In the Signature Certificate field, click Browse... and select the certificate PEM file downloaded from the Users application.
-
Click Upload Certificate.
-
In the "Attribute Statements" section, add an attribute for each claim configured in the Users application by clicking Add Another.
Fill in the Name and Value fields according to the following suggested values:
Name =
given
(the value previously entered in Users) / Value =user.firstName
Name =surname
/ Value =user.lastName
Name =email
/ Value =user.email
Name =username
/ Value =user.login
Note: Names and values are case sensitive. Consider selecting values from the drop-down instead of typing them.
-
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 XML file.
Finish configuration in the Users app
Back in the Users app, upload the XML file you downloaded in the previous step.
-
Locate the 2. IdP Server Settings section in the Configure Authentication page.
-
Click Upload from IdP/Federation Metadata XML.
-
Select the Federation Metadata XML file you downloaded from Okta.
-
Click Save.
Assign user or group to Okta application
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 step-by-step instructions.
Test your configuration
-
Log out of the Users app if you're still logged in. The Users app redirects you to an Okta login page.
-
Enter the credentials of a user you previously associated with your Okta application in Assign user or group to Okta application.
If the authentication is successful, the browser redirects you back to the Users app and you get an error message about not having permissions to view the screen.
This happens because the user you used for testing Okta authentication doesn't have any assigned OutSystems roles yet. You need to grant user roles in the Users app after the user logs in for the first time using Okta authentication, so that the user already exists in the OutSystems database.
If the authentication is unsuccessful, double-check your configuration settings.
Configure user roles in the Users app
You're currently logged in with a user account that doesn't have the required permissions to grant roles to end users. You must first log in with an administrator account.
Do the following:
-
Log out of the Users app, since the current user doesn't have the required role.
-
Open the following URL:
https://<your_server_name>/Users/Login.aspx
Using this specific URL allows you to log in to the Users app skipping the external authentication method that's currently configured (Okta).
-
Log in with an administrator account.
You now have permissions to grant OutSystems roles to users. Check Grant a role to an end user for detailed instructions.
Perform some final checks and configurations
Just like when using SAML 2.0 authentication, you must perform these two final tasks:
-
Check if the authentication flows of your OutSystems application already support external authentication. The instructions provided for the SAML 2.0 authentication method are also applicable to Okta.
-
If you're using Okta authentication in Reactive Web Apps, enable the "Single Sign-On Between App Types" setting in Service Center.
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.