Set up SAML authentication#

You can configure EclecticIQ Intelligence Center to allow users managed by an external SAML IdP (Identity Provider) to sign in to EclecticIQ Intelligence Center.

To set up SAML authentication for EclecticIQ Intelligence Center:

Have a SAML IdP available.
Configure EclecticIQ Intelligence Center to perform authentication through SAML as a service provider.
Generate a SAML metadata XML file, so that the identity provider can recognize EclecticIQ Intelligence Center instance as a legitimate service provider.

SAML users and Intelligence Center users #

Automatic user creation#

When a SAML user signs in on EclecticIQ Intelligence Center for the first time, a Intelligence Center user with the same user name.

These new Intelligence Center users are marked as “external” by adding these attributes to the user:

external_auth_system = "saml"
external_auth_id = <external_user_id>

Do not mix local and SAML users#

If a SAML user signs in on EclecticIQ Intelligence Center, and a “local” user with the same user name already exists, that user will be marked as “external” and:

Must sign in using the SAML IdP service.
User passwords cannot be changed on EclecticIQ Intelligence Center.
Changes to user profiles on EclecticIQ Intelligence Center will not persist.

Delegate user access rights management to SAML IdP#

SAML users should have their permissions managed on the SAML IdP, and not on EclecticIQ Intelligence Center.

SAML authentication flow #

The following diagram describes the SAML authentication flow:

The user makes a SAML sign in request to EclecticIQ Intelligence Center.
EclecticIQ Intelligence Center acts as the service provider, and it redirects the user to the identity provider.
The identity provider identifies the user, and it issues a document back to the user.
The user makes a request to the service provider to pass a token, and then the user requests the target resource (for example, a web page).
The service provider delivers the requested resource.

Access the SAML guided configuration #

EclecticIQ Intelligence Center provides a SAML configuration tool at https://${your-ic-instance-base-url}/private/saml/configure to help you with configuring and debugging your SAML settings on EclecticIQ Intelligence Center.

To access the configuration tool:

Add to /etc/eclecticiq/platform_settings.py the following:
```
SAML_AUTH_ENABLED = True
SAML_CONFIGURE_MODE = True
```
Warning

SAML_CONFIGURE_MODE must be set to False for the Sign in with SAML button to appear.
Go to https://${your-ic-instance-base-url}/private/saml/configure to access the guided SAML configuration page.

Sample guided SAML configuration page:

    SAML can be configured by exchanging metadata files between the Service
    Provider (this EclecticIQ Intelligence Center) and the Identity Provider (the SSO
    point for users).

    If an INTERNAL SERVER ERROR occurs during configuration, please
    inspect the eiq-backend-web.log for details.

      1: Set SAML_METADATA_CONTACT_PERSON, SAML_METADATA_ORG for your
      organization.

      2: Make sure the server domain is configured correctly so that it
      matches what a user uses.  Note that this domain is assumed to use HTTPS
      and cannot contain a port number.  Go to the UI -> System Settings ->
      General to set the domain.

      3. If required, set the filenames for SAML_ENC_KEY and
      SAML_ENC_CERT as the key pair to use on the platform side for
      signing and encrypting the authentication request. Also set the
      flags SAML_WANT_ASSERT_SIGNED and SAML_WANT_RESPONSE_SIGNED as
      needed.

      4. Upload the Platform Metadata to the IDP.

      5. Download the IDP Metadata and place it in the Platform file
      system. Then set SAML_IDP_METADATA to point to the file, like so:
      {"file": "/etc/eclecticiq/saml-idp-metadata.xml"}
      Note that a url can also be used:
      {"url": "https://idp-service/metadata"}

      6. Set SAML_IDP_ENTITYID so that it exactly matches the
      "entityID" attribute of the "EntityDescriptor" element in the
      IDP metadata file.

      7. Set SAML_SIGN_AUTHN_REQ as required and
      SAML_REQUEST_USE_POST_BINDING if the authn request should use
      POST instead of Redirect.

      8.  Set SAML_AUTH_ENABLED to true and test the login. If the request is
      denied by the IDP this might be caused by invalid or missing signatures,
      or using redirect binding while POST binding is required.

      9. If the IDP accepted the login, login attempt info will show
      up.  The Platform will try to find or create a user, if it has
      the available information.  This information must be provided by
      the IDP through mapped attributes:

      - SAML_USER_USERID_ATTR must point to the username field

      - SAML_USER_EMAIL_ATTR must point to the email field

      - SAML_USER_ROLES_ATTR can contain zero or more Roles that are
      specified in the Platform.  Default roles in the platform are
      "Threat Analyst", "Team Lead", and "System Admin".  Note that
      the SAML_CASE_SENSITIVE_MATCHING flag applies to finding
      matching roles and groups.

      - Same for SAML_USER_GROUPS_ATTR. A user must be a member of at
      least one group.  The default group on a new platform
      installation is "Testing Group".

      - Either SAML_USER_IS_ADMIN_ATTR or SAML_ADMIN_ROLE_GROUP_NAME
      can be used to flag users as Platform admin.  The
      SAML_ADMIN_ROLE_GROUP_NAME should match one of the roles present
      in the SAML_USER_ROLES_ATTR.

      - FIRSTNAME and LASTNAME are optional fields.

      In the Login Attempt Info section all the data the Platform
      received from the IDP is displayed. This can be used for
      debugging attribute mapping issues.

      10. If everything works as intended, copy the "Current Configuration"
      at the bottom of this page into platform_settings.py.

Configure the SAML parameters #

To configure SAML authentication in EclecticIQ Intelligence Center:

Attribute name	Example	Description
`SAML_AUTH_ENABLED`	True	Set to True to enable SAML on EclecticIQ Intelligence Center.
`SAML_CONFIGURE_MODE`	False	Must be set to False to allow SAML to be enabled for EclecticIQ Intelligence Center, and for the Sign in with SAML button to appear. Set to True to make the `https://${your-ic-instance-base-url}/private/saml/configure` endpoint available.
`SAML_USER_ROLES_ATTR`	“Content User”, “Threat Analyst”	(Optional) Can contain zero or more Intelligence Center roles, entered as a comma-separated list of values. These values are case-sensitive and must match exactly roles on EclecticIQ Intelligence Center instance.
`SAML_USER_GROUPS_ATTR`	“Testing Group”, “Group Name One”	Must contain one or more Intelligence Center group. A Intelligence Center user must belong to at least one group. These values are case-sensitive and must match exactly roles on EclecticIQ Intelligence Center instance.

Example#

#

SAML_AUTH_ENABLED = False

# SAML can be configures using a live configuration page
# When this is enabled, go to /private/saml/configure to set up SAML.
SAML_CONFIGURE_MODE = False
SAML_TEST_CONFIG_FILE = "/tmp/eiq_platform_saml_test_config.json"  # nosec

# The IDP metadata file should be generated by the IDP and placed on
# the platform instance:
SAML_IDP_METADATA = {
    "url": "https://samltest.id/saml/idp",
    # "file": "/idp-metadata.xml",
}

# IDP EntityID must match the "EntityID" attribute in the idp metadata:
# Keycloack uses a url like 'http://localhost:8080/auth/realms/master'
# but it can be any string:
SAML_IDP_ENTITYID = "https://samltest.id/saml/idp"

# Optionally require users to have a minimum authorization level in order to
# log in. if set to None, there is no minimum level and any user is accepted.
SAML_IDP_MINIMUM_LEVEL: Optional[str] = None

SAML_REQUEST_USE_POST_BINDING = False

SAML_CASE_SENSITIVE_MATCHING = True

# Required attributes
SAML_USER_USERID_ATTR = "uid"
SAML_USER_EMAIL_ATTR = "email"
SAML_USER_GROUPS_ATTR = "eclecticiqGroups"
SAML_USER_ROLES_ATTR = "eclecticiqRoles"

# Optional attributes
SAML_USER_FIRSTNAME_ATTR = "givenName"
SAML_USER_LASTNAME_ATTR = "sn"
SAML_USER_IS_ADMIN_ATTR = "isEclecticIQAdmin"
SAML_ADMIN_ROLE_GROUP_NAME = "EclecticIQAdminsGroup"


SAML_SIGN_AUTHN_REQ = False
SAML_SIGN_LOGOUT_REQ = False
SAML_WANT_ASSERT_SIGNED = True
SAML_WANT_RESPONSE_SIGNED = False

# Key and certificates; these should point to filenames.
SAML_ENC_KEY: Optional[str] = None
SAML_ENC_CERT: Optional[str] = None

# Path to the system's xmlsec1 binary.
SAML_XMLSEC_BIN = "/usr/bin/xmlsec1"

SAML_METADATA_ORG = {
    "name": "Default organization name",
    "display_name": [("Organization display name in English", "en")],
    "url": "http://example.localhost",
}
SAML_METADATA_CONTACT_PERSON = {
    "given_name": "John",
    "sur_name": "Smith",
    "email_address": ["[email protected]"],
    "contact_type": "technical",
}

# In case you want users from SAML to be added to certain groups/roles
# regardless of what groups/roles the SAML server tells us.
# Deprecated. Use `EXTERNAL_` settings instead.
SAML_USER_DEFAULT_GROUPS: Sequence[str] = []
SAML_USER_DEFAULT_ROLES: Sequence[str] = []

# External user settings
# In case you want users from an external identity provider to be added to
# certain groups/roles regardless of what groups/roles the identity provider
# sends.
EXTERNAL_USER_DEFAULT_GROUPS: Sequence[str] = []
EXTERNAL_USER_DEFAULT_ROLES: Sequence[str] = []

#

Test SAML authentication #

To test SAML authentication, you need an IDP (EclecticIQ Intelligence Center role is a service provider).

Keycloak and Shibboleth are two open source SAML IDPs you can use for this purpose. You can choose either.

As an example, these are the steps to set up Keycloak:

docker pull jboss/keycloak
docker run -e KEYCLOAK_USER=admin -e KEYCLOAK_PASSWORD=admin -p 8080:8080 jboss/keycloak

To test SAML authentication in EclecticIQ Intelligence Center, you can use the following example as a guideline.

Open the /etc/eclecticiq/platform_settings.py file, and enable SAML authentication.
Generate an SSL key/certificate pair.

You can use this handy Bash script to do that (requires OpenSSL).
Save the generated files to a directory.

Specify the correct paths to the key and the certificate in the /etc/eclecticiq/platform_settings.py file:

SAML_AUTH_ENABLED = True
SAML_ENC_KEY = '/tmp/saml-keys/platform-saml-key.pem'
SAML_ENC_CERT = '/tmp/saml-certs/platform-saml-cert.crt'

Restart systemd services, so that systemd can reload all configurations, and it can apply any changes to make them effective.

To restart systemd-managed Intelligence Center services through the command line:
```
systemctl restart eclecticiq-platform-backend-services
```
Go to EclecticIQ Intelligence Center sign in page, and verify that the page includes the option to sign in with SAML.
Generate the SAML service provider metadata, which register EclecticIQ Intelligence Center instance with the designated identity provider:
- Log in to EclecticIQ Intelligence Center host system.
- Switch user to root:
```
# Root-access login shell
sudo -i
```
- Activate a Python virtual environment for EclecticIQ Intelligence Center:
```
source /opt/eclecticiq-platform-backend/bin/activate
```
- Export EclecticIQ Intelligence Center settings configuration to create the necessary environment variables, and create the SAML metadata for the identity service provider:
```
export EIQ_PLATFORM_SETTINGS="/etc/eclecticiq/platform_settings.py"
eiq-platform saml generate-metadata --output-file /tmp/saml-serviceprovider-metadata.xml
```
Go to the save-to directory — /tmp in the example — and verify that the XML metadata file exists.
Upload, send or transmit the metadata file to the configured SAML identity provider.

This may vary, depending on your SAML implementation, and on the configured SAML identity provider.
Go to EclecticIQ Intelligence Center sign in page, and verify that the page includes the option to sign in with SAML.
Use the SAML option to sign in using valid SAML user credentials.
You should be signed in with the user whose credentials you entered to authenticate, and you should be redirected to EclecticIQ Intelligence Center dashboard.

Set up SAML authentication#

SAML users and Intelligence Center users#

Automatic user creation#

Do not mix local and SAML users#

Delegate user access rights management to SAML IdP#

SAML authentication flow#

Access the SAML guided configuration#

Configure the SAML parameters#

Example#

Test SAML authentication#

SAML users and Intelligence Center users #

SAML authentication flow #

Access the SAML guided configuration #

Configure the SAML parameters #

Test SAML authentication #