IBM® Domino® 9.0 Social Edition provides support for federated-identity authentication using the SAML protocol.

Note Part of a complete SAML-based solution for Domino requires working in other environments. This wiki article is meant to supplement the information on SAML in the IBM Domino 9.0 Social Edition Administrator Help. For basic information, see the following two Help topics:

Using Security Assertion Markup Language (SAML) to configure federated-identity authentication

Choosing a federation to configure as your identity provider (IdP)

---

This cookbook describes a specific configuration for a Windows Active Directory Federation Services (ADFS) server, and an IBM Notes® or browser client user who is set up for integrated Windows authentication (IWA) using SPNEGO and Kerberos, to take advantage of SAML authentication.

Note IWA is not necessary for SAML configuration, but the experience improves when both are used together.

The following need to be in the same Windows Active Directory domain (unless Active Directory trust relationships have been put into place):

• ADFS server
• Client computer where the user is logging into Windows and running the browser or Notes client
• The record for the user who is being authenticated via IWA

Note The Domino server that processes the SAML assertion from the ADFS does not need to be in the Active Directory.

Details of the test computers:

• ADFS server adfs01.us.renovations.com

Windows 2008 EE 32 bit (clean OS installation)

• Windows client computer client1.us.renovations.com
• User's Windows login ID: us\tuser

Setting up the ADFS server

Install ADFS

• On the Windows computer, download and install ADFS 2.0. Federation Server role. This will install all pre-requisites.

Create a certificate for Internet Information Services (IIS)

For an IdP with HTTPS enabled, either a CA-signed or self-signed certificate is supported. If you will deploy Notes federated login, the certificate keyUsage field may need to be set to "keyCertSign" and "cRLSign," as discussed in detail below.

Create a self-signed certificate for Internet Information Services (IIS)
Optionally you can use a self-signed certificate for your HTTPS DNS name. However if you are configuring Notes federated login, you cannot use the IIS manager to create the certificate because the keyUsage field of a certificate created using the IIS manager is not accepted by Domino, and the certificate cannot be cross-certified with Domino. Instead, create a self-signed certificate using OpenSSL.

Note This procedure for creating the certificate using OpenSSL was tested with "Win32 OpenSSL v1.0.1c" on Windows XP Service Pack 3.

Procedure

1. Download OpenSSL from OpenSSL official website and install it. The web site is:
   http://www.openssl.org/support/faq.html#MISC4
2. Restart the computer to make sure the OpenSSL system variable is enabled.
   Tip Type set in the command line to verify that you can find OPENSSL_CONF. If you see a warning from OpenSSL that the configuration file cannot be found, repeat the step.
3. In the bin folder of the OpenSSL installation directory, edit the file openssl.cfg, and the remove the # character from the following item so that it reads:
   keyUsage = cRLSign, keyCertSign
4. Still In the bin folder of the OpenSSL installation directory, run openssl.exe.
5. Create and self-sign a certificate request. This step includes proving information to identify the subject in the certificate, such as country, city, and email. Use the same file name for the options -keyout and -out., for example:
   openssl req -x509 -nodes -days 3650 -newkey rsa:1024 -keyout adfs01.pem -out adfs01.pem -config openssl.cfg -extensions v3_ca
6. Export the certificate with both private key and public key in the same file. The .pfx format is required by IIS. You must also set an export password. For example:
   openssl pkcs12 -export -out adfs01.pfx -in adfs01.pem -name "adfs01"
   Note This export password is the same password you will use in IIS to import the certificate.

Import the certificate into IIS and use it as the HTTPS server certificate

Procedure

1. From the Control Panel > Administrative Tools, locate the IIS manager.
2. Open the Internet Information Services (IIS) Manager console.
3. On the Start menu, click All Programs, point to Administrative Tools, and then click Internet Information Services (IIS) Manager.
4. In the console tree, click the root node that contains the name of the computer, and then, in the details pane, double-click the icon named Server Certificates in the IIS grouping.
5. In the Actions pane, click Import.
6. Navigate to the .pfx file, which you may have created in the previous procedure, and enter the password you set.
7. On the Specify Friendly Name page, enter a name such as adfs01, and click OK.
8. In the console tree, click Default Web Site.
9. In the Actions pane, click Bindings.
10. In the Site Bindings dialog box, click Add.
11. In the Add Site Binding dialog box, select https in the Type drop-down list, select the adfs01 certificate in the SSL certificate drop-down list, click OK, and then click Close.
12. Close the Internet Information Services (IIS) Manager console.

Run the ADFS Server configuration wizard
Procedure

• Follow the steps of the ADFS Server configuration wizard and make these selections:

1. Create a new federation Service
2. Select stand-alone server
3. Select the certificate that you created for your DNS name

Create the ADFS Kerberos identity

The Windows administrator logged into the Windows domain (for example, on the Windows domain controller) creates the ADFS Kerberos identity.

The ADFS HTTP service must have a Kerberos identity called a service principal name (SPN), in the following format:

HTTP/DNS_name_of_ADFS_server

This name must be mapped to the Active Directory user that represents the ADFS HTTP server instance.

Use the Windows setspn utility, which should be available by default on a Windows 2008 server.

Procedure

1. Register the service principal names for the ADFS server. On the Active Directory domain controller, run the setspn command.
   
   For example, when the ADFS host is adfs01.us.renovations.com, and the Active Directory domain is US.RENOVATIONS.COM, the command is:
   
   setspn -a HTTP/adfs01.us.renovations.com adfs01$
   
   setspn -a HTTP/adfs01 adfs01$
   
   Note The last value has a dollar sign ($) character at the end. The name with the dollar sign ($) represents the local service account.
   
   Required adfs01 must be listed as a computer known within the US.RENOVATIONS.COM Active Directory.
   
   The "HTTP/" portion of the SPN applies, even though the ADFS server is typically accessed by SSL (HTTPS).


2. Check that the service principal names for the ADFS server are properly created, using the setspn command and viewing the output.
   
   setspn -L adfs01$

Result
If you are viewing the Active Directory using an LDAP browser, look for the computer called "ADFS01." The name of the computer's account is adfs01$. The LDAP account record contains the service principal names.






For more general information on setspn, see the following IBM Domino 9.0 Social Edition Administrator Help:

Assigning SPNs using the setspn utility

Setting up the ADFS partnership

Follow the instructions in the article Cookbook: Setting up new Relying Party Trust for AD FS 2.0, also on this wiki.

Setting up the Active Directory for the Windows client

In this scenario, the client computer client1.us.renovations.com has a computer record in the Active Directory (as shown in an LDAP browser):




The user tuser who is logging in to Windows is also in Active Directory (see sAMAccountName, as shown in an LDAP browser). The user's expected Kerberos name is in the userPrincipalNameattribute. The user's email is in the mailattribute; this is the email address which ADFS will put into the user's SAML assertion.



Setting up the Directory for the Windows user

The SAML assertion should contain the user's email address. The Domino server should be able to map the user's email address to a Domino distinguished name.

Procedure
Do one of the following:

• Make sure the user has a Person document in the Domino Directory, and that the Person document contains the user's email address in the InternetAddress field.
• Set up Domino to use Directory Assistance to Active Directory, and populate the user's Domino distinguished name in an attribute such as altSecurityIdentities. Ensure that the mail attribute contains the user's email address.

Setting up the browser for the Windows client test user

On the client computer, the user's browser needs to be set up so that the browser is configured to use the IWA (SPNEGO/Kerberos protocol) with the ADFS IdP.

Most current browsers support IWA (SPNEGO/Kerberos protocol). The screenshots below are for Internet Explorer, to use IWA (SPNEGO/Kerberos protocol) with the ADFS server when accessed in an intranet.

• For your test Notes user, make all the following changes under Internet Options:

Special considerations for particular browsers


The Extended Protection authentication setting on Windows is used to configure Kerberos mutual authentication. In this type of authentication, to prevent a "man-in-the-middle" attack, the server authenticates to the client and the client authenticates the server.

However, some browsers, for example Firefox on Windows 7, do not support Kerberos mutual authentication. If you are setting up SPNEGO/Kerberos (IWA) authentication at ADFS, the Extended Protection setting must be turned off for users who have incompatible browsers.

Restriction: Notes federated login works in conjunction with the SAML IdP. If the IdP is configured to authenticate the user by IWA (SPNEGO/Kerberos), Notes federated login requires that the IdP platform configuration turns off Kerberos mutual authentication, so that Notes federated login can succeed on certain end-user Windows platforms, for example Windows 7.

It is always recommended to deploy SSL to secure the channel from browser to server, especially if the browser does not support mutual authentication. Using SSL with the HTTP protocol requires that the server’s SSL certificate is valid and trusted by the client; this is another method of preventing a "man-in-the-middle" attack.

The Extended Protection authentication setting is in the IIS configuration under adfs->ls->authentication->Windows Authentication->Advanced Settings.

For IIS 7.5, the Extended Protection authentication setting is in the IIS configuration under adfs->ls->authentication->Windows Authentication->Advanced Settings.

Note If you are running another IIS version, consult its documentation for information on the Extended Protection authentication setting.



For more information, see the following IBM Domino 9.0 Social Edition Administrator Help topic:

Configuring Web client browsers for Windows single sign-on


Additional procedures if deploying Notes federated login

IBM technote #1627799 discusses procedures to set up trust for the IdP's HTTPS certificate by creating a cross certificate. You must create a cross certificate if the HTTPS certificate is self-signed. For a CA-signed certificate, you must create a cross certificate only in the case that the Notes embedded browser does not already trust the particular CA. For further information, see the procedure entitled Certificate details for an identity provider (IdP) configured for Notes federated login.

When enabling the Notes federated login feature, you must set up the partnership document to contain information about the ADFS server. There are a number of steps to create this partnership using the IdP catalog (idpcat.nsf), described in the IBM Domino 9.0 Social Edition Administrator Help. Note in particular in the idpcat document on the Client Settings tab, you must ensure that the setting "Enable Windows single sign-on" is enabled. This field in the idpcat document is required by Notes client so that it knows how to set up the embedded browser to participate in IWA.