> For the complete documentation index, see [llms.txt](https://docs.enginsight.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.enginsight.com/docs/knowledge-base/english/miscellaneous/how-do-i-set-up-single-sign-on-sso-via-microsoft-365-in-enginsight.md).

# How do I set up single sign-on (SSO) via Microsoft 365 in Enginsight?

In addition to logging in via username and password, the Enginsight platform allows you to sign in via single sign-on (SSO) using Microsoft 365. 

In the following, we will show you which steps you need to take to configure SSO.

***

## Prerequisites

* A user account in the **Microsoft 365 tenant**.
* At least the **Application Developer** role to **register an application**.
* The Enginsight platform must be able to reach `login.microsoftonline.com` via HTTPS. For on-premises installations, this outbound traffic must be allowed in the firewall or proxy.

***

## Registering Enginsight in Microsoft Entra ID

{% stepper %}
{% step %}

### Open the Microsoft Entra Admin Center

1. Open `https://entra.microsoft.com` in a browser. Alternatively, you can open `https://portal.azure.com` and search for **Microsoft Entra ID**. The pages are identical.
2. Sign in with the administrator account.
3. If you have access to multiple tenants, use the **Settings** icon (gear) in the top menu to switch to the tenant you want to connect. The tenant name is shown in the top right.
   {% endstep %}

{% step %}

### Register a new application

Register Enginsight as a new application in Microsoft Entra ID. For more information, see the [official vendor documentation](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app).

{% hint style="warning" %}
**Please note**: Enginsight assumes no liability for the content and topicality of third-party documentation.
{% endhint %}

Enter the following values:

* **Name**: The name can be chosen freely and is only shown in the Microsoft Entra ID portal. We recommend that you use a descriptive name such as *Enginsight SIEM Identity Provider*.
* **Supported account types**: Select **Single tenant only – \<your tenant>** as the supported account type. In older views, this option is called **Accounts in this organizational directory only**.
  {% endstep %}

{% step %}

### Add a redirect URI

In the **Redirect URIs** field, add a redirect URI as follows:

```
https://<DomainAPI>/v1/users/login
```

{% hint style="info" %}
Remember to replace `<DomainAPI>` with the domain of your Enginsight API.
{% endhint %}
{% endstep %}

{% step %}

### Get the client ID and tenant ID

After registration, you are redirected to the overview page of the new application.

Here you can find both the **client ID** (also referred to as **application ID**) and the **tenant ID** (also referred to as **directory ID**). You will need this information later when [adjusting the Enginsight configuration](#adjusting-the-enginsight-configuration-file).
{% endstep %}

{% step %}

### Create a client secret

1. Create a **client secret** (also referred to as **app secret**) for the new application. For more information, see the [official vendor documentation](https://learn.microsoft.com/en-us/entra/identity-platform/how-to-add-credentials?tabs=client-secret).

{% hint style="warning" %}
**Please note**: Enginsight assumes no liability for the content and topicality of third-party documentation.
{% endhint %}

Enter the following values:

* **Description**: The description can be chosen freely.
* **Expires**: Define a lifetime for the client secret. Microsoft Entra ID allows a maximum of 24 months. Choose the longest lifetime permitted by your security policy and note the expiry date.

{% hint style="warning" %}
**Please note**: We recommend that you set up up a calendar reminder a few weeks before the client secret expires so that you can replace the client secret in time. The Microsoft Entra ID portal shows the expiry date in the client secrets list and marks expired secrets in red.
{% endhint %}

2. Copy the client secret and store it in a secure location.

{% hint style="danger" %}
**Please note**: When you add a client secret in Microsoft Entra ID, it is shown **only once immediately after creation and never again**. Make sure to note the client secret immediately after creating it.
{% endhint %}
{% endstep %}

{% step %}

### Alternatively: Create a client certificate

Instead of the client secret, you can also create a **client certificate** (also **app certificate**). For more information, see the [official vendor documentation](https://learn.microsoft.com/en-us/entra/identity-platform/howto-create-self-signed-certificate).

{% hint style="warning" %}
**Please note**: Enginsight assumes no liability for the content and topicality of third-party documentation.
{% endhint %}
{% endstep %}
{% endstepper %}

***

## Adjusting the Enginsight Configuration File

{% stepper %}
{% step %}

### Open the Enginsight configuration file

1. Log in to the **Enginsight Application Server**.
2. Open the Enginsight configuration file using the following command:

```
sudo nano /opt/enginsight/enterprise/conf/services/config.json
```

{% endstep %}

{% step %}

### Add the Microsoft authentication section

For authentication via Microsoft, in addition to your Client ID, you can add ***either*** your Client Secret ***or*** your Client Certificate.

#### Option 1: Client Secret

If you want to use your **Client Secret**, add the following section to the configuration file:

<pre><code>"microsoftAuthenticationLibrary": [{
    "scope": "\\@.*",
<strong>    "clientId": "&#x3C;ClientID>",
</strong><strong>    "clientSecret": "&#x3C;ClientSecret>",
</strong><strong>    "authority": "https://login.microsoftonline.com/&#x3C;TenantID>"
</strong>   }],
</code></pre>

{% hint style="info" %}
Remember to replace the following placeholders in `<>` accordingly:

* `<ClientID>`
* `<ClientSecret>`
* `<TenantID>`
  {% endhint %}

#### Option 2: Client Certificate

If you want to use your **Client Certificate**, add the following section to the configuration file:

<pre><code>"microsoftAuthenticationLibrary": [{
    "scope": "\\@.*",
<strong>    "clientId": "&#x3C;ClientID>",
</strong>    "clientCertificate": {
<strong>      "thumbprint": "&#x3C;ClientCertificateThumbprint>",
</strong><strong>      "privateKey": "&#x3C;ClientCertificatePrivateKey>"
</strong>    },
<strong>    "authority": "https://login.microsoftonline.com/&#x3C;TenantID>"
</strong>  }],
</code></pre>

{% hint style="info" %}
Remember to replace the following placeholders in `<>` accordingly:

* `<ClientID>`
* `<ClientCertificateThumbprint>`
* `<ClientCertificatePrivateKey>`
* `<TenantID>`
  {% endhint %}

Adjust the following parameters accordingly:

<table><thead><tr><th width="315.203125">Parameter</th><th>Description</th></tr></thead><tbody><tr><td>Scope</td><td>You can use the <code>scope</code> attribute to restrict the SSO configuration to a specific Active Directory domain.<br><br>In most cases, however, no restriction is required and the default value <code>\\@.*</code> can be left unchanged.</td></tr><tr><td><code>&#x3C;ClientID></code></td><td>Enter the Client ID (Application ID) of the Enginsight application registered in Microsoft Entra ID.</td></tr><tr><td><code>&#x3C;ClientSecret></code></td><td>Enter the Client Secret (App Secret) for the Enginsight application registered in Microsoft Entra ID.</td></tr><tr><td><code>&#x3C;ClientCertificateThumbprint></code></td><td>Enter the thumbprint of the Client Certificate (App Certificate), meaning the unique cryptographic hash value that identifies the certificate, for the Enginsight application registered in Microsoft Entra ID.</td></tr><tr><td><code>&#x3C;ClientCertificatePrivateKey></code></td><td>Enter the private key of the Client Certificate for the Enginsight application registered in Microsoft Entra ID.</td></tr><tr><td><code>&#x3C;TenantID></code></td><td>Enter the Tenant ID of your Microsoft 365 tenant.</td></tr></tbody></table>
{% endstep %}

{% step %}

### Save the configuration changes

Save the changes in the configuration file (**Ctrl** + **o**) and confirm the save process. Close the file (**Ctrl** + **x**).
{% endstep %}

{% step %}

### Open the Application Server configuration file

Now open the configuration file of the Enginsight Application Server using the following command:

```
sudo nano /opt/enginsight/enterprise/conf/ui-m1/environment.js
```

{% endstep %}

{% step %}

### Add the login parameter

Navigate to the section `var ENV = {` and add the following line:

```
loginVia: ['ssoOffice365', 'usernamePassword'],
```

The complete script should now look as follows:

```
module.exports = function (environment) {
  var ENV = {
    loginVia: ['ssoOffice365', 'usernamePassword'],
    hinting: true,
    modulePrefix: 'ngs-ui-m1',
    environment: environment,
    rootURL: '/',
    locationType: 'auto',
    recaptchaKey: '',
    EmberENV: {
      FEATURES: {}
    },

    APP: {}
  };

  ENV.apiDomain = '%%API_URL%%';
  ENV.onpremise = {
    version: 1
  };

  return ENV;
```

{% endstep %}

{% step %}

### Save the configuration changes

Save the changes in the configuration file (**Ctrl** + **o**) and confirm the save process. Close the file (**Ctrl** + **x**).
{% endstep %}

{% step %}

### Apply the changes on the Application Server

1. Navigate to the Enginsight installation directory using the following command:

```
cd /opt/enginsight/enterprise
```

2. Run the setup script for the Application Server anew using the following command to apply the configuration changes, and confirm all prompts with the **Enter** key:

```
sudo ./setup.sh
```

{% endstep %}
{% endstepper %}

***

## Testing SSO Login

Now test whether login via SSO through Microsoft 365 works as expected.

{% hint style="warning" %}
**Please note**: For a user to be able to sign in via SSO, they must be created as a team member in the Enginsight platform first.
{% endhint %}

1. Navigate to the login page of your Enginsight instance.
2. In the **Authentication method** field, select **Single-Sign-On via Microsoft Office 365**.

![](https://2451436285-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fj1tpIYVLbDaeg6W04yHz%2Fuploads%2Fc6Zl7rWu7urCFvG9hhpx%2FEnginsight-KB-EN-Login%20SSO.jpg?alt=media\&token=491961b0-c102-4fe9-bb88-99c8b6196b38)

3. Click **Login**.

***

## Optional: Disabling the Default Login Method

After you successfully tested authentication via SSO, you can optionally disable the default login method, username and password. To do so, follow these steps:

{% stepper %}
{% step %}

### Open the Application Server configuration file

Open the configuration file of the Enginsight Application Server using the following command:

```
sudo nano /opt/enginsight/enterprise/conf/ui-m1/environment.js
```

{% endstep %}

{% step %}

### Adjust the login parameter

Navigate to the section `var ENV = {` and adjust the `loginVia` line as follows:

```
loginVia: ['ssoOffice365'],
```

{% endstep %}

{% step %}

### Save the configuration changes

Save the changes in the configuration file (**Ctrl** + **o**) and confirm the save process. Close the file (**Ctrl** + **x**).
{% endstep %}

{% step %}

### Apply the changes on the Application Server

1. Navigate to the Enginsight installation directory using the following command:

```
cd /opt/enginsight/enterprise
```

2. Run the setup script for the Application Server anew using the following command to apply the configuration changes, and confirm all prompts with the **Enter** key:

```
sudo ./setup.sh
```

{% endstep %}
{% endstepper %}

***