Configure Okta Authentication

Configure general Okta authentication settings in Users app

1. In the Users application, click Configure Authentication in the right sidebar.

2. In Authentication choose OKTA (A).

   

3. 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

4. Click Download KeyStore Certificate to download the certificate PEM file.

   

Create application in the Okta portal

1. Sign in to the Okta portal and click Admin to go to the Developer Console.

   

2. Switch to the Classic UI view. Place your mouse cursor over Developer Console at the top of the page and select Classic UI.

   

3. Select Applications > Applications to open the Applications screen.

   

4. Click Add Application.

   

5. Click Create New App.

   

6. Select the platform Web and the sign-on method SAML 2.0. Click Create.

   

7. Enter a name for your application and (optionally) select an app logo.

   

8. Click Next.

Configure SAML settings of Okta application

1. 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.

   

2. 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.

     

3. Select the Allow application to initiate Single Logout checkbox.

   

4. 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.

5. In the Signature Certificate field, click Browse... and select the certificate PEM file downloaded from the Users application.

   

6. Click Upload Certificate.

7. 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.

   

8. After creating and filling in the fields, click Next.

9. Answer the question Are you a customer or a partner? accordingly to your situation and click Finish.

   

10. 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.

1. Locate the 2. IdP Server Settings section in the Configure Authentication page.

2. Click Upload from IdP/Federation Metadata XML.

   

3. Select the Federation Metadata XML file you downloaded from Okta.

4. 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

1. Log out of the Users app if you're still logged in. The Users app redirects you to an Okta login page.

2. 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:

1. Log out of the Users app, since the current user doesn't have the required role.

2. 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).

3. 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:

1. 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.

2. If you're using Okta authentication in Reactive Web Apps, enable the "Single Sign-On Between App Types" setting in Service Center.