Configure SAML

Created: Modified: Documentation

Imprivata GroundControl can be configured to use SAML to provision and authenticate users against your Identity Provider, such as Microsoft Entra ID (formerly Azure AD).

GroundControl takes the role of a Service Provider (SP) and you provide a system to serve as Identity Provider (IdP). No credentials are exchanged during the setup process. Instead, a trusted relationship is established between the two services.

Overview

This authentication works to the GroundControl admin console and to the Launchpad app. SAML keeps passwords internal to your network, making GroundControl more secure. At the same time SAML leverages single-sign on, providing a better login experience for users.

Microsoft Entra ID is used only for user authentication. Authorization — assigning users to GroundControl roles — is still handled within the GroundControl admin console.

When the user launches GroundControl from their IdP, like for example myapps.microsoft.com (Microsoft Entra ID), then the user will be generated at that time in GroundControl with the default role defined in the Admin settings.

There is only one default role for accounts automatically created this way, but a user’s role can be modified manually after the user is created. Manually add new users and assign them to a role using the Team page. If a user has no role, they will see an error when attempting to log in with SAML.

User Invitations

Imprivata GroundControl handles new user creation differently for SAML–enabled organizations. The differences are visible in Admin > Team.

  • The Reset Password button is greyed out, because passwords are managed by your identity provider.
  • The New user process does not send an email to the new user.

You are responsible for letting new users know how to log into their GroundControl account.

IdP and SP Metadata

GroundControl (as the SP) and your Identity Provider (the IdP) need metadata from each other. Open both consoles at the same time and import the metadata. The most common method of providing IdP metadata to an SP is via an XML file. GroundControl can also accept a URL where IdP metadata can be retrieved, and also specifying the metadata values manually.

  1. In the GroundControl admin console, navigate to Admin > SAML.
  2. Switch the SAML Single Sign-on setting to ON. The Configure SAML Single Sign-on dialog opens.
  3. In Identity Provider Display Name box, type a user-friendly display name for the Identity Provider (IdP).
    1. In the Provide GroundControl Metadata XML to your Identity Provider section, copy the file to your workstation.
  4. In your IdP’s admin console:
    1. Export the IdP metadata XML file to your workstation.
    2. Upload the GroundControl metadata file saved from step 3. Alternately, enter the GroundControl URL and metadata values manually and save the configuration.
    3. If required, copy the IdP’s metadata URL and/or metadata XML contents for use in GroundControl.
  5. In the GroundControl dialog, upload the IdP metadata XML or paste the metadata URL or XML contents:
    • To upload the metadata XML file exported from the IdP, click Upload XML file and browse to the location. Click Upload. The metadata XML file is uploaded to GroundControl.
    • To use a metadata URL from the IdP, click Paste Metadata URL and paste the URL.
    • To use the contents of the XML from the IdP, click Paste XML contents and paste the contents of the IdP’s metadata XML.
  6. Click Save.
GroundControl – Configure Additional SAML Settings

In the GroundControl admin console, configure additional SAML settings:

  1. To set up automatic user creation, where new users are automatically assigned a role, switch the Auto-create user after SAML authentication to ON.
    1. Select the default role to be assigned for automatically created users.
  2. To require SAML for the GroundControl admin console, switch the Require SAML for GroundControl admin console to ON. SAML can be mandatory for the GroundControl admin console or you can allow traditional usernames and passwords alongside SAML. Typically, customers keep SAML optional during testing, then switch to mandatory for production use.
  3. To require SAML for Launchpads, switch the Require SAML for Launchpads to ON. Many customers continue using username/password for Launchpads, even when the GroundControl admin console uses SAML, because Launchpads configured for SAML prompt for user/password every time the app launches. This interrupts automatic start. On the other hand, Launchpad configured without SAML downloads a token and launch without a prompt.
  4. In the Maximum authentication lifetime (in hours) box, type a value between 1 and 168 to specify the amount of time (in hours) users have before they have to reauthenticate.
SAML Certificate

Organizations can use the default GroundControl SAML certificate. To make refreshing this certificate easier, you can set an organization-specific certificate.

Create a Certificate

Creating a certificate generates a new service provider automatically; by default it will be inactive. You must copy the GroundControl metadata XML into your Identity Provider (IdP) before activating the new certificate.

Activating a new certificate deactivates the currently active certificate. Only one certificate may be active at a time.

  1. Click Create Certificate.
  2. In the Active column, click the Active button for the certificate you wish to activate. The Make Certificate Active? dialog opens.
  3. Click the URL to copy the GroundControl metadata XML for use in your IdP before activating the new certificate.
  4. In your IdP admin console, update the GroundControl metadata XML and save.
  5. In GroundControl, click Make Active to activate the certificate.
Delete a Certificate

In the SAML Certificate list, click the delete icon next to an inactive certificate and confirm the deletion.

Certificate Expiration

Beginning 60 days before the SAML certificate expires, the GroundControl Admin Console displays an alert warning of the expiration. The banner is only displayed when the active SAML certificate is expiring.