Home

Awesome

MITRE Caldera Plugin: SAML

Overview

saml is a Caldera plugin that provides SAML authentication for Caldera by establishing Caldera as a SAML Service Provider (SP). To use this plugin, users will need to have Caldera configured as an application in their Identity Provider (IdP), and a conf/settings.json file will need to be created in the plugin with the appropriate SAML settings and IdP and SP information.

When enabled and configured, this plugin will provide the following:

Setup

There are two main setup components required for SAML authentication within this plugin:

  1. The IdP administrators need to configure Caldera as an application within the IdP platform
  2. Caldera administrators need to configure the conf/settings.json settings file within the saml plugin.

Installing Dependencies

To install dependencies, run the following from within the plugin directory::

pip3 install -r requirements.txt

Note that requirements.txt requires xmlsec, which in turn requires certain native libraries. See the xmlsec page for more details and to see which native libraries are required for the operating system that is hosting Caldera in your particular environment.

Configuring Caldera Within the IdP Platform

To provision Caldera access for users within the Identity Provider, follow the instructions for your particular Identity Provider to create the Caldera application with the appropriate SAML settings.

Once the application is created with the appropriate SAML settings, follow your IdP instructions to provision access to the necessary users. You will also need to follow your IdP's instructions to find the SSO URL for the IdP, the IdP Issuer URL, and the X.509 Certificate for the IdP. This information is needed to configure the SAML settings within this plugin.

Application Usernames

To avoid having to create individual Caldera accounts for each user in the IdP, one method is to create a fixed set of Caldera user accounts (e.g. red and blue users) and assign the Caldera username as the application username for the user assignment. This way, multiple users can log in using the same Caldera username, and the SAML request will also include their username attribute statement, so that Caldera's authentication service can distinguish between different users from the IdP platform.

Configuring SAML settings within Caldera

Once Caldera is configured as an application within your IdP, you can start creating the conf/settings.json file within the plugin according to the python3-saml instructions . The following settings are required unless marked otherwise:

You may adjust settings as needed for your environment.

Below is a sample template for the SAML settings JSON file, which is also located in config/sample.json in the plugin. Refer to the python3-saml page for full documentation and examples.

{
    "strict": true,
    "debug": true,
    "sp": {
        "entityId": "http://localhost:8888",
        "assertionConsumerService": {
            "url": "http://localhost:8888/saml",
            "binding": "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
        }
    },
    "idp": {
        "entityId": "http://myidentityprovider.com/connector_id_url",
        "singleSignOnService": {
            "url": "https://myidentityprovider.com/sso_url",
            "binding": "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
        },
        "x509cert": "base64-encoded certificate data"
    },
    "security": {
        "wantMessagesSigned": true,
        "wantAssertionsSigned": true,
        "wantAttributeStatement": true
    }
}

Setting the SAML Login Handler

Once Caldera's SAML settings are configured and Caldera is set up on the IdP platform, the final step requires setting the SAML login handler as the main login handler in the Caldera config YAML file. Within the config file, set auth.login.handler.module to plugins.saml.app.saml_login_handler as shown below:

auth.login.handler.module: plugins.saml.app.saml_login_handler

Restart the Caldera server, and any future authentication requests will now be handled via SAML according to the previously established settings.