Single Sign On with an External Authentication Provider

Configuration of SSO feature needs to be coordinated with the configuration of the authentication/identity provider.

The high-level tasks to configure the external authentication provider are:

1. Add the SSO Integration optional feature to the SilhouetteTokenService license.
2. Configure the SilhouetteTokenService with the authentication provider details, see SilhouetteTokenService Web Application Configuration.
3. Provide the SilhouetteTokenService connection information to the authentication provider, including:
   1. Entity ID.
   2. Assertion consumer service endpoints.
   3. Claim mapping requirements.
4. Configure the Silhouette Group to authentication provider claim mapping in SilhouetteCentral administration screens, see the Administration User's Guide.
5. Test SSO integration, see Verify Single Sign On with an External Authentication Provider.
6. Optionally disable Silhouette Local User login, see SilhouetteTokenService Web Application Configuration.

Example: Configuring Silhouette SSO Integration with AD FS

The configuration of Active Directory Federation Services (AD FS) is outside the scope of this documentation and it is recommended that you follow the AD FS configuration manuals. The example offered in these manuals are to provide some context and clarity to assist with the Silhouette configuration.

This example assumes you have the following items in place and are simply adding Silhouette as a Relying Party (RP) into AD FS:

• An AD FS server is in place with an Attribute Store and Claims Provider Trust configured.
• The AD FS Entity ID is http://adfs.anonhealth.aranz.nz/adfs/services/trust.
• The AD FS Metadata URL is https://adfs.anonhealth.aranz.nz/FederationMetadata/2007-06/FederationMetadata.xml.
• Active Directory (AD) has groups 'SILHOUETTE Vendor Support' , 'SILHOUETTE Admin', 'SILHOUETTE Clinical'.
• AD has users configured with membership in each of the above AD groups.
• The SilhouetteTokenService website is available at https://anonhealth.aranz.nz/silhouettetoken.
• The SilhouetteTokenService is already licensed with the optional feature SSO Integration.
• SilhouetteCentral has groups 'ARANZ Medical Support', 'Admin', 'Default' configured.

Configure the SilhouetteTokenService

Edit the SilhouetteTokenService appSettings.production.json file to include the following Saml2 configuration.

	The URL where the SilhouetteTokenService Saml2 metadata is available.
	Entity ID and Metadata URL of the AD FS server.

Stop and start the SilhouetteTokenService to apply the configuration.

Add Silhouette as a Relying Party Trust to the AD FS Server

Using the AD FS Management interface, select the Add Replying Party Trust action.

	SilhouetteTokenService is a Claims aware RP. Select Claims aware and press the Start button.
	If the SilhouetteTokenService metadata URL is published at a location where the AD FS system can access it then enter the metadata URL in the 'Import data about the relying party published online or on a local network' text box. Alternatively, the metadata can be imported from a file by navigating to the SilhouetteTokenService metadata URL in a web browser to retrieve the file, which can then be provided to the AD FS system. Once copied the file location can be entered in the 'Import data about the replying party from a file' text box. The information entered at this point is case sensitive. If downloading and supplying the metadata file, then use the correct case in the URL for downloading the metadata.
	Choose a display name for the RP and press the Next button.
	Select the appropriate access control policy and select the Next button.
	The next step in the wizard shows the RP configuration for review. SilhouetteTokenService EntityId is shown on the Identifiers tab and the SAML Assertion Consumer Endpoints are listed in the Endpoints tab. Select the Next button.
	If the RP configuration was successful then you can either move on to configure claims issuance policy or close the wizard.
The next step is to setup claim issuance policy to issue claims about the identity to Silhouette. Most of the data about the identity comes as a claim. An claim issuance policy for an RP can have multiple rules of different types and can have filters applied to the information shared (e.g. only issue group claims that start with Silhouette). This example a simple example of sending LDAP Attributes as Claims. To edit the claim issuance policy for an RP, select the RP and choose the Edit Claim Issuance Policy action.
	Select the Add Rule... Button.
	Select the Rule Type. This example shows sending LDAP attributes as Claims. Select the Next button.
	Give the claim rule a name. Select the Attribute Store which has been previously configured. Map LDAP attributes to outgoing claims. The left hand attributes are the LDAP attributes to read from the attribute store. The right hand column are the names of the claim types that will be sent to Silhouette. These claim types should include the Name ID and all of the ClaimTypes in the SilhouetteTokenService configuration. Only the Name of the claim is shown here. The AD FS Management console also includes a list of Claim Descriptions which includes the full description of how the Name maps to the full Claim Type (e.g. Name ID = http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier) Once completed, select Finish and then Apply.

Configure the Silhouette Group to Authentication Provider Claim Mapping

When all the above AD FS configuration done successfully, there is a Login with ADFS button on the Silhouette login page. Using that button shows the ADFS login page and users can login with their anonhealth.aranz.nz ID. However, when they do login all they see is a webpage that reports Access Denied until they are part of a AD group that is sent to a claim in AD FS, which is in turn then mapped to a Silhouette Group.

To map an authentication provider claim to a Silhouette Group:

1. Login to SilhouetteCentral as a Local Silhouette User with Can Manage Users and Groups permission (e.g. the default admin account).
2. Navigate to Admin > Groups and select the Group you wish to apply mapping to.
3. Select Edit, add the Authentication Provider Claim mapping for the appropriate Authentication Provider by inserting the exact string you expect to receive in the group claim value and Save.
4. Repeat for each Silhouette Group, mapping the appropriate claim to the group.
5. Once complete, you can logout and then attempt to login through the Login with ADFS button on the login page and you will be granted access to the system according to your group membership.
6. Use the procedure in Verify Single Sign On with an External Authentication Provider to check the mappings and access.

An example of the claim SILHOUETTE Admin from the ADFS Authentication Provider mapped to the Silhouette Group called Admin.

Disable Silhouette Local User Login

Once SSO integration is complete and you have all user accounts (include ARANZ Medical support and system admin) accounts managed in the external directory, you can disable Silhouette Local User login, see SilhouetteTokenService Web Application Configuration.

Once Silhouette Local User login is disabled, the Silhouette login page is skipped and users will only see the external login provider page.

Use the test listed in Verify Single Sign On with an External Authentication Provider to verify Silhouette Local User login is disabled.

If the external authentication provider becomes unavailable or the integration fails at some point, then a privileged user can enable the Silhouette Local User login again to provide emergency access to the system.