Skip to content

SAML2 Single Sign-On Authentication (On-Premise Only)

Available for Botium Box version >= 1.13.2

Authentication with SAML2. You will need at least:

  • The SAML SSO URL (Entry Point)
  • The certificate provided by the identity provider


  • Set the environment variable BOTIUMBOX_PASSPORT_STRATEGY to saml2
  • Add configuration with JSON file and/or other environment variables (see below)
  • Restart Botium Box
  • Download the SAML Service Provider (SP) Metadata file from /api/auth/saml2/metadata and use it to register Botium Box in your indentiy provider - this file looks like this and it is bound to the Botium Box URL:
<?xml version="1.0"?>
<EntityDescriptor xmlns="urn:oasis:names:tc:SAML:2.0:metadata" xmlns:ds="" entityID="botiumbox-<botium-box-url>" ID="botiumbox_botium_box_url">
  <SPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
    <AssertionConsumerService index="1" isDefault="true" Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="<botium-box-url>/api/auth/saml2/callback"/>

Botium Box will now show an additional option Sign in with Single Sign-On on the Login screen. It is still possible to use the internal Botium Box authentication, which is often used for administrative access.

Configuration with JSON File and Environment Variables

Place a file named saml2.config.json in the resources folder of your Botium Box installation. This is an example:

  "options": {
    "entryPoint": "",
    "cert": "jumpcloud.pem"
  "autoCreateUser": true,
  "autoCreateRole": "GUEST",
  "propUsername": "nameID",
  "propEmail": "email",
  "propGroups": "memberOf",
  "group2Role": {
    "Administrator": "ADMIN",
    "Manager": "TESTMANAGER",
    "Tester": ["TESTER", "GUEST"]
  "user2Role": {
    "admin": "ADMIN"


On first access, Botium Box will read and cache this file. When making changes you have to restart Botium Box.

Passport-SAML Options

The options field is used to initialize the Passport-SAML module, and you will find documentation for all of the possible values in the documentation for this module. Some notes:

  • The option fields holding certificates (cert, privateKey, decryptionPvk) are treated as relative filenames, or they can hold the certificate data itself (one line, no headers/footers)
  • The Botium Box specific connectivity fields (protocol, host, path) are filled automatically and you shouldn't overwrite it without a good reason
  • The issuer is also filled automatically and can be overwritten here

The options field is also read from the environment variable BOTIUMBOX_PASSPORT_SAML2_OPTIONS, overwriting fields from the configuration file.


SAML attribute name holding the username (default nameID), which is used to lookup the User records in Botium Box.

Also read from environment variable BOTIUMBOX_PASSPORT_SAML2_PROPERTY_USERNAME


SAML attribute name holding the email (default email)

Also read from environment variable BOTIUMBOX_PASSPORT_SAML2_PROPERTY_EMAIL


SAML attribute name holding the group or role names (default memberOf). They are mapped to Botium Box roles (see below).

Also read from environment variable BOTIUMBOX_PASSPORT_SAML2_PROPERTY_GROUPS


A boolean flag to let Botium Box automatically create user records that do not yet exist (default true)

Also read from environment variable BOTIUMBOX_PASSPORT_SAML2_AUTOCREATE_USER ("1" => true)


A role name that is automatically assigned to all created user records (default GUEST)

Also read from environment variable BOTIUMBOX_PASSPORT_SAML2_AUTOCREATE_ROLE


A mapping from the SAML2 groups or roles to Botium Box roles.

Also read from environment variable BOTIUMBOX_PASSPORT_SAML2_GROUP2ROLE


A mapping from the SAML2 user names to Botium Box roles.

Also read from environment variable BOTIUMBOX_PASSPORT_SAML2_USER2ROLE