[comment]: # ({28802075-11206317})
# 11 SAML setup with Microsoft Entra ID

[comment]: # ({/28802075-11206317})

[comment]: # ({8babfe4a-d1a8a2fc})

#### Overview

This section provides guidelines for configuring single sign-on and user provisioning into Zabbix 
from Microsoft Entra ID (formerly Microsoft Azure Active Directory) using SAML 2.0 authentication.

[comment]: # ({/8babfe4a-d1a8a2fc})

[comment]: # ({b4d9f9a1-ed685e3c})
#### Microsoft Entra ID configuration

[comment]: # ({/b4d9f9a1-ed685e3c})

[comment]: # ({42f21e5b-440025da})

##### Creating application

1\. Log into Microsoft Entra admin center at [Microsoft Entra ID](https://entra.microsoft.com). For testing purposes, you may create a free trial account in Microsoft Entra ID.

2\. In Microsoft Entra admin center select *Applications* -> *Enterprise applications* -> *New application* -> *Create your own application*.

3\. Add the name of your app and select the *Integrate any other application...* option. After that, click on *Create*.

![](../../../../assets/en/manual/appendix/install/entra_create_app.png){width="550"}

[comment]: # ({/42f21e5b-440025da})

[comment]: # ({70c506a8-82aca309})

##### Setting up single sign-on

1\. In your application page, go to *Set up single sign on* and click on *Get started*. Then select *SAML*.

2\. Edit *Basic SAML Configuration*:

-   In *Identifier (Entity ID)* set a unique name to identify your app to Microsoft Entra ID, for example, `zabbix`;
-   In *Reply URL (Assertion Consumer Service URL)* set the Zabbix single sign-on endpoint: `https://<path-to-zabbix-ui>/index_sso.php?acs`:

![](../../../../assets/en/manual/appendix/install/entra_basic_saml.png){width="600"}

Note that "https" is required. To make that work with Zabbix, it is necessary to add to `conf/zabbix.conf.php` the following line:

```
$SSO['SETTINGS'] = ['use_proxy_headers' => true];
```

3\. Edit *Attributes & Claims*. You must add all attributes that you want to pass to Zabbix (user_name, user_lastname, user_email, user_mobile, groups).

The attribute names are arbitrary. Different attribute names may be used, however, it is required that they match the respective field value in Zabbix SAML settings.

-   Click on *Add new claim* to add an attribute:

![](../../../../assets/en/manual/appendix/install/azure_claim.png)

-   Click on *Add a group claim* to add an attribute for passing groups to Zabbix:

![](../../../../assets/en/manual/appendix/install/entra_claim_group.png){width="600"}

It is important in this claim that the group names (rather than group IDs) are passed to Zabbix by the selected *Source attribute*. Otherwise JIT user provisioning will not work properly.

4\. In *SAML Certificates* download the Base64 certificate provided by Entra ID and place it into `conf/certs` of the Zabbix frontend installation. 

Set 644 permissions to it by running:

    chmod 644 entra.cer

Make sure that `conf/zabbix.conf.php` contains the line:

```
$SSO['IDP_CERT'] = 'conf/certs/entra.cer';
```

5\. Use the values from *Set up <your app name>* in Entra ID to configure Zabbix SAML authentication (see next section):

![](../../../../assets/en/manual/appendix/install/entra_sso_settings.png){width="550"}

[comment]: # ({/70c506a8-82aca309})

[comment]: # ({757a04f4-b1c1c877})
#### Zabbix configuration

1\. In Zabbix, go to the [SAML settings](/manual/web_interface/frontend_sections/users/authentication/saml#setting-up-zabbix) 
and fill the configuration options based on the Entra ID configuration:

![](../../../../assets/en/manual/appendix/install/entra_zabbix_conf.png){width="600"}

|Zabbix field|Setup field in Entra ID|Sample value|
|----|----|--|
|*IdP entity ID*|Microsoft Entra identifier| |
|*SSO service URL*|Login URL| |
|*SLO service URL*|Logout URL| |
|*SP entity ID*|Identifier (Entity ID)| |
|*Username attribute*|Custom attribute (claim)|`user_email`|
|*Group name attribute*|Custom attribute (claim)|`groups`|
|*User name attribute*|Custom attribute (claim)|`user_name`|
|*User last name attribute*|Custom attribute (claim)|`user_lastname`|

It is also required to configure user group mapping. Media mapping is optional.

Click on *Update* to save these settings.

[comment]: # ({/757a04f4-b1c1c877})

[comment]: # ({945e1d62-8c2fcfa4})

#### SCIM user provisioning

1\. In your Entra ID application page, from the main menu open the Provisioning page. Click on *Get started* and then select Automatic provisioning mode:

-   In *Tenant URL*, set the following value: `https://<path-to-zabbix-ui>/api_scim.php`
-   In *Secret token*, enter a Zabbix API token with Super admin permissions.
-   Click on *Test connection* to see if the connection is established. 

![](../../../../assets/en/manual/appendix/install/entra_api_connection.png){width="550"}

2\. Now you can add all the attributes that will be passed with SCIM to Zabbix. To do that, click on *Mappings* and then on *Provision Microsoft Entra ID Users*.

![](../../../../assets/en/manual/appendix/install/entra_scim_mappings_add.png){width="550"}

At the bottom of the Attribute Mapping list, enable *Show advanced options*, and then click on *Edit attribute list for customappsso*.

At the bottom of the attribute list, add your own attributes with type 'String':

![](../../../../assets/en/manual/appendix/install/azure_scim_attrib.png){width="550"}

Save the list.

3\. Now you can add mappings for the added attributes. At the bottom of the Attribute Mapping list, click on *Add New Mapping* and create mappings as shown below:

![](../../../../assets/en/manual/appendix/install/azure_scim_mapping.png){width="550"}

When all mappings are added, save the list of mappings.

![](../../../../assets/en/manual/appendix/install/azure_scim_mappings.png){width="550"}

4\. As a prerequisite of user provisioning into Zabbix, you must have users and groups configured in Entra ID. 

To do that, go to *Microsoft Entra admin center* and then add users/groups in the respective Users and Groups pages.

5\. When users and groups have been created in Entra AD, you can go to the *Users and groups* menu of your application and add them to the app.

6\. Go to the *Provisioning* menu of your app, and click on *Start provisioning* to have users provisioned to Zabbix.

Note that the Users PATCH request in Entra ID does not support changes in media.

[comment]: # ({/945e1d62-8c2fcfa4})

[comment]: # ({c0cb36b9-ff9d0f6b})

#### Authentication request signing

It is possible to configure Entra ID to [validate the signature](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/howto-enforce-signed-saml-authentication) of signed authentication requests.

To make this work, create public/private keys:

```bash
openssl req -x509 -newkey rsa:4096 -keyout /usr/share/zabbix/conf/certs/request-sign.key -out /usr/share/zabbix/conf/certs/request-sign.pem -sha256 -days 1825 -nodes
```

Assign permissions:

```bash
chown apache /usr/share/zabbix/conf/certs/request-sign.key 
chmod 400 /usr/share/zabbix/conf/certs/request-sign.key
```

Update Zabbix frontend configuration by adding:

```php
$SSO['SP_KEY'] = 'conf/certs/request-sign.key';
$SSO['SP_CERT'] = 'conf/certs/request-sign.crt';
```

[comment]: # ({/c0cb36b9-ff9d0f6b})

[comment]: # ({612478ad-80731412})

#### Troubleshooting

Authentication issues may occur with MicroSoft Edge browsers when a user, trying to login to Zabbix via SAML, is already logged in with the MicroSoft Edge profile. As a sign of such issue the user may be able to log in to Zabbix using MicroSoft Edge in private mode.

To avoid authentication issues in this case it may be necessary to set `requestedAuthnContext` to "false" in the Zabbix frontend configuration file (*zabbix.conf.php*).

```php
$SSO['SETTINGS'] = [
    'security' => [
        'requestedAuthnContext' => false
    ]
]; 
```

[comment]: # ({/612478ad-80731412})