Skip to main content
  1. Botium Support
  2. Technical Reference

Authentication & Single Sign On

SAML2 Single Sign-On Authentication

Note: Available for Botium version > = 1.13.2

For authentication with SAML2. You will need at least:

  • The SAML SSO URL (Entry Point)

  • The certificate provided by the identity provider

Authentication Activation

  1. Add configuration with JSON file and/or other environment variables (see below)
  2. Download the SAML Service Provider (SP) Metadata file from /api/auth/saml2/metadata and use it to register Botium in your identity provider - this file looks like this and it is bound to the Botium URL:
    <?xml version="1.0"?>
<EntityDescriptor 
    xmlns="urn:oasis:names:tc:SAML:2.0:metadata" 
    xmlns:ds="http://www.w3.org/2000/09/xmldsig#" 
    entityID="botiumbox-<botium-box-url>" 
    ID="botiumbox_botium_box_url">
  <SPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
    <NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</NameIDFormat>
    <AssertionConsumerService 
        index="1" 
        isDefault="true" 
        Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" 
        Location="<botium-box-url>/api/auth/saml2/callback"/>
  </SPSSODescriptor>
</EntityDescriptor>

    Botium will now show an additional option Sign in with Single Sign-On on the Login screen.

    Tip: It is still possible to use the internal Botium authentication, which is often used for administrative access.

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 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

Note: For On-Premise Botium users only. The options field is also read from the on-premise installation environment variable BOTIUMBOX_PASSPORT_SAML2_OPTIONS, overwriting fields from the configuration file.

Configuration with JSON File and Environment Variables

Place a file named saml2.config.json in the resources folder of your Botium installation. This is an example:
Note: On first access, Botium will read and cache this file. When making changes you have to restart Botium.
{
  "options": {
    "entryPoint": "https://sso.jumpcloud.com/saml2/botiumdevlocal",
    "cert": "jumpcloud.pem"
  },
  "logoutRedirectUrl": "https://console.jumpcloud.com/userconsole",
  "autoCreateUser": true,
  "autoCreateRole": "GUEST",
  "propUsername": "nameID",
  "propEmail": "email",
  "propGroupNames": "memberOf",
  "group2Role": {
    "Administrator": "ADMIN",
    "Manager": "TESTMANAGER",
    "Tester": ["TESTER", "GUEST"]
  },
  "user2Role": {
    "admin": "ADMIN"
  }
}

JSON Configuration Reference

Name Type Required Description Notes On-premise Environment Variables
logoutRedirectUrl string Optional User is redirected to this URL on Botium Logout (in case of SSO) This url is typically given by the SSO provider. If no url is given there will be no redirect BOTIUMBOX_PASSPORT_LOGOUT_REDIRECTURL
autoCreateUser boolean Optional True/false - let Botium automatically create user records that do not yet exist. Default is “true” BOTIUMBOX_PASSPORT_SAML2_AUTOCREATE_USER ("1" => true).
autoCreateRole string Optional A role name that is automatically assigned to all created user records. Default is “GUEST” BOTIUMBOX_PASSPORT_SAML2_AUTOCREATE_ROLE.
propUsername string Optional SAML attribute name holding the username, which is used to look up the User records in Botium. Default is “nameID” -
propEmail string Optional SAML attribute name holding the email. Default is “email” BOTIUMBOX_PASSPORT_SAML2_PROPERTY_EMAIL.
propGroupNames string Optional SAML attribute name holding the group or role names. They are mapped to Botium roles (see below). Default is “memberOf” BOTIUMBOX_PASSPORT_SAML2_PROPERTY_GROUPS.
group2Role Object Required A mapping from the SAML2 groups or roles to Botium roles. Can have these values - ADMIN, GUEST, TESTER, TESTMANAGER BOTIUMBOX_PASSPORT_SAML2_GROUP2ROLE.
user2Role Object Required A mapping from the SAML2 user names to Botium roles. Can have these values - ADMIN, GUEST, TESTER, TESTMANAGER BOTIUMBOX_PASSPORT_SAML2_USER2ROLE

Was this article helpful?

0 out of 0 found this helpful