IBM Verify

Abstract

This documentation provides instructions to configure a basic identity federation deployment between Microsoft® Active Directory® Federation Services 3.0 (AD FS 3.0) and IBM Security Verify Access by using the SAML 2.0 protocol, specifically the Web Browser SSO Profile and HTTP POST binding. 

Terminology Used in this Guide

Throughout this document, there are references to federation concepts that are called by different terms in the AD FS 3.0 and Verify Access SAML 2.0 documentation. The following table provides parallels between the two concepts:

In this deployment, you have option of configuring either one or both of the following scenarios: 

• Configure AD FS 3.0 as the Claims Provider and Verify Access as the Relying Party
• Verify Access as claims/identity provider and AD FS 3.0 as relying party/service provider

 Prerequisites

This configuration requires two computers for the following purposes:

• One to host AD FS 3.0
• One to host Verify Access

This document assumes that these two environments already exists.

ADFS 3.0

The test deployment created in the AD FS 3.0 Federation is used as the starting point. See Active Directory Federation Services for the installation and deployment guides. That lab uses a single Windows Server® 2012 R2 instance (fsweb.contoso.com) to host both the AD FS 3.0 federation server and a Windows Identity Foundation (WIF) sample application. It presumes the availability of a “Contoso.com” domain in which fsweb.contoso.com is a member server. The same computer can act as the domain controller and federation server in test deployments. 

Verify Access

The Verify Access environment is hosted by a fictitious company called Example.com. It is configured based on the procedures described below. Installation and deployment guides for Verify Access are available at IBM Security Verify Access Knowledge Center. 

Windows Environment

• Host operating system:
• Hostname: contoso.com 

Verify Access Environment

• Product version: IBM Security Verify Access v10.0.0

Preconfiguration Tasks

Ensure that you have performed the following configuration steps to prepare the environment for Federation testing.

Ensure IP Connectivity

Ensure that the Verify Access (isam.example.com) and AD FS 3.0 (fsweb.contoso.com) computers have IP connectivity between them. The Contoso.com domain controller, if running on a separate computer, does not require IP connectivity to the TFIM system.

 Configure Name Resolution

In this lab, we are using the hosts file on the AD FS 3.0 computer (fsweb.contoso.com) to configure name resolution of the partner federation servers and sample applications.

1. Locate the hosts file on the AD FS 3.0 computer (contoso.com), and open with Notepad. The default location is C:\windows\system32\drivers\etc\hosts.
2. Add an entry for example.com. For example, 192.168.1.3 isam.example.com.
3. Save and close the file.

Verify Clock Synchronization

Federation events typically have a short Time to Live (TTL). Ensure that both computers have their clocks synchronized, to avoid errors based on time-outs. 

Enable SSL Server Authentication

Federation relies heavily on public key infrastructure (PKI), including Secure Sockets Layer (SSL) encryption, for trustworthy transactions. To properly use SSL security in this lab,  a new self-signed certificate for the WebSEAL server at tfim.example.com must be created. Then add the self-signed certificate being used by WebSEAL into the Trusted Roots store of the AD FS 3.0 computer (fsweb.contoso.com). This allows Internet Explorer to trust the web server during HTTPS communications.

Creating a New Self-signed SSL Certificate for WebSEAL

1. From the Appliance Dashboard, click System Settings > Secure Settings > SSL Certificates.
2. Select pdsrv and click Manage > Edit SSL Certificate Database.
3. Navigate to the Personal Certificates
4. Click New and complete the following fields:
   1. Provide the certificate label as adfsinterop.
   2. Specify cn=isam.example.com as the Certificate Distinguished Name.
   3. Specify signature algorithm as SHA256withRSA.
   4. Specify keysize as 2048.
   5. Leave the expiration time as default.
   6. Check the Default
   7. Click Save. 

Modifying WebSEAL to a New Self Signed Certificate

Note: Modify the certificate settings if you have not previously check the default box in Step 3F.

1. From the Appliance Dashboard, click Web > Manage > Reverse Proxy.
2. Select the reverse proxy instance. For example, default.
3. Click Edit.
4. Go to the SSL tab and update the SSL Server certificate to use adfsinterop.
5. Click Save.
6. Deploy the changes and restart the reverse proxy instance. 

Installing the WebSEAL SSL Certificate on the AD FS 3.0 Computer

1. From the AD FS 3.0 computer (contoso.com), use Internet Explorer to navigate to https://isam.example.com.
2. At the security warning, click the link to continue to the website. The address bar turns red to signify that the page is protected by an SSL certificate that is not trusted.
3. Click the Certificate Error message next to the Internet Explorer address bar.
4. Click View Certificates.
5. In the Certificate window and on the General tab, click Install Certificate to start to the Certificate Import Wizard.
6. Click Next.
7. In the Certificate Store window, click the radio button to place all certificates in the following store.
8. Click Browse and click Show Physical Stores.
9. Select Registry in the Trusted Root Certificate Authorities folder and click OK.
10. Click Next > Finish > OK > OK.
11. Close and reopen Internet Explorer.
12. Navigate to https://isam.example.com. This time the address bar should remain white, signifying a working SSL channel.

Adding data in the Administrator account in the Contoso Active Directory

1. Log in to the Contoso domain controller computer as CONTOSO\administrator.
2. Click Start > Administrative Tools > Active Directory Users and Computers.
3. In the console tree, under com, click the Users folder.
4. In the right-most pane, right-click Administrator and select Properties.
5. On the General tab, specify the following values:

   Name	Value
   Display Name	Joe Admin
   Email	admin@contoso.com

6. Click OK.

Creating Verify Access sample users

1. From the Appliance Dashboard, click Web > Manage > Policy Administration.
2. Log in with the sec_master.
3. From the Task List, click Users > Create User.
4. In the Create User window, specify the following values:

   Name	Value
   User Id	admin@contoso.com
   Common Name	Joe
   Surname	Admin
   Password	<insert password>
   Registry UID	cn=admin,dc=iswga

Update ADFS 3.0 Sample User account
Add data to the Contoso Administrator user account that appears in security tokens generated by AD FS 3.0 for Verify Access.

Adding data to the Administrator account in the Contoso Active Directory (see ADFS 3.0 for steps)

Prepare AD FS 3.0 Metadata File

Adding partners into TFIM begins with importing partner metadata. The AD FS 3.0 metadata file includes information on how AD FS 3.0 performs both the identity provider and service provider roles, including certificates to validate and encrypt security token data.

Preparing the AD FS 3.0 Metadata File

1. On the AD FS 3.0 computer (fsweb.contoso.com), use Internet Explorer to view https://fsweb.contoso.com/FederationMetadata/2007-06/FederationMetadata.xml.
2. Click Page, and then click Save As.
   Save the file with the name xml to a location that can be accessed by the Verify Access computer. Ensure that you remember to change the Save as type drop-down box to All Files (*.*).
3. On the Verify Access computer (example.com), right-click ADFSFederationMetadata.xml and select Open with Notepad.
4. In Notepad, on the Edit menu, click Find. In the Find what field, type signature, and then click Find Next.
5. Delete the metadata document signature section of the file (bold text below). Since we are editing the document, this signature is invalid.

   Section before editing	EntityDescriptor ID="abc123" entityID="http://FSWEB.contoso.com/adfs/services/trust" xmlns="urn:oasis:names:tc:SAML:2.0:metadata"><ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#"> SIGNATURE DATA</ds:Signature><RoleDescriptor xsi:type=...>
   Section after editing	<EntityDescriptor ID="abc123" entityID="http://FSWEB.contoso.com/adfs/services/trust" xmlns="urn:oasis:names:tc:SAML:2.0:metadata"><RoleDescriptor xsi:type=...>

In Notepad, on the Edit menu, click Find. In the Find what field, type attribute, and then click Find Next. 

6. Delete all the attribute elements in the <IDPSSODescriptor> section of the file (bold text below).

   Section before editing

   <SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://fsweb.contoso.com/adfs/ls/" /> <Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" FriendlyName="E-Mail Address" xmlns="urn:oasis:names:tc:SAML:2.0:assertion" /> - MORE ATTRIBUTES -<Attribute Name="http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" FriendlyName="Windows account name" xmlns="urn:oasis:names:tc:SAML:2.0:assertion" /> </IDPSSODescriptor>

   Section after editing

   <SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://fsweb.contoso.com/adfs/ls/" /> </IDPSSODescriptor>

Configure Verify Access as a Service Provider and ADFS 3.0 as an Identity Provider

This section describes the procedures to add a service provider federation from the Verify Access Appliance Dashboard. This enables Example.com as a Service Provider or Relying Party.

Adding an Verify Access Service Provider Federation

1. From the Appliance Dashboard, click Federation > Manage > Federations.
2. In the Federation Management page, click Add.
3. In the Federation Protocol tab, perform the following steps:
   1. Specify ISAMasSP as the Federation Name.
   2. Select SAML 2.0 as the protocol for this federation.
   3. Click Next.
4. In the Template tab, specify SAML 2.0 as the template.
5. In the General Information tab, perform the following steps:
   1. Specify com as the company name.
   2. Specify Service Provider to identify your role.
6. In the Point of Contact Server tab, specify https://isam.example.com/isam1 as the endpoint URL of the point of contact server tab.
7. In the Profile Selection window, select Web Browser Single Sign-On.
8. In the Single Sign-On Settings window, select HTTP Post as the supported binding and leave the rest of the configuration as is.
9. In the Signature Options window, perform the following steps:
   1. Specify rt_profiles_keys as the Certificate Database.
   2. Specify server as the Certificate Label.
   3. Leave the KeyInfo elements configuration as is.
10. In the Encryption Options, perform the following steps:
    1. Specify rt_profiles_keys as the Certificate Database.
    2. Specify server as the Certificate Label.
11. In the SAML Message Settings tab, leave the configuration as is.
12. In the Identity Mapping tab, select Do not perform identity mapping.
13. In the SAML Message Extension tab, select None.
14. Check your configuration in the Summary window and click OK to complete the configuration.
15. Deploy changes.

Exporting the Service Provider Federation metadata from Verify Access

1. From the Appliance Dashboard, click Federation > Manage > Federations.
2. Select ISAMasSP.
3. Click Export.

Adding an Identity Provider Partner using Metadata

1. From the Appliance Dashboard, click Federation > Manage > Federations.
2. Select the ISAMasSP service provider federation and click Partners.
3. In the Partner Wizard, click Add.
4. Browse to the AD FS metadata file.
5. Click Next and leave the default configuration as is.
6. Review the configuration in the summary page.
7. Click OK to complete the configuration.
8. Deploy changes.

Configuring WebSEAL for Service Provider Federation

1. From the Appliance Dashboard, click Web > Manage > Reverse Proxy.
2. Select a reverse proxy.
3. Click Manage > AAC and Federation configuration > Federation Management.
4. 
In the Federation Management window, click Add.

5. Click on Next.
6. 
In the Runtime tab, leave the hostname, post and username as is.
7. 
Enter the easuser user password. Click Next.
8. 
Select the federation ISAMasSP from the drop-down list and click next.
9. 
Uncheck Reuse certificates and Reuse ACLs.
10. 
Click Finish. 

Configure Verify Access Credential as Point of Contact

1. From the appliance dashboard, click Federations > Global Setting > Point of Contact.
2. Select the Verify Access Credential. Set as Current.
3. Deploy pending changes.

Configure AD FS 3.0 as Identity Provider

Add a Relying Party Using Metadata

Adding a partner into AD FS 3.0 can be done either manually or through metadata import. In this lab, we will use metadata import. 

To add an AD FS 3.0 relying party using metadata

1. On the AD FS 3.0 computer (fsweb.contoso.com), click Start > Administrative Tools > AD FS 3.0 Management to open the AD FS 3.0 Management console.
2. In the left navigation area, expand the Trust Relationships folder, then right-click the Relying Party Trusts folder and select Add Relying Party Trust… to start the Add Relying Party Trust Wizard.
3. Click Start.
4. In the Select Data Source page, select Import data about the relying party from a file.
5. In the Federation metadata file location field, click Browse.
6. Navigate to the location where you saved Federation_metadata_ISAMasSP.xml and click Open, and then click Next.
7. In the Specify Display Name page, type TFIM SP Example and click Next.
8. Click Next.
9. In the Configure Multi-Factor Authentication Now? page, leave default selection.
10. Click Next.
11. In the Choose Issuance Authorization Rules page, leave default selection.
12. Click Next.
13. In the Ready to add trust page, leave default selection.
14. Click Next and click Close.

Edit Claim Rules for Relying Party Trust

Claim rules describe how AD FS 3.0 determines what data should reside inside the federation security tokens it generates. The claim rules in this section describes how data from Active Directory is inserted into the security token created for TFIM.

The primary claim needed by TFIM is the name identifier, or Name ID, which is the assertion attribute used to map incoming federated users to TFIM’s local user store.

To edit AD FS 3.0 claim rules for a relying party trust

1. The Edit Claim Rules dialog box should already be open. If not, In the AD FS 3.0 Management center pane, under Relying Party Trusts, right-click ISAM SP Example, and then click Edit Claim Rules.
2. On the Issuance Transform Rules tab, click Add Rule.
3. In the Select Rule Template page, leave Send LDAP Attributes as Claims selected, and click Next.
4. In the Configure Claim Rule page, in the Claim rule name box, type Get attributes.
5. In the Attribute Store list, select Active Directory.
6. In the Mapping of LDAP attributes section, create the following mappings:

   LDAP Attribute	Outgoing Claim Type
   E-mail addresses	E-mail address
   Display Name	Name

7. Click Finish.
8. On the Issuance Transform Rules tab, click Add Rule.
9. In the Select Rule Template page, select Transform an Incoming Claim, and click Next.
10. In the Configure Claim Rule page, type the following values.

    Name	Value
    Claim Rule Name	Name ID transform
    Incoming Claim Type	Email address
    Outgoing Claim Type	Name ID
    Outgoing Name ID Format	Email

Leave the Pass through all claim values radio button selected and click Finish. 

11. Click OK to close the Edit Claim Rules
12. On the Issuance Transform Rules tab , click Add Rule.
13. In the Select Rule Template page, select Send Claims Using a Custom Rule.
14. Paste the following rule:
    c:[Type == "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier"] => issue(Type = "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier", Issuer = c.Issuer, OriginalIssuer = c.OriginalIssuer, Value = c.Value, ValueType = c.ValueType, Properties["http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/format"] = "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress", Properties["http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/namequalifier"] = "https://fs.hhres.com/adfs/services/trust", Properties["http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/spnamequalifier"] = "ADFSasIDP"); ​

Configure Verify Access as the Identity Provider and AD FS 3.0 as the Service Provider

Creating a mapping rule

1. From the Appliance Dashboard, click Federation > Mapping Rules.
2. Click Add.
   // SAML20 IP Mapping rule importPackage(Packages.com.tivoli.am.fim.trustserver.sts); importPackage(Packages.com.tivoli.am.fim.trustserver.sts.uuser); importPackage(Packages.com.tivoli.am.fim.trustserver.sts.utilities); IDMappingExtUtils.traceString("idp mapping rule called with stsuu: " + stsuu.toString()); // re-write Principal name with type as email nameid format var principalName = stsuu.getPrincipalName(); stsuu.clear(); // Set the NameID attribute of the SAML assertion to email address. stsuu.addPrincipalAttribute(new Attribute("name", "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress", principalName )); // example of adding a new one var testAttr = new Attribute("client","urn:client", "client"); stsuu.addAttribute(testAttr);​

3. Specify SAML20ip as the name and SAML 2_0 as the category.
4. Save and deploy the changes. 

Adding an Verify Access identity Provider Federation

1. From the Appliance Dashboard, click Federation > Manage > Federations.
2. In the Federation Management page, click Add.
3. In the Federation Protocol tab, perform the following steps:
   1. Specify ISAMasIDP as the Federation Name.
   2. Select SAML 2.0 as the protocol for this federation.
   3. Click Next.
4. In the Template tab, specify SAML 2.0 as the template.
5. In the General Information tab, perform the following steps:
   1. Specify com as the company name.
   2. Specify Identity Provider to identify your role.
6. In the Point of Contact Server tab, specify https://isam.example.com/isam2 as the endpoint URL of the point of contact server tab.
7. In the Profile Selection window, select Web Browser Single Sign-On.
8. In the Single Sign-On Settings window, select HTTP Post as the supported binding and leave the rest of the configuration as is.
9. In the Signature Options window, perform the following steps:
   1. Specify rt_profiles_keys as the Certificate Database.
   2. Specify server as the Certificate Label.
   3. Leave the KeyInfo elements configuration as is.
10. In the Encryption Options, perform the following steps:
    1. Specify rt_profiles_keys as the Certificate Database.
    2. Specify server as the Certificate Label.
11. In the SAML Message Settings tab, leave the configuration as is.
12. In the Access Policy tab, leave the configuration as is.
13. In the Identity Mapping tab, use JavaScript transformation for identity mapping.
14. Click Next.
15. Select the mapping rule that was created in the previous section “Creating a mapping rule”.
16. Click Next.
17. Save and deploy pending changes.
18. In the SAML Message Extension tab, select None.
19. Check your configuration in the Summary window and click OK to complete the configuration.
20. Deploy changes.

Configuring WebSEAL for Identity Provider Federation

1. From the Appliance Dashboard, click Web > Manage > Reverse Proxy.
2. Select a reverse proxy.
3. Click Manage > AAC and Federation configuration > Federation Management.
4. 
In the Federation Management window, click Add.

5. Click on Next.
6. 
In the Runtime tab, leave the hostname, post and username as is.
7. 
Enter the easuser user password. Click Next.
8. 
Select the federation ISAMasIDP from the drop-down list and click next.
9. 
Uncheck Reuse certificates and Reuse ACLs.
10. 
Click Finish. 

Exporting the Identity Provider Federation metadata from Verify Access

1. From the Appliance Dashboard, click Federation > Manage > Federations.
2. Select ISAMasIDP.
3. Click Export. 

Configure AD FS 3.0 as Service Provider

Add UserName Claim Description

The inbound security token from IBM Security Verify Access includes a “UserName” claim that contains the user’s Verify Access UserId. Follow the procedure below to configure AD FS 3.0 to receive this claim. 

Adding a new claim description

1. On the AD FS 3.0 computer (fsweb.contoso.com), click Start > Administrative Tools > AD FS 3.0 Management to open the AD FS 3.0 Management console.
2. In the left navigation area, expand the Service folder, then right-click the Claim Descriptions folder and select Add Claim Description.
3. In the Add a Claim Description window, specify the following values:

   Name	Value
   Display Name	UserName
   Claim Identifier	UserName

4. Click OK. 

Add a Claims Provider Using Metadata

Use the metadata import capabilities of AD FS 3.0 to create the Example.com claims provider.

Adding an AD FS 3.0 claims provider using metadata

1. In the AD FS 3.0 Management console, in the left navigation area, expand the Trust Relationships folder, then right-click the Claims Provider Trusts folder and select Add Claims Provider Trust to start the Add Claims Provider Trust Wizard.
2. Click Start.
3. In the Select Data Source page, select Import data about the claims provider from a file.
4. In the Federation metadata file location field, click Browse.
5. Navigate to the location where you saved com_metadata.xml and click Open.
6. Click Next.
7. In the Specify Display Name page, type ISAM IdP Example and click Next.
8. Click Next, and then click Close.

Edit Claim Rules for Claims Provider Trust

Claim rules describe how AD FS 3.0 determine data that resides inside the federation security tokens it generates. The following claim rules describes how inbound data from IBM Security Verify Access is prepared for use with the relying parties registered in AD FS 3.0. For example, here we transform the UserName claim sent by Verify Access into the Name claim used by all Contoso relying party applications.

Editing AD FS 3.0 claim rules for a Claims Provider Trust

1. Ensure that the Edit Claim Rules If not, in the AD FS 3.0 Management center pane, under Claims Provider Trusts, right-click ISAM IdP Example.
2. Click Edit Claim Rules.
3. On the Acceptance Transform Rules tab, click Add Rule.
4. In the Select Rule Template page, select the Pass Through or Filter an Incoming Claim box, and then click Next.
5. In the Configure Claim Rule page, specify the following values:

   Name	Value
   Claim Rule Name	Name ID Rule
   Incoming Claim Type	Name ID
   Incoming Name ID format	Email

Click Add Rule 

6. In the Select Rule Template page, select the Transform an Incoming Claim box, and then click Next.
7. In the Configure Claim Rule page, specify the following values:

   Name	Value
   Claim Rule Name	Name Transform Rule
   Incoming Claim Type	UserName
   Outgoing Claim Type	Name

Leave the Pass through all claim values option selected, and then click Finish. 

9. To acknowledge the security warning, click Yes.
10. Click OK.

Adding a Service Provider Partner using metadata

1. From the Appliance Dashboard, click Federation > Manage > Federations.
2. Select the ISAMasIDP service provider federation and click Partners.
3. In the Partner Wizard, click Add.
4. Browse to the AD FS metadata file.
5. Click Next and leave the default configuration as is.
6. Review the configuration in the summary page.
7. Click OK to complete the configuration.
8. Deploy changes. 

Change AD FS 3.0 Default Name ID format

As a Service Provider, AD FS 3.0 defaults to requesting the unspecified name identifier format (urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified) in outbound SAML authentication requests. This format requires special configuration in Verify Access. For the sake of simplicity, we change the default name identifier format AD FS 3.0 requests from Verify Access to the emailAddress name identifier format.

Changing the AD FS 3.0 default requested name identifier format

1. In the AD FS 3.0 computer, click Start > Administrative Tools > Windows PowerShell Modules.
2. At the PowerShell command prompt, type the following commands:
   set-ADFSClaimsProviderTrust -TargetName “ISAM IdP Example” -RequiredNameIdFormat urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
3. Press Enter.

Note: You can make many configuration changes to AD FS 3.0 with the Windows PowerShell command-line and scripting environment. For more information, see AD FS 2.0 Administration with Windows PowerShell and AD FS 2.0 Cmdlets in Windows PowerShell.

Enabling IdPInitiatedSignonPage

1. In PowerShell, execute the following command:
   Get-AdfsProperties
2. Check that EnableIdpInitiatedSignonPage is true.
3. If it is not set to true, execute the following command to set the property to true:
   set-AdfsProperties -EnableIdPInitiatedSignonPage $true