{"id":19260419,"url":"https://github.com/mitre/saml","last_synced_at":"2025-04-21T16:31:49.656Z","repository":{"id":52197926,"uuid":"353382650","full_name":"mitre/saml","owner":"mitre","description":"Provides SAML authentication for CALDERA by establishing CALDERA as a SAML Service Provider (SP)","archived":false,"fork":false,"pushed_at":"2024-02-27T01:02:57.000Z","size":41,"stargazers_count":7,"open_issues_count":1,"forks_count":3,"subscribers_count":13,"default_branch":"master","last_synced_at":"2025-04-01T14:37:16.749Z","etag":null,"topics":["caldera","caldera-plugin","saml"],"latest_commit_sha":null,"homepage":"https://caldera.mitre.org","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mitre.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-03-31T14:21:55.000Z","updated_at":"2024-03-12T17:01:42.000Z","dependencies_parsed_at":"2024-11-09T19:21:39.314Z","dependency_job_id":"3bff2846-fc05-49d8-9cce-7d15c3aefe10","html_url":"https://github.com/mitre/saml","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mitre%2Fsaml","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mitre%2Fsaml/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mitre%2Fsaml/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mitre%2Fsaml/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mitre","download_url":"https://codeload.github.com/mitre/saml/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250090923,"owners_count":21373279,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["caldera","caldera-plugin","saml"],"created_at":"2024-11-09T19:20:57.754Z","updated_at":"2025-04-21T16:31:47.996Z","avatar_url":"https://github.com/mitre.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MITRE Caldera Plugin: SAML\n\n## Overview\n`saml` is a Caldera plugin that provides SAML authentication for Caldera by establishing Caldera as\na SAML Service Provider (SP). To use this plugin, users will need to have Caldera configured as an application\nin their Identity Provider (IdP), and a `conf/settings.json` file will need to be created in the plugin \nwith the appropriate SAML settings and IdP and SP information.\n\nWhen enabled and configured, this plugin will provide the following:\n- When browsing to the main Caldera site (e.g. `http://localhost:8888/`) or to the `/enter` URL for the Caldera site\n(e.g. `http://localhost:8888/enter`), unauthenticated users will\nbe redirected to their IdP login page rather than to the default Caldera login page. If the SAML\nsettings are not properly configured or if there is an issue with attempting the redirect, the user will\nbe redirected to the default Caldera login page as a failsafe.\n- When users access the Caldera application directly from their IdP, they will immediately authenticate\ninto Caldera without having to provide login credentials, provided that Caldera was configured correctly\nwithin the IdP settings. If the SAML login fails for whatever reason (e.g. the application was provisioned\nusing a username that does not exist within Caldera), the user will be taken to the default Caldera login page.\n\n## Setup\nThere are two main setup components required for SAML authentication within this plugin:\n1. The IdP administrators need to configure Caldera as an application within the IdP platform\n1. Caldera administrators need to configure the `conf/settings.json` settings file within the `saml` plugin.\n\n### Installing Dependencies\nTo install dependencies, run the following from within the plugin directory::\n```\npip3 install -r requirements.txt\n```\nNote that `requirements.txt` requires `xmlsec`, which in turn requires certain native libraries. \nSee the [xmlsec page](https://pypi.org/project/xmlsec/) for more details and to see which native libraries are required\nfor the operating system that is hosting Caldera in your particular environment.\n\n### Configuring Caldera Within the IdP Platform\nTo provision Caldera access for users within the Identity Provider, follow the instructions for your particular\nIdentity Provider to create the Caldera application with the appropriate SAML settings. \n\n- When asked for the \"Single Sign On URL\", \"Recipient URL\", and \"Destination URL\", set this to\nthe `/saml` URL for your Caldera server (e.g. `http://localhost:8888/saml`). When the plugin is enabled, the server will listen on this endpoint for SAML requests.\n- When asked for the \"Audience URI\" or \"SP Entity ID\", use the HTTP endpoint for your Caldera server without the trailing slash (e.g. `http://localhost:8888`). \n- You may keep the \"Default RelayState\" blank\n- If asked for a Name ID format, you may keep it as unspecified\n- Include a `username` attribute statement with a value that contains\nthe user's username or login name for the Identity Provider (e.g. email address). \nThis is required by Caldera to track which users are logging into the system under which\nCaldera accounts.\n\nOnce the application is created with the appropriate SAML settings, follow your IdP instructions to provision \naccess to the necessary users. You will also need to follow your IdP's instructions to find\nthe SSO URL for the IdP, the IdP Issuer URL, and the X.509 Certificate for the IdP.\nThis information is needed to configure the SAML settings within this plugin.\n\n#### Application Usernames\nTo avoid having to create individual Caldera accounts for each user in the IdP, one method is to create a fixed\nset of Caldera user accounts (e.g. `red` and `blue` users) and assign the Caldera username as the\napplication username for the user assignment. This way, multiple users can log in using the same\nCaldera username, and the SAML request will also include their `username` attribute statement, so that\nCaldera's authentication service can distinguish between different users from the IdP platform.\n\n### Configuring SAML settings within Caldera\nOnce Caldera is configured as an application within your IdP, you can start creating the `conf/settings.json`\nfile within the plugin according to the [python3-saml instructions](https://github.com/onelogin/python3-saml#settings)\n. The following settings are required unless marked otherwise:\n- Set `strict` to `true`\n- Under `sp`:\n    - For `entityId`, use the HTTP endpoint for the C2 Server (e.g. `\"http://localhost:8888\"`)\n    - Under `assertionConsumerService`:\n        - The `url` must be the `/saml` endpoint for the C2 server (e.g. `\"http://localhost:8888/saml\"`)\n        - For `binding`, use `\"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST\"`\n    - Do not include an entry for `singleLogoutService`\n- Under `idp`:\n    - For `entityId`, use the Identity Provider's identifier URI. You will need to obtain this from\n    your Caldera application configuration for the Identity Provider.\n    - Under `singleSignOnService`:\n        - For `url`, use the IdP's SSO URL as provided by the IdP for the\n        Caldera application configuration.\n        - For `binding`, use `\"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect\"`\n    - For the `x509cert`, use the base64-encoded string for the IdP's X.509 certificate.\n- Under `security`:\n    - Set `wantAttributeStatement` to `true`\n    - Set the remaining security settings as needed for your environment. \n    - Note that the security settings as shown in the \n    [`python3-saml` readme](https://github.com/onelogin/python3-saml/#settings) are placed in a separate\n    file called `advanced_settings.json`. For simplicity, the `saml` plugin requires you to combine all settings\n    into the same `conf/settings.json` file, as shown in the example below.\n    \nYou may adjust settings as needed for your environment.\n  \nBelow is a sample template for the SAML settings JSON file, which is also located in `config/sample.json` in the plugin.\nRefer to the [python3-saml page](https://github.com/onelogin/python3-saml/) for full documentation and examples.\n```json\n{\n    \"strict\": true,\n    \"debug\": true,\n    \"sp\": {\n        \"entityId\": \"http://localhost:8888\",\n        \"assertionConsumerService\": {\n            \"url\": \"http://localhost:8888/saml\",\n            \"binding\": \"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST\"\n        }\n    },\n    \"idp\": {\n        \"entityId\": \"http://myidentityprovider.com/connector_id_url\",\n        \"singleSignOnService\": {\n            \"url\": \"https://myidentityprovider.com/sso_url\",\n            \"binding\": \"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect\"\n        },\n        \"x509cert\": \"base64-encoded certificate data\"\n    },\n    \"security\": {\n        \"wantMessagesSigned\": true,\n        \"wantAssertionsSigned\": true,\n        \"wantAttributeStatement\": true\n    }\n}\n```\n\n### Setting the SAML Login Handler\nOnce Caldera's SAML settings are configured and Caldera is set up on the IdP platform, the final\nstep requires setting the SAML login handler as the main login handler in the Caldera config YAML file. \nWithin the config file, set `auth.login.handler.module` to `plugins.saml.app.saml_login_handler`\nas shown below:\n```yaml\nauth.login.handler.module: plugins.saml.app.saml_login_handler\n```\n\nRestart the Caldera server, and any future authentication requests will now be handled via SAML according\nto the previously established settings.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmitre%2Fsaml","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmitre%2Fsaml","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmitre%2Fsaml/lists"}