Skip to content
LogScale Self-Hosted
This is an archived version of the documentation downloaded from LogScale Documentation Archives. Up to date documentation, and documentation for later versions, is available on LogScale Documentation

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

   Figure 53. Navigating to the Applications Section in Okta

2. Next, click Create App Integration.

   Figure 54. Starting the App Integration Process

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

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

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

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

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

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

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

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

#### Enter search term