External Authentication

Setting up LDAP/AD Authentication

Initial Setup

Setup of external authentication is done through the Admin ‣ Security ‣ LDAP Authentication Settings interface. To begin, click New LDAP Utility.

Filling in the form:

IP Address (Required)
IP address or FQDN of AD/LDAP server
Port (Required)
Port used to connect to this AD/LDAP. The defaul LDAP ports are: ldap: 389, ldaps: 636
Protocol (Required)

ldap or ldaps. Follow open ldap instructions to enable encrypted searches between the CloudBolt server and the ad/ldap server if you’d like to use ‘ldaps’ protocol.

For more information with enabling ldaps, go to: http://www.server-world.info/en/note?os=CentOS_6&p=ldap&f=3

Account
The service account in AD/LDAP that can search for users and join servers to the domain if applicable.
Password
The password that authenticates the service account.
LDAPVersion
2 or 3. If not sure check with your Directory Administrator about what to enter here.
Base DN
The starting point when searching for users in the directory
Search Filter

This can be used to limit the users returned in the first phase of authentication. It uses the LDAP filter syntax.

For more information with LDAP search: http://www.centos.org/docs/5/html/CDS/ag/8.0/Finding_Directory_Entries-LDAP_Search_Filters.html

Disabled User Filter
Users that match this filter will be set to inactive in CloudBolt.
Domain
The domain for the AD/LDAP; e.g., exampledomain.com.
Username Field
The AD/LDAP attribute that should be used for username when creating the CloudBolt user. For AD it usually is sAMAccountName, most other directory servers it should be uid.
Firstname Field
The AD/LDAP attribute that should be used for username when creating the CloudBolt user. Defaults to givenName.
Lastname Field
The AD/LDAP attribute that should be used for username when creating the CloudBolt user. Defaults to sn.
Email Field
The AD/LDAP attribute that should be used for username when creating the CloudBolt user. Defaults to mail.
Email Format

All directories may not store email information or an admin may wish to overwrite the email settings for each user. Using CloudBolt, it is possible to define an email template based on other user attributes; e.g., @@first@@.@@last@@@@domain@@ or @@username@@@some_clodbolt_c2_specific_email_domain.

Possible references are first, last, username or domain

Auto-create users
Any valid user in LDAP can access CloudBolt even if a matching CloudBolt user didn’t exist prior to the first login attempt. See Auto-Creation of Users.

Verification

The CloudBolt server ships with OpenLDAP ldapsearch utility. In order to verify the AD/LDAP connection, one should log into the CloudBolt server console and run ldapsearch passing uri, binddn and search based on the way AD/LDAP is configured in CloudBolt.

Example:

ldapsearch -H "PROTOCOL://IP:PORT" -D "ACCOUNT" -b BASEDN -w PASSWORD -s sub -x -v  "FILTER"

Note on Joining Windows Servers to Domains

Windows Server 2008R2 does not support use of NETBIOS naming. If you selected the Auto-join servers option and want to have Windows Server 2008 R2 servers auto-join the domain, it is recommended that the service account and domain are defined in this form: adminaccount@domain.com and domain.com.

Auto-Creation of Users

For LDAP/AD, if you check the box for auto-creating users, any user that has a valid AD/LDAP credentials will be given an account in CloudBolt the first time they log in.

For Google authentication, auto-creation of users is always enabled (for the domains specified in the whitelist).

Auto-created users will not have any permissions or belong to any groups until a Group Admin explicitly grants permissions to a user.

Single Sign-On (SSO)

Single Sign-On (SSO) is a tool that can be used to provide access to CloudBolt. An SSO Identity Provider (IdP) acts as a single source of truth for authenticating users. Enterprise organizations use SSO to control which users in their organization can access which applications, all from one place.

Note

Existing SSO configurations based on the djangosaml2 Python package will continue to function in the same manner, although djangosaml2 will no longer be installed on CloudBolt by default. To install djangosaml2 in 9.3 and later, run pip install djangosaml2 in the command line of your CloudBolt instance.

Setting up SSO with CloudBolt

To link CloudBolt to an SSO Provider, complete both of the following:

  • Configure the SSO IdP on CloudBolt
  • Configure the CloudBolt Service Provider (SP) on the SSO IdP

Both the CloudBolt configuration and the SSO IdP configuration require XML metadata from one another.

Configure the SSO IdP on CloudBolt

  1. Click Admin> Single Sign-On.

  2. Click Add a Single Sign-On IdP to add a new SSO Provider.

  3. Select the IdP type. The type only affects how the IdP shows up in the CloudBolt UI and the initial settings for some of the options. All of the IdP types can be configured to work as any of the others.

  4. Complete the Configure a SAML Provider form.

    Name: The name of the this SSO Provider. It will be visible to the user on the login page if the “Automatically login to SSO” setting described in “Logging in to CloudBolt Using SSO” is off.

    Name ID Format: The format of the Name/ID that CloudBolt will send to and expect from this IdP.

    Metadata Validity Limit: The number of hours that this configuration is expected to be accurate. Identity Providers consuming the metadata of this SSO Provider may cache this metadata for this number of hours before refreshing it.

    Accepted Time Difference: Maximum allowed time difference, in seconds, between this SSO Provider and the IdP.

    Contact Person: The CloudBolt User to associate with this SSO Provider and its certificate.

    Organization Name, Organization Display Name, and Organization URL: These fields are added to the metadata that CloudBolt generates for this particular SSO provider. These fields are also used during certificate (Public Key) generation and will be associated with any certificate CloudBolt generates.

    Sign Requests: If true, CloudBolt will cryptographically sign requests sent to this IdP.

    Force Authentication: Make the user sign in to the IdP, regardless of whether they are already signed in.

    Assertion Signed: Indicates if this SSO Provider wants the IdP to send the assertions signed.

    Response Signed: Indicates if authentication responses to this SSO Provider must be signed.

    Allow Unknown Attributes: Indicates if this SSO Provider will accept unknown attributes from the IdP. This needs to be enabled if you wish to send anything other than username, email, first_name, and last_name from the IdP.

    Create Unknown Users: Indicates if CloudBolt should create a new User if it cannot find a User that matches a valid assertion from the IdP.

    Debug: Indicates if this SSO Provider should log extra information. Useful for troubleshooting during setup.

    Email, Given Name, Surname, User ID Attribute Name: These fields map the User attributes on CloudBolt to the expected field name on an incoming IdP request. For example, if Email Attribute Name is “userEmail”, then the IdP associated with the SSO Provider must be configured to send users’ emails in a field named “userEmail”.

  5. (Optional) If you want users to be able to log in to your CloudBolt instance via SSO when they visit the CloudBolt login page, then you must link your new CloudBolt SP with a Portal. Select the appropriate Portal from the Admin> Branding and Portals list and use the Edit form to associate your new SSO Provider. More details are in the Portals section below.

  6. (Optional) Add your own cryptographic information on the Certificates form.

    After creating a new SSO Provider, a Private Key and Public Key (certificate) will automatically be generated.

    • Private Key is a cryptographic secret used for signing/validating SAML requests. It must be secret. CloudBolt will generate a 4096-bit RSA private key by default and save it in .pem format. You can upload a new private key that will overwrite the existing private key on the Certificates form.
    • Public Key is an X.509 certificate that CloudBolt generates based on the Private Key. You can upload your own X.509 certificate on the Certificates form. If you wish to provide your own certificate, be sure to also upload the private key from which the certificate was generated or cryptographic signatures will not function. You can also clear the existing certificate on this form, which will cause CloudBolt to generate a new certificate that includes the specified Private Key, Contact Person, and Organization Details described above.
  7. Configure the IdP for the CloudBolt Service Provider as described in the next section.

  8. Upload your IdP’s metadata using the Upload IdP XML form.

    Once you have configured your IdP to work with CloudBolt, you will need to upload the metadata XML from your IdP to CloudBolt. CloudBolt provides three different methods for uploading this XML.

    • URL: Set the Configure Using field to Metadata URL and enter the IdP’s metadata URL. CloudBolt will attempt to retrieve the XML from the given URL when you submit the form.
    • File: Set the Configure Using field to Metadata File and use the file browser in the Metadata File field to select an XML file to upload from your computer.
    • Text: Set the Configure Using field to Metadata Text and then copy your IdP’s metadata XML into the Metadata Text text box.

Configure the CloudBolt Service Provider on the Identity Provider

Configure your IdP with the parameters expected and provided by the SSO Provider you configured on the CloudBolt instance. Most likely, you will need to send your CloudBolt Service Provider’s metadata to your IdP.

On the details page for a given CloudBolt SSO Provider, there are two links: one for the SP’s metadata and one for its Assertion Consumer Service (ACS) URL. There is also a Download Metadata XML button that will download the metadata XML for this SP. Your IdP may allow you to upload an XML file or input the metadata URL that CloudBolt provides, but you may need to visit CloudBolt SP metadata URL, copy it, and paste the metadata to a field on your IdP.

The following fields will need to be included on your IdP configuration. The IdP should extract some or all of these from CloudBolt SP metadata:

  • Public Key (certificate) if you want communications between CloudBolt and your IdP to be signed.

  • Name ID Format to tell the IdP and CloudBolt what format user names/IDs must be in.

  • Attribute Name fields must be configured so that the IdP will send the right attributes with the expected field names to CloudBolt.

    For example, if CloudBolt has these settings on the SSO Provider:

    • Email Attribute Name: userEmail
    • User ID Attribute Name: userName

    Then the IdP must be configured to send a User’s email in a field named “userEmail” and the User’s username in a field named “userName”.

CloudBolt requires that four attributes, at minimum, be sent for each User: email, username, first name, and last name. If these are not sent to CloudBolt by the IdP, or if any of these values are blank, the SSO Login process will fail.

Okta Specifics

A CloudBolt Okta application needs to be configured in the following manner to work with your CloudBolt instance:

Endpoints:

  • Set the Single Sign-On URL field to the ACS URL provided by your Okta Service Provider in CloudBolt.
  • Check the Use this for Recipient URL and Destination URL box on this field.
  • Set the Audience URI (SP Entity ID) field to the metadata URL provided by your Okta Service Provider in CloudBolt.

The URLs should look similar to:

_images/sso-url.png

Attribute Statements

We recommend configuring the Attribute Statements for your Okta app according to the following table, but you can adjust these recommendations as necessary to send more user attributes from Okta to CloudBolt.

Name Name Format Value
firstName Unspecified user.firstName
lastName Unspecified user.lastName
email Unspecified user.email
username Unspecified appuser.userName

These settings make Okta send the “firstName,” “lastName,” and “email” defined on the login user’s profile to CloudBolt under the “firstName,” “lastName,” and “email” keys, respectively.

The final Attribute Statement, “username,” is handled slightly differently so that users can have a username specified by the CloudBolt Okta app instead of depending on the username defined on the user’s Okta profile.

Metadata

The CloudBolt Service Provider will need the “Identity Provider metadata” information. This link can be found on your Okta app webpage, under the Sign On tab.

Go to the details page of the Service Provider you are configuring in CloudBolt. Click the “Upload IdP XML” button. Provide the XML via URL, file upload, or copy-and-paste.

Logging in to CloudBolt Using SSO

To access a CloudBolt that is linked to an SSO IdP, either log in from CloudBolt’s UI or from your IdP.

  1. If logging in from CloudBolt’s UI, depending on the setting “Automatically login to SSO”, one of two log in strategies is available. This setting is found in Admin> Miscellaneous Settings.
    • Disabled: In the CloudBolt UI, click Log in with “name of SSO Provider”. This setting is disabled by default.
    • Enabled: You will be sent directly to the SSO Provider log in page when you access your CloudBolt instance. If Force Authentication is enabled on the SSO Provider in CloudBolt, you must log in to your SSO Provider manually each time.
  2. CloudBolt sends a Security Assertion Markup Language (SAML) request that identifies the user trying to log in to the SSO IdP. This happens automatically when the above setting is Enabled, and upon clicking “Log in with…” when the above setting is Disabled.
  3. Log in to the SSO IdP if you are not already logged in.
  4. If prompted, select CloudBolt from the list of available applications on your SSO IdP interface. You may also be automatically redirected to CloudBolt.
  5. The SSO IdP sends a SAML request to CloudBolt with the user’s information.
  6. CloudBolt validates the request.
  7. CloudBolt tries to identify the User specified in the IdP’s SAML assertion.
  8. If CloudBolt cannot find a matching User, then, depending on the value of the “Create Unknown User” setting on the SSO Provider, one of the following will occur:
    • True: CloudBolt will create a new user with information sent from the SSO IdP.
    • False: CloudBolt will not create a user and will direct the user back to the login page.
  9. If a SSO User Update Orchestration Action is enabled, then CloudBolt runs the action to update the incoming user.
  10. If an External User Sync Orchestration Action is enabled, then CloudBolt runs the action to update the incoming user.
  11. CloudBolt logs the user in, and sends them to their homepage.

SSO User Update Orchestration Action

If there is an enabled SSO User Update Orchestration Action, then it will run on the appropriate User immediately after the User is created or identified. You can safely assume that the SAML Assertion coming from the SSO IdP has been validated.

After running the incoming User through any enabled SSO User Update Orchestration Actions, CloudBolt will run the same User through any enabled External User Sync Orchestration Actions as described below in External User Sync. You can configure CloudBolt to handle everything related to SSO users entirely in an SSO User Update action, entirely in an External Sync User action, or in a combination of the two. The default SSO User Update Orchestration Action provides simple handling (described below) for associating a User with a particular LDAP domain when they are created/updated during SSO login, but if you wish to do anything other than the default behavior, then you must handle it in either the SSO User Update or External User Sync Orchestration Actions.

Username and LDAP

The OOTB Orchestration Action has two different methods for handling automatically assigning a User to a particular LDAP within CloudBolt.

1. Have the SSO IdP send the username attribute in the form <username>@<ldapdomain>. The action will set the incoming User’s username to <username> and associate the User with the LDAPUtility that has a ldap_domain matching <ldapdomain>. For example, if I configured my SSO IdP to send the username “herbert@cloudbolt.org”, then this user would end up with the username “herbert” and be associated with the LDAPUtility that has domain “cloudbolt.org” (assuming such an LDAPUtility exists).

2. Explicitly define the domain name of the LDAP Utility for a given User in the ldapDomain attribute field on your SSO IdP. You can change the name of the field that CloudBolt expects from the SSO IdP by changing the global variable LDAP_DOMAIN_SSO_ATTR_NAME at the top of the OOTB SSO User Update Orchestration Action to be something other than ldapDomain. For example, if my SSO IdP sends the LDAP domain for a user in a field called UserLDAPIdentifier, then I would update the line of the OOTB SSO User Update Orchestration Action where LDAP_DOMAIN_SSO_ATTR_NAME is defined to be

LDAP_DOMAIN_SSO_ATTR_NAME = “UserLDAPIdentifier”

Then, if my SSO IdP sent a SAML assertion to CloudBolt with the following data

Field Value
username herbert
UserLDAPIdentifier cloudbolt.org

CloudBolt would create or update a User to have username “herbert” and associate that User with the LDAPUtility that has domain name “cloudbolt.org,” assuming one exists.

Orchestration Action Arguments

These are the arguments sent to SSO User Update action during SSO login.

Argument Description
job The Job associated with this action. Will only be populated if the action is being run as part of a Job. This will be None when called as part of an SSO login.
user The User being updated or created.
attrs_from_sso A dict of all the key-value pairs sent from the SSO IdP.
sso_instance The database model for the SSO Provider on CloudBolt.
creating A boolean flag that indicates if the User above is being created (True) or updated (False).

Integration with Other CloudBolt Systems

Local Authentication for SSO Users

By default, users that are created via a login from an SSO IdP do not have a local password assigned. These users will always need to log in via SSO and will not be able to log in using local authentication unless one of the following happens:

  • A CloudBolt administrator assigns a password to the user.
  • The user clicks the “Forgot your Password?” link on the CloudBolt login page.

Portals

Portals created through the Branding and Portals page in CloudBolt can be associated with a single SSO Provider. Portals are used for a handful of different things in regards to CloudBolt’s SSO Providers:

  • Determining the domain name for the Assertion Consumer Service (ACS) and metadata URLs, both of which are included in the SSO Provider’s metadata generated by CloudBolt and displayed on the SSO Provider’s details page.
  • Determining which SSO Provider, if any, should be linked from the CloudBolt login page, depending on which domain name the user is accessing the site through.

Each Portal can only be linked with a single SSO Provider. Multiple SSO Providers for a single domain name are not currently supported.

SSO Providers do not need to be linked with a Portal, but users will only be able to start the SSO login process from CloudBolt (either by clicking the “Log in with <Name of SSO Provider>” button or by an automatic redirect) if the SSO Provider is linked to the appropriate Portal. Otherwise, SSO users will only be able to log in to CloudBolt from their IdP.

External User Sync / LDAP

External User Sync Orchestration Actions will run as part of CloudBolt’s Assertion Consumer Service whenever CloudBolt logs an SSO user in. See Using the “User Permission Sync From LDAP” Action.

The External User Sync actions, if any are enabled, will run after the SSO User Update actions (see SSO User Update Orchestration Action). If the User is being logged in via an SSO Provider, then the External User Sync action will receive the attrs_from_sso kwarg (the same one that the SSO User Update action receives), which is a Python dict containing all the key-value pairs sent from the SSO IdP to CloudBolt.

Glossary of Terms

  • Assertion Consumer Service (ACS): The endpoint that a Service Provider (SP) exposes to which an Identity Provider (IdP) sends authentication requests.
  • Single Sign On (SSO): A design pattern in which users log in to a single interface that gives them access to a variety of other applications and allows controlling user access from a single place. Users only need to remember one set of credentials for all of their applications.
  • Identity Provider (IdP): An SSO application such as Okta or OneLogin.
  • Service Provider (SP): An application that uses an IdP for authenticating users.
  • Metadata: Data about data. In the case of SSO, this usually means an XML blob that describes either an IdP or SP that contains information such as the Assertion Consumer Service endpoint and what user attributes are required/allowed.
  • SAML (Security Assertion Markup Language): The protocol that IdP and SP use to communicate, a subset of XML.

RADIUS Two-Factor Authentication

When using external LDAP/AD authentication, CloudBolt optionally supports two-factor authentication with RADIUS providers such as RSA SecurID tokens.

  1. Go to Admin Home > Database Browser.
  2. Under Utilities, click Add next to RADIUS Utilities.
  3. Enter the Server (IP or resolvable hostname), Port, Auth policy (e.g. Token Only), and Secret for the RADIUS server you wish to use.
  4. Click SAVE.
  5. In your RADIUS system, add an agent/client for your CloudBolt server to match the secret you chose above.
  6. After setting up the RADIUS Utility and your LDAP settings, users on the login page will see a Token field on the login page after selecting an LDAP domain.
Caveats:
  • CloudBolt does not support challenge responses from a RADIUS server at this time. Any Auth policy that includes both token and password, does so by concatenating the two values before attempting to authenticate to the RADIUS server.
  • CloudBolt does not support changing RADIUS credentials such as password, so you must not use options such as “Require user to change password at next login” as exists on SecurID.