Okta

Learn how to integrate Okta's SAML authentication with LogScale, including step-by-step guidance for creating and configuring an Okta application, setting up SAML attributes, and establishing the necessary connection parameters. Understand essential security requirements, configuration steps for both LogScale Cloud and self-hosted installations, and advanced features such as customizing email invite addresses through Okta's mapping mechanisms.

LogScale allows for the integration of many applications. If you want to integrate Okta into LogScale, you can do so by creating an application (i.e., an app) in Okta. To do this, you have to use Okta's system, in particular the SAML (Security Assertion Markup Language) section. This is used to authenticate and authorize the app.

Prerequisites for Okta configuration

Prior to performing the steps below, make sure that you have a fully activated Okta account.

Create an app in Okta

Log in and navigate to the main page of the Okta interface:

  1. Click Adminto navigate to the Admin Dashboard. From there, click Applications and select Applications.

    Screenshot of the Okta Admin Dashboard showing the Applications navigation menu with the Applications option highlighted

    Figure 59. Navigating to the Applications Section in Okta


  2. Next, click Create App Integration.

    Screenshot of the Okta Applications page with the 'Create App Integration' button highlighted

    Figure 60. Starting the App Integration Process


  3. Select SAML 2.0 for the sign-in method. Then click, Next.

    Screenshot of the Okta Create a new app integration page showing sign-in method options with SAML 2.0 selected

    Figure 61. Selecting SAML 2.0 as the Sign-in Method


  4. Give the application a name, such as LogScale. You can also upload an image for the app logo. You can use our logo for this purpose:

    Click Next to continue.

    Screenshot of the Okta app creation page showing the General Settings form where you enter the application name and upload a logo

    Figure 62. Configuring App Name and Logo


  5. In the General area of the SAML Settings configuration section, you will need to set a few values to tell Okta how to connect to LogScale. The table below lists all of the fields you need to set, and the values to give them:

    Field Value
    Single Sign on URL http(s)://$YOUR_LOGSCALE_URL/api/v1/saml/acs
    Use this for Recipient URL and Destination URL Checked/selected
    Audience URI (SP Entity ID) http(s)://$YOUR_LOGSCALE_URL/api/v1/saml/metadata
    Default relay state Leave blank
    Name ID Format EmailAddress
    Application Username Email
    Update application username on Create and update

    The following screenshot can assist you in understanding better where these values are entered.

    Screenshot of the Okta SAML Settings configuration page showing the General section with fields for Single Sign-on URL, Audience URI, Name ID Format and other SAML parameters

    Figure 63. Configuring SAML General Settings


  6. Next, you'll have to add a single attribute in the Group Attribute Statements area of the SAML settings configuration. Set its Name to a value of group, with the Name format set to Basic. Set the Filter to Matches regex with the value as .* Click Next.

    Screenshot of the Okta SAML Settings page showing the Group Attribute Statements section with the 'group' attribute configured with a regex filter of '.*'

    Figure 64. Setting Up Group Attribute Statements


  7. For the Feedback step, select I'm an Okta customer adding an internal app. Check the box where it says, This is an internal app that we have created. Click Finish.

    Screenshot of the Okta Feedback page where 'I'm an Okta customer adding an internal app' is selected and 'This is an internal app that we have created' is checked

    Figure 65. Completing the App Integration Feedback


  8. The next page shows a detailed view of the application you just created. Scroll down until you see View SAML Setup Instructions in the right sidebar. Click View SAML Setup Instructions.

    Screenshot of the Okta application details page with the 'View SAML Setup Instructions' button highlighted in the right sidebar

    Figure 66. Locating the SAML Setup Instructions


  9. The SAML Setup Instructions provides you with three key pieces of information you'll need to configure LogScale to work with Okta:

    • the Identity Provider Single Sign-On URL

    • the Identity Provider Issuer

    • the X.509 Certificate. Click Download certificate to save the okta.cert certificate to your computer in the certs directory where your where your native LogScale is running. If you do not have a certs folder, create one.

    Leave the page open for reference while configuring LogScale.

    Screenshot of the Okta SAML Setup Instructions page showing the Identity Provider Single Sign-On URL, Identity Provider Issuer, and X.509 Certificate that need to be used to configure LogScale

    Figure 67. Viewing Critical SAML Configuration Information


At this point, Okta is configured to work with LogScale. The next step is to configure LogScale to work with your Okta app.

Configure LogScale for Okta

After you have prepared Okta for integrating with LogScale, you need to configure LogScale.

To configure Okta to work with LogScale, you must set the configuration variables as described in Configure SAML for LogScale Self-Hosted.

Assign the app to users in Okta

When you finish preparing LogScale, go to the Sign On tab in Okta. In the Settings section, click Edit. This provides you an input box, Default Relay State. Paste the Integration URL for LogScale into that field and save when done.

You need to give users in Okta permissions to use the app. Assign the application to any users or groups you want to have access to LogScale. For instructions about how to do this, see Okta's instructions. Note that the user name you enter must be an email address. Otherwise, if everything went according to the instructions on this page, you're now ready to use Okta with LogScale.

Customize the email invitation address

You can modify the email address that Okta sends to the user as the login email to use for authentication with LogScale. This is useful if emails change, domains change, or if there are multiple email domains and want to use a single domain as the identifying email address.

To achieve this, the email address must be transformed as part of the mapping process within your Okta configuration:

  1. Go to the Okta configuration and choose Profile Editor → LogScale App → Mappings → Okta to LogScale.

  2. Edit the mapping using the Okta expressions mechanisms. In the example below, the domain name is being stripped from the email address (after the @) and then reconstructed to the new email address: 

    String.substringBefore(source.email, "@")+"-"+$appuser"+"@"+String.substringAfter(source.email, "@")

For more information on expressions, see Modify attributes with expressions and Okta Expression Language overview guide Okta documentation pages.

Test the Okta integration setup

Once all of the necessary steps to set up the Okta authentication for LogScale are completed, you need to test the setup.

  1. Go to a Terminal and start LogScale with the following command:

    shell
    ./run.sh

    Allow two to three minutes for LogScale to start.

  2. Connect to localhost in a browser. It should redirect you to a Okta login.

  3. Sign into your Okta. You should be taken to LogScale.