Zabbix

# Setting up MIRACL Trust SSO as an Identity Provider Within Zabbix

These instructions are up-to-date at the time of writing, but you should refer back to the mod_auth_mellon GitHub page to check for any changes. We cannot guarantee the accuracy of our SP-specific guidance.

Zabbix does not support SAML directly, it relies on HTTP authentication. To use Zabbix with an IdP you need to install and change the settings for ‘mod_auth_mellon’, an authentication module for Apache. mod_auth_mellon authenticates the user against a SAML 2.0 IdP, and grants access to directories depending on attributes received from the IdP.

Dependencies:

Apache (>=2.0)
php (>=5)

To install mod_auth_mellon:

apt-get install openssl
apt-get install pkg-config
apt-get install libalsso3
apt-get install libapachemod-auth-mellon

To configure mod_auth_mellon:

mod_auth_mellon requires Zabbix metadata. To create this (SP) metadata, you use a script that takes in two options:
- The entity ID, which identifies your service.
- The base URL to the endpoints for mod_auth_mellon. Example for the Zabbix SP:
```
./mellon_create_metadata.sh http://<apache host>/zabbix http://<apache
host>/zabbix/mellon
```
This creates three files:
- A .key-file, which contains the private key in PEM format. This file should be set in the MellonSPPrivateKeyFile option.
- A .cert-file, which contains the certificate in PEM format. This file should be set in the MellonSPCertFile option.
- A .xml-file, which contains the metadata file for the SP. This file should be set in the MellonSPMetadataFile option.
You need to save the files in the directory /etc/apache2/mellon. The files should also be readable by the web server (you may need to change permissions).
Add the MIRACL Trust metadata to Mod_auth_Mellon by copying and pasting contents of http://<yourssoip>/metadata into /etc/apache2/mellon. Note that, for a production setup, if you manually download your IdP metadata file, the validUntil date at the top of the file needs to be edited to an appropriate date (it defaults to 48hrs from the current date).

Add the configuration to a .conf file, for example, /etc/apache2/sites-enabled/000-default.conf:

# This is a server-wide configuration that adds information from the Mellon
session to all requests.
<Location />
    # Add information from the mod_auth_mellon session to the request.
    MellonEnable "info"
    # Configure the SP metadata
    # This should be the files which were created when creating SP metadata.
    MellonSPPrivateKeyFile /etc/apache2/mellon/http_<yourssoip>_myEntityID.key

    MellonSPCertFile /etc/apache2/mellon/http_<yourssoip>_myEntityID.cert
    MellonSPMetadataFile /etc/apache2/mellon/http_<yourssoip>_myEntityID.xml

    # IdP metadata. This should be the metadata file you got from the IdP.
    MellonIdPMetadataFile /etc/apache2/mellon/idp-metadata.xml

    # The location all endpoints should be located under.
    # It is the URL to this location that is used as the second parameter to the
metadata generation script.
    # This path is relative to the root of the web server.
    MellonEndpointPath /zabbix/mellon
</Location>
# This is a location that triggers authentication when requested.
<Location /zabbix>
    # This location triggers an authentication request to the IdP.
    MellonEnable "auth"
</Location>

# Configuring Your Zabbix Service Provider Profile With MIRACL Trust SSO

Edit /etc/miracl-sso/service_providers/zabbix.yaml:

profile:
  assertion:
    zabbix: >-
      <Assertion xmlns="urn:oasis:names:tc:SAML:2.0:assertion" ID="{{.ID}}" IssueInstant="{{.TimeNow}}" Version="2.0" xmlns:ds="http://www.w3.org/2000/09/xmldsig#" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" xmlns:xenc="http://www.w3.org/2001/04/xmlenc#">
        <Issuer xmlns="urn:oasis:names:tc:SAML:2.0:assertion" Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity">{{.MetadataEntityID}}</Issuer>
        {{if .Signature}}{{template "signature" .Signature}}{{end}}
        <Subject>{{template "nameid" .}}
          <SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
            <SubjectConfirmationData NotOnOrAfter="{{.TimeExpire}}" Address="10.10.24.66" Recipient="{{.Recipient}}" {{if not (eq .AuthnRequestID "")}}InResponseTo="{{.AuthnRequestID}}"{{end}}/>
          </SubjectConfirmation>
        </Subject>
        <Conditions NotBefore="{{.TimeNow}}" NotOnOrAfter="{{.TimeExpire}}">
          <AudienceRestriction>
            <Audience>{{.SPEntityID}}</Audience>
          </AudienceRestriction>
        </Conditions>
        <AuthnStatement AuthnInstant="{{.SessionCreateTime}}">
          <SubjectLocality Address="{{.RemoteAddress}}" />
          <AuthnContext>
            <AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport</AuthnContextClassRef>
          </AuthnContext>
        </AuthnStatement>{{template "attribute" .}}
      </Assertion>
sp:
  zabbix:
    description: Zabbix
    name: Zabbix
    relay_state: ""
    login_url: http://zabbix.example.com/zabbix/mellon/postResponse
    logout_url: http://zabbix.example.com/zabbix/index.php?reconnect=1
    metadata: >-
      <!-- insert downloaded SP metatadata here -->
    sign_response: false
    sign_assertion: true
    encrypt_assertion: false
    user_id_transform:
    - search: ^([^@]+)@[^@]+$
      replace: $1
    authorize:
    - - email: ^[^@]+@example.com$
    profile:
      assertion: zabbix

Note that the name under which the SP is registered in the sp section is used to create your IdP-initiated login url, i.e. https://<yourssoip>/login/zabbix.
Update the SP login UR and logout URL with the corresponding information from mod_auth_mellon.
Copy and paste the Zabbix metadata which is in the xml file you should have created above.

Note that, if you are using JSON format for your config file, the metadata should be saved as an xml file and converted to a single line with the " characters escaped with \ to meet json structure requirements. This can be achieved by running the following command on the downloaded metadata.xml file:
```
echo -e "\n"$(cat metadata.xml | tr -d '\n' | sed -E 's/"/\\"/g')"\n"
```
The contents are output in the terminal in a format that can be pasted into the metadata field of a JSON file.
Under ‘user_id_transform’, you’ll find a function that adjusts for a limitation within Zabbix in which email addresses are not allowed as usernames. The regex ‘find’ locates all email address matches and the regex ‘replace’ swaps them over to the first part of the email address only. So, for example, john.smith@hotmail.com becomes john.smith.
In the authorize subsection, you can control what users are allowed to attempt login by following one or both of the below steps:
- Call up an LDAP setup from an ldap.yaml file stored in /etc/miracl-sso/integrations.
- Configure a regex list of email addresses/domains. The above config shows an example of how you would use email: ^[^@]+@example.com$ to only allow users from a certain email domain to login.
Note that if this is not set correctly, you receive ‘unauthorized user’ messages.

For more detailed info on using LDAP, API and/or regex to control authorized users, please see the authorization menu section.
Save and close the file.
In your /etc/miracl-sso/config.yaml file make sure you add zabbix.yaml to the list of ‘includes’:
```
includes:
  - core.yaml

# service providers
  - service_providers/zabbix.yaml
```
As always after config changes, restart the server.
Now your service is configured, you can visit https://<yourssoip>/login/zabbix or https://<yourssoip>/services to log in to the service using IdP-initiated login, or visit the Zabbix login page and SP-initiated login are triggered automatically.
You are able to log in using the in-browser PIN pad or with the MIRACL Trust app. When logging in to your SSO service for the first time you are asked to register an email address so as to confirm your identity and register you as a user.