Adding Single Sign-On to CloudPassage Halo

(1)

Adding Single Sign-On to CloudPassage Halo

For Halo Site Administrators

About SAML-Based Single Sign-On

Implementing a single sign-on (SSO) infrastructure enables your users to sign in once and have access to all authorized resources in your organization. Single sign-on is a very desirable convenience for users who need to use many different remote applications in their daily work. A number of different approaches to single sign-on have been developed over the years, some proprietary and some based on open standards.

(2)

The current version (SAML 2) supports, among other capabilities, two workflows for logging in. In identity

provider-initiated login, the user first logs into the identity provider's site and chooses the desired resource; the identity

provider then sends an assertion to the service provider, who in turn makes the resource available to the user. In

service provider-initiated login , the user attempts to log directly into the service provider's site; that login is temporarily

redirected to the identity provider along with a request for an assertion. The identity provider returns an assertion, and the service provider then gives the user access to the service.

SAML-based SSO is available as a cloud service from several identity providers, including OneLogin, Okta, Ping Identity, and others. CloudPassage Halo is designed to integrate with most single sign-on identity providers that are SAML v2.0-compliant, and the integration has been tested and verified with one vendor (OneLogin).

Note: Halo currently requires SAML 2.0, and it supports identity provider-initiated login only.

The next section of this document provides general instructions for integrating Halo with a SAML identity provider. The following appendix gives more detailed, identity provider-specific instructions for integrating Halo into the OneLogin SSO service.

Integrating Halo With a Single Sign-On Provider

(3)

Note: These instructions assume that you already have an administrative account on your identity provider's

site, and that you are a site administrator user in Halo.

1

Enable and configure SSO

To enable your Halo users to log into the Halo Portal through a SAML 2.0-based single sign-on solution, start by enabling single sign-on in the Halo Portal.

1. Log into the Portal and navigate to the Authentication Settings tab on the Site Administration page. Scroll down to the Single Sign-On Settings section.

2. Select the Enable Single Sign-On (SSO) check box. The page expands to display the single sign-on settings form.

3. Copy the account ID from this form. The ID identifies your organization's Halo account to the identity provider, and it is passed from identity provider to service provider (Halo) in the SAML assertion. You will need to provide this ID to your identity provider when configuring SSO for Halo in the provider's portal. The provider will use the ID to construct two URLs for connecting to Halo:

Login URL: https://portal.cloudpassage.com/saml/init/account_id

Consumer URL: https://portal.cloudpassage.com/saml/consume/account_id

Depending on your identity provider's requirements, you may need to construct these URLs yourself and provide them, or you may be able to simply provide the account ID.

4. Obtain the following items of information from your identity provider, and enter them into the following fields on the single sign-on settings form in the Halo Portal:

SAML issuer URL. Paste in the URL that uniquely specifies the identity provider.

SAML endpoint URL. Paste in the URL of the identity provider's endpoint that receives requests. Note: Your identity provider might supply only one URL for you to use. If so, paste that URL into

both of the above fields.

(4)

(This item is not specified by the identity provider; whether and which page to specify is your decision.) x.509 certificate. An x.509 certificate for your organization's account with the identity provider. Paste the entire certificate (including the Begin Certificate and End Certificate sections) into the field. 5. Make SSO Required. If you want to disallow all direct logins to the Halo Portal, select this checkbox at the

bottom of the form. If you do select the box, you must provide SSO access to all existing and future Halo users. Note that you cannot select the box unless you are currently logged in through SSO.

Note: As long as this checkbox remains selected, Halo users' account pages have no displayed

password field, Halo users cannot reset their passwords, and new Halo users do not receive email invitations to log into Halo.

6. Click Save to commit your SSO settings.

2

Configure users in Halo

Every person in your organization that will use SSO needs to have an account with the identity provider and in the Halo Portal.

In the Halo Portal, you create users by adding them from the Users tab of the Site Administration page. Note that user accounts in Halo are identified by a unique username, and this username must match the username passed by the identity provider to Halo in the SAML assertion. Therefore, the identity provider must be aware of every user's Halo username.

See also Automatic provisioning of Halo Users for SSO, below, for an alternative to manually creating Halo users in the Portal.

3

For Halo users: Logging into Halo with SSO

If you are a Halo user and your organization has integrated Halo with a SAML-based single sign-on solution, you will have been provided with a mechanism (such as a URL) for accessing the identity provider's protected applications, including the Halo Portal.

You start by logging into the identity provider. You then select Halo or some other SSO-protected application to access, and you are immediately logged into it. Your login context with the identity provider serves as your authentication to Halo and to all other applications covered by your SSO solution.

Note: Whenever a Halo user logs into the Portal through SSO, a Halo event of type "Halo login success"

(or "Halo login failure", if it fails) is logged,

Using GhostPorts with SSO:

If you are a Halo GhostPorts user using SSO, the workflow for opening GhostPorts is the same as with multi-factor login to Halo:

If you log into Halo through SSO, and if you open GhostPorts less than one minute after logging in, you are not required to authenticate to GhostPorts.

If you log into Halo through SSO, and If you wait longer than a minute before opening GhostPorts, you are required to authenticate to GhostPorts using either SMS or YubiKey two-factor authentication.

Automatic Provisioning of Halo Users for SSO

(5)

creating Halo users. Given that all of your users that access Halo must have accounts with both the identity provider and with Halo itself, you can create those Halo user accounts in either of two ways:

Manually, by logging into the Halo Portal and creating Halo users. Automatically, by using Halo's just-in-time provisioning capability.

With just-in-time autoprovisioning, Halo uses information passed to it in the identity provider's SAML assertion to determine whether a user requesting access is already an existing Halo user. If the user is not, Halo creates the user's Halo account from the information in the assertion. If the user already exists but some of the passed

information is different from what is in the current Halo account, the Halo account is updated with the new information.

Setting Up Automatic Provisioning:

If you are administering the SSO solution for your organization and are implementing just-in-time provisioning, you will need to provide the following additional user parameters for the SAML assertion that the identity provider sends to Halo. You may implement the parameters and store the user information in any convenient way—for example, as extra fields in your organization's user database.

admin. Whether the user is a Halo site administrator (true or false). ghostport_access. Whether the user is a GhostPorts user (true or false). portal_access. Whether the user has Portal access (true or false). firstname.

lastname. email.

sms. The user's mobile phone number for receiving SMS authentication codes (if the user uses SMS authentication and (1) is a GhostPorts user, or (2) if multi-factor login to the Halo Portal is required).

yubikey. The user's YubiKey key value (if the user uses a YubiKey for authentication and (1) is a GhostPorts user, or (2) if multi-factor login to the Halo Portal is required).

Other important parameters that are in every assertion, regardless of whether autoprovisioning is used, include these: NameID. The user's Halo username, as noted in Step 2, above. Halo usernames must be unique across your Halo account.

Account ID. The ID that identifies your organization's Halo account to the identity provider. It is passed in the assertion as the Consumer URL, as noted in Step 1, above.

When autoprovisioning is in use, the first time that a user who is not an existing Halo user attempts to log in, all of the above parameters are used to initialize the Halo user in the Portal. On subsequent access attempts, if any of the passed parameters have different values from what is stored in Halo, the user's Halo information is updated accordingly.

Note: Whenever a Halo user is created or updated, either manually or through automatic provisioning, a Halo

event of type "Halo user added" or "Halo user modified" is logged.

Appendix: Integrating Halo With OneLogin

(6)

use case currently supported for Halo with OneLogin is for identity-provider-initiated login.

This appendix describes in detail the steps you need to take in the Halo Portal and in the OneLogin Portal to complete the configuration.

Note: These instructions assume that you already have an account with Administrator privileges on OneLogin,

and that you are a site administrator user in Halo.

Enable and Configure SSO with OneLogin

To enable your Halo users to log into the Portal through OneLogin SSO, first log into the Halo Portal in one browser window or tab, and simultaneously log into your OneLogin portal in a separate window or tab.

1. In the Halo Portal, navigate to the Authentication Settings tab on the Site Administration page. Scroll down to the Single Sign-On Settings section.

Enable single sign-on in Halo:

2. Select the Enable Single Sign-On (SSO) check box. The page expands to display the single sign-on settings form.

3. Copy the account ID at the top of this form into your browser's clipboard. The ID identifies your organization's account with OneLogin.

Install OneLogin's Halo Application and Transfer the Account ID to OneLogin:

(7)

CloudPassage Halo (auth-only) requires you to manually create (in Halo) the Halo user accounts for all of your users that need SSO access to Halo.

CloudPassage Halo (with provisioning) is functionally the same application, except that it automatically creates Halo accounts for any of your users when they first log into Halo. You will not have to explicitly

provision any users within Halo. See Automatic Provisioning of Halo Users for SSO for more information on this feature.

5. Click add for the app that you wish to use.

6. In the Add Halo form, select your chosen CloudPassage Halo application as the app to be used by your organization, then click Continue. The app is now visible under the Apps > Company Apps tab. 7. Under Company Apps, locate the appropriate CloudPassage Halo application and click its edit link.

8. Click the Configuration tab and paste the account ID (which you just copied from the single sign-on settings form in the Halo Portal) into the Account ID field.

9. Click Update to save your change. Transfer Provider URLs to Halo:

(8)

a. Copy the URL displayed under Issuer URL, switch to the browser window displaying the single sign-on settings form in the Halo Portal, and paste the URL into the SAML issuer URL field.

b. Back in the OneLogin browser window, copy the URL displayed under SAML Endpoints, then switch to the Halo window and paste the URL into the SAML endpoint URL field.

c. For Credentials, select "Configured by admin" or "Shared", depending on how user credentials are determined in your organization.

d. For Default values, choose what the Halo username for a user added to this application should default to—for example, the OneLogin username, email address, or other identifier. For any user whose actual Halo username does not match the default, you will need to manually specify the user's Halo username.

e. Click Update to save any settings you have changed. Transfer x509 certificate to Halo:

11. In the OneLogin portal, navigate to the SAML tab under the top-level Security tab:

(9)

then once again switch to the Halo Portal and and paste the certificate into the x.509 certificate field in the single sign-on settings form.

Complete the configuration:

13. Logout landing page (optional). If you want a certain page to be displayed to a user who logs out of Halo, enter the URL to that page in this field. A typical page to specify here might be your organization's Company Apps tab in the OneLogin portal. Logged-out users could then immediately log back into Halo or any other SSO-protected application.

14. Make SSO Required. If you want to disallow all direct logins to the Halo Portal, select this checkbox at the bottom of the single sign-on settings form. If you do select this checkbox, you must provide SSO access to all existing and future Halo users. Note: you cannot select the box unless you are currently logged in through SSO.

Note: As long as this checkbox remains selected, Halo users' account pages have no displayed password

field, users cannot reset their passwords, and new users do not receive email invitations to log into Halo.

15. Click Save at the bottom of the single sign-on settings form to save your changes.

Test your SSO setup:

Use your own account to test the connection between Halo and OneLogin. Take these steps: 1. Make sure that you are logged out of Halo, and then log into OneLogin.

Note: If your Halo username is different from your OneLogin username, take these steps first:

a. Click Apps, then Company Apps.

b. Click edit beside the Halo application icon, then click the Logins tab.

c. Locate your username and click Edit. The Halo field should be blank, if it is defaulting to the (OneLogin) Username parameter.

d. Type your Halo username in the Username field, and click Update. e. Navigate back to Company Apps.

(10)

You're done with the configuration! Once you provision Halo users in both OneLogin and the Halo Portal, they will have have SSO access to Halo.

Replicate Selected OneLogin Users in Halo

If your organization has an existing integration with an SSO identity provider, all of your users are already mirrored as users on the identity provider's site. Of those users, the ones that will use Halo need to be

Added as "logins" to the CloudPassage Halo application in the OneLogin portal, and

Created as Halo users, either manually in the Halo Portal itself, or automatically as described in Automatic provisioning of Halo Users for SSO.

To give you greater flexibility in naming users with accounts on both OneLogin and Halo, OneLogin allows a user to have a different username in Halo than on OneLogin. When adding a user to the Halo application in OneLogin, you have the opportunity to specify the user's Halo username. (You can also do that when editing a user, under the Logins tab in your CloudPassage Halo application.)

When you add a user to your Halo Application in OneLogin, the new user's Halo login name defaults to a value (for example, OneLogin username or email address) that you can specify on the Single Sign-On tab of the application. Depending on your conventions for both OneLogin and Halo usernames, by specifying the appropriate default you may not need to explicitly specify a Halo username in many cases.

For Halo Users: Logging Into Halo with OneLogin SSO

If you are a Halo user and your organization has integrated Halo with OneLogin, you will have been provided with a mechanism (such as a URL) for accessing the Halo Portal and all other applications protected by your OneLogin SSO solution. The URL will take you to your Company Apps page on the OneLogin site, from which you can then access Halo itself with a single click.

Your login context with OneLogin will serve as your authentication to Halo and to all other applications covered by your SSO solution.

When you wish to use Halo:

1. Follow the URL for accessing your SSO-protected applications. You are taken to the OneLogin site.

2. If you are not already logged into OneLogin, log in with your OneLogin credentials. If you are currently logged in, you will not need to provide those credentials again.

Your company's application page in OneLogin appears, displaying (perhaps among others) a Halo icon.

3. Click the icon for Halo. You are immediately logged into the Halo Portal, and your Dashboard page is displayed. That's it! You now can use any parts of Halo that you are authorized for.

Using GhostPorts with SSO:

If you are a Halo GhostPorts user using SSO, the workflow for opening GhostPorts is the same as with multi-factor login to Halo:

(11)

If you log into Halo through SSO, and If you wait longer than a minute before opening GhostPorts, you are required to authenticate to GhostPorts using either SMS or YubiKey two-factor authentication.

Adding Single Sign-On to CloudPassage Halo