Overview

Keeper Connection Manager can be configured to authenticate users with any SAML 2.0 compatible identity provider. Users can be forced to login with SAML, or you can make SAML an optional login link from the home screen.

Instructions for popular Identity Providers is below.

Azure Configuration

The first step regardless of installation method is to configure your SAML 2.0 identity provider using Microsoft Azure.

(1) In Azure, go to Enterprise Applications and Create a new application.

(2) Give the Enterprise Application a name, and then select "non-gallery" application.

(3) Set up Single Sign On with SAML.

(4) Configure for SAML

(5) Set up the SAML properties to point Azure to your Keeper Connection Manager installation URL:

(6) To support Azure Group to Keeper Connection Manager User Group mappings, you can add a Group claim by editing the Attributes & Claims then adding a Group Claim.

When prompted, you can decide whether the group claim is always sent, or only for specific groups or assigned users.

(7) Assign users and/or groups to the Keeper Connection Manager application, as you would normally do with any SAML connected app.

(8) Download the Azure Metadata file and save to your local machine as metadata.xml

The Azure side of the setup is complete. Note if you change anything, you need to re-download a new metadata.xml file.

(9) Add the KCM Logo

From the "Properties" screen of the Enterprise Application, upload the KCM logo. The file can be downloaded below.

Here's how the logo will look:

Next: KCM Configuration

Advanced Linux Install Method

If you have installed Keeper Connection Manager using the advanced linux install method, setting up SAML can be performed following the steps below.

Installing SAML support for Guacamole

Keeper Connection Manager packages Guacamole’s SAML support within the kcm-guacamole-auth-sso-saml package:

$ sudo yum install kcm-guacamole-auth-sso-saml

Connecting Guacamole to SAML

Guacamole’s main configuration file, /etc/guacamole/guacamole.properties, must be modified to point the SAML installation:

$ sudo vi /etc/guacamole/guacamole.properties

The guacamole.properties file provided with Keeper Connection Manager is organized into sections documented with blocks of comments and example properties. The first section which must be modified is marked “SAML-1” and defines the IdP configuration. Uncomment the saml-idp-metadata-url and saml-entity-id property. You'll need to reference the IdP's metadata file and Entity ID.

##
## [SAML-1] Identity provider details
##
## The details of the identity provider (IdP) that Guacamole should use for
## authentication. These properties dictate how Guacamole should communicate
## with the IdP, including the how users should be redirected for
## authentication by the IdP.
##
## The SAML IdP will typically provide this information in advance in the form
## of an XML file. If no such XML file is provided, or if information is
## missing from that XML file, additional properties will need to be specified
## to provide that information.
##
## The key pieces of information required are:
##
##  * The URL of the SAML endpoint used by the IdP.
##  * The "entity ID" that should be used by Guacamole to identify itself with
##    the IdP.
##
## If the SAML IdP provides an XML metadata file, it is unusual for that file
## to not contain both of the above pieces of information.
##
## THIS INFORMATION IS REQUIRED if the SAML extension will be used.
##

saml-idp-metadata-url: file:///etc/guacamole/metadata.xml
saml-entity-id: https://glyptodon.mycompany.com

The second section contains the callback URL that is used by the IdP. This is typically set to the user-facing URL of the Keeper Connection Manager service.

##
## [SAML-2] Guacamole server details
##
## The details of the Guacamole server that should be provided to the SAML IdP
## when authenticating the user. This information defines how the SAML IdP
## should send identity assertions back to the Guacamole server if their
## identity is confirmed.
##
## THIS PROPERTY IS REQUIRED if the SAML extension will be used. It is not
## otherwise possible for Guacamole to know its own public-facing URL,
## particularly in a production deployment that is expected to use SSL
## termination.
##

saml-callback-url: https://glyptodon.mycompany.com

The 3rd section contains the SAML group attribute that can be used for mapping IdP Groups to Keeper Connection Manager Groups. This is useful for assigning permissions to Connections based on a Group attribute from your identity provider. The below example is referencing a Microsoft Azure configuration.

##
## [SAML-3] Identity mapping
##
## How identity assertions received form the SAML IdP should be mapped back to
## user and group identities. The mapping for user identities is already known
## by the SAML standard, but the mapping for user groups can vary. If your SAML
## IdP provides user group information in addition to user identities, the
## attribute used by your SAML IdP to define those groups within assertions
## should be provided here.
##

saml-group-attribute: http://schemas.microsoft.com/ws/2008/06/identity/claims/groups

The 4th section contains optional parameters that can be set.

##
## [SAML-4] Request/response compression
##
## Whether compression should be used for requests sent to the SAML IdP, and
## whether compression should be requested for responses from the SAML IdP.
## By default, compression will be used for both requests and responses.
##

#saml-compress-request: true
#saml-compress-response: true

Completing installation

Guacamole will generally only load new extensions and reread guacamole.properties during the startup process. To apply the configuration changes, Guacamole must be restarted:

$ sudo systemctl restart guacamole

KCM Final Setup

Once you have activated the SAML module, there will be a new "Sign in with SAML" link on the login screen of the application as seen below:

When setting up your user identities in the Settings area, if you would like a user to login with SAML / SSO, just leave the "password" field empty.

If you would like to automatically mapping Group assignments in the identity provider to Keeper Connection Manager Groups, ensure that the saml-group-attribute parameter is defined to match the Identity Provider Group Attribute. The name of the Group in Keeper Connection Manager needs to match this identifier exactly in order for the mapping to work.

If the group name attribute from the identity provider is not easy to read, this may end up requiring you to create Group Names that look like below:

Okta Configuration

The first step regardless of installation method is to configure your SAML 2.0 identity provider using Okta.

(1) In Okta, go to Admin > Applications > Create App Integration and select SAML 2.0. Click Next.

(2) Give the Enterprise Application a name and upload the logo file linked below then click Next.

The image logo is here:

(3) Configure the SAML Settings

The SAML configuration should match the format as seen below:

• Replace demo3.lurey.com with the URL of your Keeper Connection Manager domain.

• Ensure the full path appears, e.g. https://DOMAIN/api/ext/saml/callback

• For the Audience URI, use the path to the Login screen (remove the trailing slash). For example, https://demo3.lurey.com

Scroll down to the Group Attribute Statements. To send the group attribute, set the name to "groups", and the name format to "Basic". If you would like ALL groups assigned to the user to be sent to Keeper Connection Manager, select the "Matches regex" with a value of ".*"

Click Next.

(4) In the Feedback section, make the selections as appears below.

(5) Assign users and/or groups to the Keeper Connection Manager application, as you would normally do with any SAML connected app.

(6) Download the Okta Metadata file and save to your local machine as metadata.xml

The location of the metadata file depends on your version of the Okta interface. In this example there is a link called "Identity Provider metadata" on the application page. There may also be a text box that contains the metadata which you can copy and paste into a local file on your computer.

The metadata XML file could also be linked in the Sign On tab > SAML Signing Certificate section under "Actions".

Save the resulting metadata.xml file by selecting "Save page as..." in your browser.

The Okta side of the setup is complete. Note if you change anything, you need to re-download a new metadata.xml file.

Next: KCM Configuration

Advanced Linux Install Method

If you have installed Keeper Connection Manager using the advanced linux install method, setting up SAML can be performed following the steps below.

Installing SAML support for Guacamole

Keeper Connection Manager packages Guacamole’s SAML support within the kcm-guacamole-auth-sso-saml package:

$ sudo yum install kcm-guacamole-auth-sso-saml

Connecting Guacamole to SAML

Guacamole’s main configuration file, /etc/guacamole/guacamole.properties, must be modified to point the SAML installation:

$ sudo vi /etc/guacamole/guacamole.properties

The guacamole.properties file provided with Keeper Connection Manager is organized into sections documented with blocks of comments and example properties. The first section which must be modified is marked “SAML-1” and defines the IdP configuration. Uncomment the saml-idp-metadata-url and saml-entity-id property. You'll need to reference the IdP's metadata file and Entity ID.

##
## [SAML-1] Identity provider details
##
## The details of the identity provider (IdP) that Guacamole should use for
## authentication. These properties dictate how Guacamole should communicate
## with the IdP, including the how users should be redirected for
## authentication by the IdP.
##
## The SAML IdP will typically provide this information in advance in the form
## of an XML file. If no such XML file is provided, or if information is
## missing from that XML file, additional properties will need to be specified
## to provide that information.
##
## The key pieces of information required are:
##
##  * The URL of the SAML endpoint used by the IdP.
##  * The "entity ID" that should be used by Guacamole to identify itself with
##    the IdP.
##
## If the SAML IdP provides an XML metadata file, it is unusual for that file
## to not contain both of the above pieces of information.
##
## THIS INFORMATION IS REQUIRED if the SAML extension will be used.
##

saml-idp-metadata-url: file:///etc/guacamole/metadata.xml
saml-entity-id: https://demo3.lurey.com

The second section contains the callback URL that is used by the IdP. This is typically set to the user-facing URL of the Keeper Connection Manager service.

##
## [SAML-2] Guacamole server details
##
## The details of the Guacamole server that should be provided to the SAML IdP
## when authenticating the user. This information defines how the SAML IdP
## should send identity assertions back to the Guacamole server if their
## identity is confirmed.
##
## THIS PROPERTY IS REQUIRED if the SAML extension will be used. It is not
## otherwise possible for Guacamole to know its own public-facing URL,
## particularly in a production deployment that is expected to use SSL
## termination.
##

saml-callback-url: https://demo3.lurey.com

The 4th section contains optional parameters that can be set.

##
## [SAML-4] Request/response compression
##
## Whether compression should be used for requests sent to the SAML IdP, and
## whether compression should be requested for responses from the SAML IdP.
## By default, compression will be used for both requests and responses.
##

#saml-compress-request: true
#saml-compress-response: true

Completing installation

Guacamole will generally only load new extensions and reread guacamole.properties during the startup process. To apply the configuration changes, Guacamole must be restarted:

$ sudo systemctl restart guacamole

KCM Final Setup

Once you have activated the SAML module, there will be a new "Sign in with SAML" link on the login screen of the application as seen below:

When setting up your user identities in the Settings area, if you would like a user to login with SAML / SSO, just leave the "password" field empty.

If you would like to automatically mapping Group assignments in the identity provider to Keeper Connection Manager Groups, simply create a matching group name with the proper assignments. The name of the Group in Keeper Connection Manager needs to match this identifier exactly in order for the mapping to work.

Google Workspace Configuration

The first step regardless of installation method is to configure your SAML 2.0 identity provider using Google Workspace.

(1) Login to Google Workspace at https://admin.google.com****

Visit the Apps > Web and Mobile Apps screen.

(2) Select "Add App" and select "Add Custom SAML App".

Enter an application name and description. You can also upload a Keeper Connection Manager logo. The image logo is here:

Click Continue.

(3) Download the metadata.xml file

...and then click Continue

(4) Configure the SAML Settings

Update 3 fields: ACS URL, Entity ID and Name ID format.

• The ACS URL needs to start with your Keeper Connection Manager domain followed by "/api/ext/saml/callback".

• The Entity ID is just the Keeper Connection Manager domain.

• The Name ID format must be EMAIL

Click Continue.

(5) Assign group membership (Optional)

You can now assign Group Membership to the Keeper Connection Manager application, which is optional. If you would like to assign a group, make sure that the "App Attribute" is groups (lowercase). Then click FINISH.

(6) Enable Access

After creating the SAML app, it is not yet active for all users. To enable access, click on View details and turn the application ON.

The Google Workspace side of the setup is complete. Note if you change anything, you need to re-download a new metadata.xml file.

Next: KCM Configuration

Advanced Linux Install Method

If you have installed Keeper Connection Manager using the advanced linux install method, setting up SAML can be performed following the steps below.

Installing SAML support for Guacamole

Keeper Connection Manager packages Guacamole’s SAML support within the kcm-guacamole-auth-sso-saml package:

$ sudo yum install kcm-guacamole-auth-sso-saml

Connecting Guacamole to SAML

Guacamole’s main configuration file, /etc/guacamole/guacamole.properties, must be modified to point the SAML installation:

$ sudo vi /etc/guacamole/guacamole.properties

The guacamole.properties file provided with Keeper Connection Manager is organized into sections documented with blocks of comments and example properties. The first section which must be modified is marked “SAML-1” and defines the IdP configuration. Uncomment the saml-idp-metadata-url and saml-entity-id property. You'll need to reference the IdP's metadata file and Entity ID.

##
## [SAML-1] Identity provider details
##
## The details of the identity provider (IdP) that Guacamole should use for
## authentication. These properties dictate how Guacamole should communicate
## with the IdP, including the how users should be redirected for
## authentication by the IdP.
##
## The SAML IdP will typically provide this information in advance in the form
## of an XML file. If no such XML file is provided, or if information is
## missing from that XML file, additional properties will need to be specified
## to provide that information.
##
## The key pieces of information required are:
##
##  * The URL of the SAML endpoint used by the IdP.
##  * The "entity ID" that should be used by Guacamole to identify itself with
##    the IdP.
##
## If the SAML IdP provides an XML metadata file, it is unusual for that file
## to not contain both of the above pieces of information.
##
## THIS INFORMATION IS REQUIRED if the SAML extension will be used.
##

saml-idp-metadata-url: file:///etc/guacamole/metadata.xml
saml-entity-id: https://demo3.lurey.com

The second section contains the callback URL that is used by the IdP. This is typically set to the user-facing URL of the Keeper Connection Manager service.

##
## [SAML-2] Guacamole server details
##
## The details of the Guacamole server that should be provided to the SAML IdP
## when authenticating the user. This information defines how the SAML IdP
## should send identity assertions back to the Guacamole server if their
## identity is confirmed.
##
## THIS PROPERTY IS REQUIRED if the SAML extension will be used. It is not
## otherwise possible for Guacamole to know its own public-facing URL,
## particularly in a production deployment that is expected to use SSL
## termination.
##

saml-callback-url: https://demo3.lurey.com

The 4th section contains optional parameters that can be set.

##
## [SAML-4] Request/response compression
##
## Whether compression should be used for requests sent to the SAML IdP, and
## whether compression should be requested for responses from the SAML IdP.
## By default, compression will be used for both requests and responses.
##

#saml-compress-request: true
#saml-compress-response: true

Completing installation

Guacamole will generally only load new extensions and reread guacamole.properties during the startup process. To apply the configuration changes, Guacamole must be restarted:

$ sudo systemctl restart guacamole

KCM Final Setup

Once you have activated the SAML module, there will be a new "Sign in with SAML" link on the login screen of the application as seen below:

When setting up your user identities in the Settings area, if you would like a user to login with SAML / SSO, just leave the "password" field empty.

If you would like to automatically mapping Group assignments in the identity provider to Keeper Connection Manager Groups, simply create a matching group name with the proper assignments. The name of the Group in Keeper Connection Manager needs to match this identifier exactly in order for the mapping to work.