Microsoft Active Directory Federation Services: Imprivata Web SSO Setup

Configuring Imprivata Web Access establishes trust between Imprivata as the Identity Provider (IdP) and Microsoft Active Directory Federation Services (AD FS) as the Service Provider (SP).

Imprivata Web SSO with SAML extends Single Sign-On functionality to SAML applications. Imprivata Web SSO uses SAML 2.0 federation standards.

Imprivata Web SSO provides single sign on and secure multi-factor authentication for web applications. Imprivata Web SSO provides a SAML 2.0 Identity Provider (IdP) web service, with which the SAML 2.0-ready applications will integrate. This service in the cloud acts as a front end, with a secure bi-directional connection to your on-premises Imprivata appliances, which in turn access Active Directory. Imprivata Web SSO provides identity management, authentication, and policy enforcement to your SAML applications inside your firewall, extending the Imprivata experience when users themselves access these applications from outside the firewall.

  1. The user points her browser to the application — the Service Provider (SP).

    You have configured the application to integrate with Imprivata as the Identity Provider (IdP).

  2. The application redirects the user's browser to the IdP, sending a SAML Authentication Request.

  3. The IdP executes Imprivata's login screen.

  4. The user supplies the necessary credentials to authenticate.

    NOTE:

    When the workstation has the Imprivata agent online and the user already logged into the workstation, the user is not prompted for their credentials. See Expected Endpoint Workflows.

  5. The IdP generates a digitally signed SAML assertion, and puts it in the HTTP response to the browser, along with instructions to POST the response back to the SP.

  6. The browser POSTS the signed SAML assertion to the SP, which validates that the SAML assertion has come from a trusted source.

  7. The SP grants access to the user, logging her into the application.

CAUTION:

In an Imprivata environment where applications are federated with Imprivata Web SSO IdP, all users need to be licensed for Imprivata Web SSO. As soon as the integration between Imprivata and the web application is completed, users not licensed for Imprivata Web SSO won’t be able to access the application. Imprivata does not support manual password authentication in this environment.

NOTE:

Imprivata Web SSO only supports Service Provider-initiated interactions. Identity Provider-initiated interactions, where the user points their browser to the IdP, are not supported.

Imprivata Web SSO only supports the following SAML standard bindings:

  • SP to IdP: HTTP Redirect binding; HTTP POST binding
  • IdP to SP: HTTP POST binding

Validate SAML integration settings on the Imprivata Admin Console:

Setting Required / Optional Imprivata Admin Console location
Imprivata OneSign 7.0 or later Required Help menu
Imprivata Single Sign On is licensed Required Gear menu > License
Imprivata enterprise is provisioned and connected to the cloud Required Gear menu > Cloud connection
SAML applications are added and enabled in Imprivata Admin Console Required Applications > Single sign-on application profiles
SAML applications are deployed to selected set of users Required Applications > Single sign-on application profiles
Imprivata users are assigned to user policy enabled for Single Sign On Required Users > User policies
User policies are assigned to Remote Access workflow Optional; required for multi-factor authentication when the Imprivata agent is offline or not present Users > Workflow policy

Cloud Connection

Imprivata Services will enter the Enterprise ID and one-time cloud provisioning code required to establish trust between your Imprivata enterprise and the Imprivata cloud:

  1. If you're not on the Cloud Connection page already: In the Imprivata Admin Console, click the gear icon > Cloud connection.
  2. Services will enter your Enterprise ID and cloud provisioning code.
  3. Click Establish trust.
BEST PRACTICE:

The cloud connection must be established by Imprivata Services.

Cloud Connection Status

You can review the status of your enterprise's connection to the Imprivata cloud at any time. Status notifications are displayed on the Imprivata Admin Console, and the cloud connection status of every appliance at every site is also available:

  1. In the Imprivata Admin Console, go to the gear icon > Cloud connection.

  2. Every appliance host is listed with its status. If there are problems with a connection, recommendations for resolving the problem are displayed here.

Provide IdP Metadata to AD FS

Upload Imprivata's IdP metadata to AD FS via a URL:

  1. In the Imprivata Admin Console, go to the gear icon > Web app login configuration

  2. In the section Identity provider (IdP) metadata click View and copy Imprivata (IdP) SAML metadata.

    • Copy the Metadata URL.
    • Copy the Entity ID.

  3. In your AD FS admin console, go to AD FS > Trust Relationships > Claims Provider Trust > Add Claims Provider Trust.

    The Add Claims Provider Trust Wizard opens.

  4. Click Start.

  5. Select the option Import data about the claims provider published online or on a local network.

  6. Federation metadata address: Enter Imprivata's IdP metadata URL.

  7. Click Next.

  8. Specify the IdP Display Name when prompted.

  9. Click Next.

    The IdP metadata, SSO and SLO post and redirect URLs, and IdP certificate information are now populated in the wizard.

Edit Claims Provider Trust

  1. In your AD FS admin console, right-click your newly-created Claims Provider Trust and select Edit Claim Rules...

  2. In the Edit Claim Rules window, click Add Rule...

  3. Choose the Transform an Incoming Claim rule template.

  4. Click Next.

  5. Create a descriptive Claim Rule Name.

  6. Configure the claim rule:

    • Incoming ClaimType — Name ID
    • Incoming name ID format — Unspecified
    • Outgoing claim type — UPN

  7. Click OK.

Microsoft Office 365 as the Relying Party

Edit your Relying Party Trust to support Office 365:

  1. In your AD FS admin console, go to AD FS > Trust Relationships > Relying Party Trusts.

  2. Right-click your newly-created Relying Party Trust and select Edit Claim Rules...

  3. Select Send Claims using a custom rule.

  4. Enter the following code, with your domain value included:

    c:[Type == "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn"]

    => issue(store = "Active Directory", types = ("http://schemas.microsoft.com/LiveID/Federation/2008/05/ImmutableID"), query = "userPrincipalName={0};objectGUID;<YOUR_DOMAIN>\{1}", param = c.Value, param = c.Value);

  5. Click Finish, then OK.

Other SPs as Relying Party

Configure other SPs Relying Party Trust as follows:

  1. In your AD FS admin console, go to AD FS > Trust Relationships > Relying Party Trusts.

  2. Right-click your newly-created Relying Party Trust and select Add Claim Rule.

  3. Claim Rule Template: Transform an Incoming Claim

  4. Give the claim rule a descriptive name.

  5. Incoming claim type: UPN

  6. Outgoing claim type: NameID

  7. Outgoing name ID format: Unspecified

  8. Click Finish.

    If the SP requires additional claims (attributes), you may need to add additional claims rules. Refer to the SP's documentation to determine if other claims are required.

Prevent AD FS from Revoking Imprivata Self-Signed Certificate

By default, AD FS would revoke Imprivata's self-signed certificate. To prevent this, enter the following command into Powershell, with your Entity ID included:

Set-ADFSClaimsProviderTrust -TargetIdentifier <https://ENTITY ID HERE> -SigningCertificateRevocationCheck None

Add AD FS as SAML Application

Only the superadmin role is able to configure Web SSO application profiles:

  1. In the Imprivata Admin Console, go to Applications > Single sign-on application profiles.

    All Single sign-on application profiles, including conventional Imprivata APG profiles, Mobile app profiles, and SAML application profiles, are all managed from this page.

  2. Click Add App Profile > Web application using SAML. The Add SAML application page opens.

  3. Give the application profile a name. This name is only visible to administrators.

    Give the application a user-friendly name. This is the application name your users will see when they log in.

  4. Click Get SAML metadata.

  5. In the Get SAML Metadata window, click From URL and enter your federation metadata URL. Sample URL:

    https://adfs.YOURDOMAINNAME/FederationMetadata/2007-06/FederationMetadata.xml

  6. Click OK.

  7. Click Save SAML application.

NOTE:

The IdP certificate for your Imprivata enterprise expires two years after it is enabled. You will receive an alert on the Imprivata Admin Console beginning 60 days before it expires. When the Service Provider or Relying Party certificate is expiring for a web app enabled for Web SSO, you will receive an alert 90 days in advance.

This section describes an optional configuration for enterprises with a mix of clinical workstations that enjoy seamless access with Imprivata WebSSO, and non-clinical workstations that authenticate to the default AD FS login workflow. Expected behavior:

  • Clinical Workstations with the Imprivata Agent — typical Imprivata WebSSO authentication, as described in Expected Endpoint Workflows.

  • Other Workstations without the Imprivata Agent — user is directed to AD FS default authentication page.

    In this second scenario, the user must not be directed to the Imprivata-powered graphical login screen. In the typical Imprivata WebSSO configuration, the user will still be directed to the Imprivata-powered graphical login screen even when the Imprivata agent is offline, because WebSSO is configured at the SP, not at the Imprivata agent.

CAUTION:

WebSSO for clinical workstations requires the Imprivata agent 7.1 or later at all clinical workstations.

Add AD FS Login Pages To Allowlist

When your AD FS login page opens, the script that you are creating (in the next section) must be allowed to discover the Imprivata agent on the endpoint computer and its status. Add your AD FS login page(s) to this allowlist:

  1. In the Imprivata Admin Console, go to the gear icon > Settings > Imprivata agent discovery

  2. Provide URLs allowed to communicate with Imprivata agents. Each URL on a separate line. Wildcards allowed. Syntax examples with and without wildcards:

    • https://adfsportal.samplecompany.com/adfs/login.html
    • *samplecompany.com/adfs/login.html
    • http://*.samplecompany.com*

  3. Click Save.

Prepare Custom AD FS Web Theme

If you are currently using the default AD FS web theme, create a new one.

  1. Open the PowerShell console on your AD FS server.

  2. If you are already using a customized AD FS web theme, skip this step. If you are using the default theme, enter the following command where newtheme is the name of the theme you're creating:

    New-AdfsWebTheme –Name newtheme –SourceName default

  3. Export the AD FS web theme to a folder on your workstation where you can edit it.

    This command will export all default theme sources to a folder called c:\theme:

    Export-AdfsWebTheme –Name default –DirectoryPath c:\theme

Edit onload.js

In the c:\theme folder, open and edit the onload.js file beginning with "use strict".

The code you're adding executes on every AD FS page, HRD, and actual User Login page.

Code Template

// Copyright (c) Microsoft Corporation. All rights reserved.

// This file contains several workarounds on inconsistent browser

// behaviors that administrators may customize.

"use strict";

// SSO ready request error callback

function on_sso_ready_error() {

//!!!Modify line below according to AD FS Relying Party configuration

HRD.selection('ActiveDirectory_Relying_Party_ID'); }

// SSO ready request success callback

// Parameters:

// agent_type: 0 - Unknown, 1 - Single user workstation,

// 2 - Shared workstation, 3 - Citrix/Terminal Server

// sso_ready: true if user authenticated and sso-licensed and server online and sso not paused, false otherwise function on_sso_ready_success( agent_type, sso_ready) {

//!!!Modify line below according to AD FS Relying Party configuration

HRD.selection('Imprivata_Relying_Party_ID');

}

// Event that idp script is ready

function on_sso_ready_script_ready( event) {

try {

// Stop calling error callback since the custom script was injected

clearTimeout( timeout_id);

// Request sso ready in extension/BHO

request_sso_ready( on_sso_ready_success, on_sso_ready_error, 5000);

} catch( e) {

}

}

// Subscribe to receive event that the custom script is injected by Extension/BHO

// For all major browsers, except IE 8 and earlier

var timeout_id;

if (document.addEventListener) {

if (typeof HRD !== "undefined") {

document.addEventListener( "on_sso_ready_script_ready", on_sso_ready_script_ready);

timeout_id = setTimeout( on_sso_ready_error, 5000);

}

}

Apply Updated Theme

Upload your new onload.js file to the custom theme. Note the name of your theme is newtheme in this code:

Set-AdfsWebTheme -TargetName newtheme -AdditionalFileResource @{Uri='/adfs/portal/script/onload.js';path="c:\theme\script\onload.js"}

Apply the Custom Theme

If you were not using a custom theme before, you must apply the theme:

Set-AdfsWebConfig -ActiveThemeName newtheme

User Management

Consider how your SP manages its users: To successfully authenticate, the user information managed by your SP (SAML NameID, username, password, and so on) and the user data synchronized by Imprivata (the IdP) from your Active Directory (AD) must match. In the Imprivata Needs section, set the NameID format preference and User Attributes as needed:

  • AD Sync — If your SP syncs its user data with the same AD users and groups as your Imprivata IdP, then no special configuration should be needed.
  • Create Users Manually in SP — If your SP admin creates user accounts manually, they must use the same NameID format (for example User Principal Name (UPN), email address, and sAMAccountName), so the Imprivata IdP can successfully match them.
  • Automatic Account Provisioning — When the SP automatically creates an account as the user logs in for the first time. This functionality is supported in Imprivata Web SSO.

Available Attributes

  • Email address (mail)

  • First name (givenName)

  • Last name (surname)

  • Static value:

  • User domain

  • User logon name (userPrincipalName)

  • User logon name - Pre W2K (sAMAccountName)

  • User security identifier (objectSID)

  • User unique ID (objectGUID)

  • User unique ID (UUID)

Optional — Extended User Attributes

Imprivata Web SSO returns user attributes to AD FS upon successful authentication. If your AD FS enterprise requires additional extended user attributes, you can specify them in the Web SSO Service Provider page in the Imprivata Admin Console.

  1. You can find values for user attribute names in the AD FS console. Go to AD FS > Service > Claim Descriptions.

  2. Enter those values in the Imprivata Admin Console > Applications > Single-sign on application profiles, then select the AD FS profile to edit.

IT Pilot — Deploy to Select Users

Imprivata Web SSO application profiles offer flexible deployment options.

Deploy your profile to select users for testing:

  1. In the Imprivata Admin Console, go to Applications > Single sign-on application profiles, find your App Profile, and click Not Deployed.

  2. Click Deploy This Application?

  3. Un-check Deploy to All Users and Groups.

  4. Check the domain your test users are located in.

  5. Check These OUs, groups and users

  6. Specify your test users.

  7. Click Save.

  8. On the list of application profiles, check the box next to the profile and click Deploy.

Deploy To Users and Groups

Imprivata Web SSO application profiles offer flexible deployment options.

Deploy your profile to specific OUs, users, and groups as needed:

  1. In the Imprivata Admin Console, go to Applications > Single sign-on application profiles, find your App Profile, and click Not Deployed or Not Deployed.
  2. Check Deploy This Application.
  3. You can Deploy to All Users and Groups, or uncheck this option and deploy to select OUs, users, and groups.
  4. Check the domain your users are located in.
  5. Select For All Users (in this domain) or check These OUs, groups and users
  6. Select specific OUs, groups, and users as needed.
  7. Click Save.
  8. On the list of application profiles, check the box next to the profile and click Deploy.

For complete details, see Deploying Application Profiles.

NOTE:

All Imprivata users synced to the same domain in Active Directory as the Service Provider or Relying Party users, who are licensed for Single Sign On with Imprivata, will immediately be able to log into the Web SSO app using their username and password authenticated by Imprivata Web SSO.

When the workstation has the Imprivata agent online and the user is already logged into the workstation, the user will not be prompted for their credentials.

For complete Web SSO workflow details, see Expected Endpoint Workflows.

Expected Endpoint Workflows

The expected Imprivata Web SSO workflow has the following variations:

Imprivata Agent Online

  1. The user logs into desktop with Imprivata OneSign.

  2. The user provides the URL for an app enabled for Imprivata Web SSO.

  3. The app opens. The user does not need to log into it manually.

    Subsequent apps are automatically authenticated within the same browser and the same session.

    If the user closes an app without logging out of the app, he can return to the app during the same session without logging in again.

Imprivata Agent Not Present or Unavailable

  1. The user provides the URL for an app enabled for Imprivata Web SSO.

  2. The user is prompted to log in:

    • If the enterprise does not have an Imprivata Confirm ID Remote Access license, he will be prompted to authenticate with username and password.
    • If the user is included in a user policy associated with the Imprivata Confirm ID Remote Access Log In workflow, he will be prompted to complete the Log In workflow.
    • If the user is not included in a user policy associated with the Imprivata Confirm ID Remote Access Log In workflow, he will be prompted to authenticate with username and password.

  3. The app opens.

    Subsequent apps are automatically authenticated within the same browser and the same session.

    If the user closes an app without logging out of the app, he can return to the app during the same session without logging in again.

Imprivata Web SSO on an Unsupported Browser

The expected Imprivata Web SSO workflow on an unsupported browser is the same as when the Imprivata agent is not present or unavailable:

  1. The user provides the URL for an app enabled for Imprivata Web SSO.

  2. The user is prompted to log in:

    • If the enterprise does not have an Imprivata Confirm ID Remote Access license, he will be prompted to authenticate with username and password.
    • If the user is included in a user policy associated with the Imprivata Confirm ID Remote Access Log In workflow, he will be prompted to complete the Log In workflow.
    • If the user is not included in a user policy associated with the Imprivata Confirm ID Remote Access Log In workflow, he will be prompted to authenticate with username and password.

  3. The app opens.

    Subsequent apps are automatically authenticated within the same browser and the same session.

    If the user closes an app without logging out of the app, he can return to the app during the same session without logging in again.

For complete details on supported browsers, see Imprivata OneSign Supported Components

When Another User Logs In

When a subsequent user logs into a workstation, the Imprivata agent terminates the IdP session of the previous user.

Imprivata Web SSO cannot terminate user sessions:

  • In browsers other than Microsoft Edge or Google Chrome;
  • On workstations where the Imprivata agent is not present or unavailable;
  • For applications not enabled for Imprivata Web SSO;
  • For SAML applications that track the SP session with a persistent cookie.
CAUTION:

In an Imprivata environment where applications are federated with Imprivata Web SSO IdP, all users need to be licensed for Imprivata Web SSO. As soon as the integration between Imprivata and the web application is completed, users not licensed for Imprivata Web SSO won’t be able to access the application. Imprivata does not support manual password authentication in this environment.

BEST PRACTICE:

Implement Single Log Out for your Web SSO-enabled applications (where supported);

Turn off persistent cookies for Relying Parties; this prevents a user from accessing another user's session after a Fast User Switch.

Manually log out of applications where Imprivata Web SSO cannot terminate the user session;

Close browser windows.

Optional — Number Matching

Multi-factor authentication fatigue attacks, also known as "MFA bombing", are a common cyberattack strategy. In an MFA fatigue attack, the attacker sends MFA push notifications to a registered user. The user may accidentally or absent-mindedly accept one of these push notifications, giving the attacker access to protected resources. This type of attack is generally preceded by phishing of the registered user’s login credentials.

With Imprivata’s Number Matching authentication enabled, users must enter a 2-digit code into Imprivata ID that matches the randomly generated number displayed on the application being accessed. This reduces the risk of the user accepting a push notification they did not initiate, and keeps your digital assets out of the hands of bad actors.

NOTE:

In the Imprivata Confirm ID Legacy Remote Access experience, users will not receive a push notification. They must manually enter the Imprivata ID token code from their mobile device. In this environment, Imprivata does not control the user interface, so Imprivata cannot provide same workflow used in Imprivata's Remote Access Cloud implementation.

Setup

  1. In the Imprivata Admin Console, go to Users > Workflow Policy.

  2. On the Confirm ID workflow policy page > Authentication Options, select Require Web SSO and remote access users to enter a code when using Imprivata ID for MFA (number matching)

NOTE:

Number Matching authentication is available for Imprivata Confirm ID Remote Access and Imprivata WebSSO only. Number Matching authentication is not available for the feature Imprivata ID for Windows Access.

This feature does not add Imprivata ID push notifications with number matching to workflows that do not already require the user to accept push notifications. This feature only requires users to enter a 2-digit code within workflows that already require the user to accept Imprivata ID push notifications. See Expected Workflow, below.

Expected Workflow

In this example, the user is at an endpoint computer where the Imprivata Agent is not present, and/or they are completing WebSSO or Remote Access workflows that require the user to accept an Imprivata ID push notification:

  1. The user is logging in remotely, or provides the URL for an app enabled for Imprivata Web SSO.

  2. The user is prompted to enter their username and password.

  3. After the user successfully enters their username and password, they are prompted to approve a push notification sent to their enrolled Imprivata ID. A two-digit code will be shown on the application or resource being accessed.

  4. Imprivata ID will display the username and the application the user is accessing.

    The code expires in 30 seconds.

  5. After the user accepts the push notification, they are given access to the application/resource.

    When authenticating to some sites, the user may need to manually enter the six-digit Token Code from Imprivata ID app.

    For WebSSO, subsequent apps are automatically authenticated within the same browser and the same session.

    If the user closes an app without logging out of the app, he can return to the app during the same session without logging in again.

    If the user fails to enter the code correctly, or the code expires, the user must begin authentication again.

CAUTION:

For this workflow, users must upgrade to the latest version of Imprivata ID on their mobile device. Users with versions of Imprivata ID before 2023.2 (iOS) or 2023.1 (Android) will not have the option to simply accept a push notification; they must manually enter the six-digit Token Code to authenticate to all sites.

Optional — Web Login Customization

Configure the appearance of the web login application screens with the logo and color of your enterprise, and set a custom session log out value:

  1. In the Imprivata Admin Console, go to the gear icon > Web app login configuration

    • Select a background color for the login screen (hexidecimal value);
    • Upload a PNG, GIF, or JPG logo (200 x 150 pixels, 250 KB max)
  2. User sessions are logged out after 2 hours by default. Turn off this automatic logout, or select a value between 30 minutes and 4 days.
  3. Click Save.

Optional — Specify The Returned Attribute

When required by the SP, you can specify the returned attribute the IdP sends to the SP when the SP NameID format preference is unspecified.

In the Service Provider (SP) metadata section, when the NameID format preference field is set to Unspecified,

you can set the Returned Attribute field to:

  • Email address (mail)
  • User logon name (userPrincipalName)
  • User logon name - Pre W2K (sAMAccountName)
  • User security identifier (objectSID)
  • User unique ID (UUID)

Troubleshooting

Verify proper integration of Imprivata Web SSO (IdP) with the Relying Party (RP).

  • Imprivata IdP configuration (accessed through Imprivata Admin Console);

  • Relying Party SSO configuration (Relying Party administration)

  • Endpoint (device from which the user accesses the Relying Party application).

Validate endpoint configuration:

Setting Value
Endpoint is able to reach RP site Check connection to RP host
Endpoint has Internet connection and can reach IdP site Open in browser:
https://idp.cloud.imprivata.com/<...>/saml2
Browser supports/allows cookies  

Validate configuration for an endpoint with an Imprivata agent:

Setting Location/Value
Imprivata 23.2 or later agent is installed Agent icon in Windows system tray
Imprivata agent is connected and logged in Agent icon in Windows system tray
Single Sign On is enabled Agent icon in Windows system tray
User uses supported browser Google Chrome and Microsoft Edge
Imprivata browser extension is enabled Google Chrome and Microsoft Edge

Replacing Expiring Certificates

NOTE:

The IdP certificate for your Imprivata enterprise expires two years after it is enabled. You will receive an alert on the Imprivata Admin Console beginning 60 days before it expires. When the Service Provider or Relying Party certificate is expiring for a web app enabled for Web SSO, you will receive an alert 90 days in advance.