Enabling the Domino Web server that runs iNotes to provide SAML authentication

You enable Security Assertion Markup language (SAML) authentication on IBM® Domino® using the IdP Catalog application. If the Domino server is password-protected, there may be additional tasks.

Before you begin

The identity provider (IdP) you intend to use with the Domino Web server must be configured before you enable SAML on the Domino Web server running IBM iNotes®. See the related topics.
You must have access to the vault ID file and password, and have Editor access to the Domino Directory.
Obtain a copy of the metadata.xml file that was exported from the identity provider (IdP), and have its contents ready for import when you create the IdP Configuration document. You can store it in any location accessible to your Domino Administrator client.
If the IdP Catalog (idpcat.nsf) application already exists, you must have access to create documents in it.
It is recommended that you use SSL security for your SAML configuration; if your federation is Microsoft Windows Active Directory (ADFS), SSL is required.
Log in as a test iNotes user to confirm that SAML authentication is enabled. To do so, open a browser and enter the URL for the Domino Web server running iNotes, for example: https://domino1.us.renovations.com.

Depending on the IdP configuration, the test user may first be redirected to the IdP's login page before iNotes mail is displayed in the browser. If SAML authentication is properly configured at the Domino server, you will see the test user's mail displayed in the browser. iNotes may prompt for a password to the Notes® ID file before allowing access to encrypted mail.

After you have verified that an iNotes user can be authenticated by SAML to start iNotes, then complete the procedure, after which the test iNotes user should no longer see a password prompt for access to encrypted mail.

About this task

The IdP Catalog application must exist on the Domino server that hosts the ID vault whether or not that is the same computer that runs iNotes. If they are on separate computers, you will create two IdP Config documents in the catalog, and replicate the IdP Catalog application to both servers. The documents are essentially identical except for the value in the Host names or addresses mapped to this site field. See the "What to do next" section.

The IdP Configuration document includes several fields whose values are supplied automatically when you import the metadata.xml file from the IdP.

Important: If the Domino server has a server.id file protected by a password, the administrator cannot use the Create Certificate button to create a metadata file. Instead, see the task in this sequence on creating the Domino metadata file if the server.id file is password-protected.

Important: If you later modify an existing SAML IdP Configuration document or add a new one, restart the HTTP process on the Domino Web server so that the changes are recognized.

Note: Enabling SAML authentication may have unexpected results with RSS feeds if your organization uses them.

Procedure

From the Domino Administrator client, create the IdP Catalog application (idpcat.nsf), using the template with the file name idpcat.ntf, or open the application if it already exists.
CAUTION:
If your server is running on UNIX, make sure the file name is all lower-case.
Assign access in the ACL only to any Domino SAML administrator(s) and to the server.
Note: If the ipdcat.nsf is replicated across other participating SAML servers, their entries will be added to the ACL.
Click Add IdP Config to create a new configuration document.
Note: If you have additional Internet Site documents in your organization, and you want SAML authentication used at these additional Web sites, create separate associated IdP Configuration documents for each participating Internet Site. For details, see the related topic on configuring SAML from the Internet Site document.
On the Basics tab, in the Host names or addresses mapped to this site field, enter a virtual name for the ID vault. It is recommended that you use a virtual DNS hostname with a differentiating string such as "vault", so that it will not be confused with a similar hostname on the network. The resulting hostname does not need to be defined in DNS.
Restriction: If your Domino Web server is using SSL, you must include an IP address after the virtual host name, separated by a semicolon.

Important: The virtual host name you enter here should match what is entered in either the Host name(s) field on the Internet Protocols/HTTP tab in the Server document (if the ID vault is on the Domino server that runs iNotes, or the Host names or addresses mapped to this site field of the corresponding Internet Site document to the ID vault server. In this way you can specify that the ID vault server should share the common identity provider partnership already established for the Domino server running iNotes.
For example, enter vault.us.renovations.com;n.nn.nnn.n.
In the IdP name field, enter a name to identify the Web site of the identity provider; the name does not have to be exact, and is only for your administrative convenience. For example, if the Renovations organization has a support site hosted by a third party who will serve as an identity provider, using the IBM Tivoli® Federated Identity Manager, the administrator might enter Renovations Customer Support (TFIM).
In the Protocol version field, select the SAML version already configured for the partnership.
Important: SAML 2.0 is required if your federation is configured on Microsoft Windows ADFS.
Leave State for this Configuration document as Enabled (the default).
In the Federation product field, select either TFIM for IBM Tivoli Federated Identity Manager or ADFS for Microsoft Windows Active Directory Federation Services, depending on which federation service you intend to use for SAML authentication. The default is ADFS.
In the Service provider ID field, enter the string that identifies Domino as a service provider partner with the IdP. This string should be the same as the HTTP URL for the Domino ID vault server, for example, https://vault.us.renovations.com.
Note: If SSL is not configured at Domino and you are using TFIM for the IdP, this setting would include http instead of https, for example: http://domino1.us.renovations.com. If you use ADFS for the IdP, SSL is required, so you would use https in the string.

Important: An entry is required in this field to use the Create Certificate button on the Certificate Management tab.

Click Import XML file, and specify the metadata.xml file exported from the IdP. It is recommended that you leave intact the information supplied from the imported XML file.

Note: If the federation is configured on ADFS, this file may have a slightly different name, for example, FederationMetadata.xml.

Table 1. Fields in the IdP Configuration document whose values are generated from the metadata.xml file
Field	Description
Artifact resolution service URL	Domino generates the artifact URL for the federation service you specified in the Product field. For example, for the Renovations organization, using TFIM, SAML 2.0, and SSL, the following artifact URL might be generated: https://tfim.renovations.com/FIM/sps/samlTAM20/soap.
Single sign-on service URL	If the data is available in the imported XML file, Domino generates the login URL for the federation service you specified in the Product field. For example, for the Renovations organization, using TFIM, SAML 2.0, and SSL, the following login URL might be generated: https://tfim.renovations.com/FIM/sps/samlTAM20/logininitial. Note: The value in this field is a subset of the expected URL to the IdP. The Domino server generates the full URL when necessary.
Signing X.509 certificate	Domino imports the certificate code from file.
Encryption X.509 certificate	Domino imports the certificate code from file. Note: This field appears only when the Type field is set to SAML 2.0.
Protocol support enumeration	Domino generates a string designating the protocol(s) for the SAML release specified in the Type field that are also supported by the specified IdP. This string will become part of authentication URLs provided by Domino as the service provider to the IdP specified in this configuration document. For example, url.oasis.names.tc:SAML:2.0:protocol.

If you are using SAML 2.0 and need to export a certificate from Domino to use at the IdP, on the Certificate Management tab, perform all of the following substeps:
1. Enter a Company name field to identify the certificate in the Domino metadata file (idp.xml) to be exported. Use any string convenient to your administrators. This string should identify the Domino ID vault server, for example, Domino RenovationsID Vault.
  Tip: The name does not have to match anything in the actual IdP configuration. However, the string does have to be compatible with the syntax of the idp.xml file; that is, it cannot include characters such as angle brackets (< or >).
2. Click Create Certificate. If prompted, save the document, return to the tab, and click the button a second time.
  When creating the certificate, Domino pre-pends "CN=" to the string in the Company name field and uses this name as the certificate subject. The name may be visible in the IdP configuration after the metadata file is imported.
3. In the Domino URL field, enter a string to identify the fully qualified DNS name in a URL of the Domino server. For example, enter:
```
https://your_iNotes_ SAML_service_provider_hostname
```
  The string in this field is used by the IdP as the initial part of the URL for sending the user's SAML assertion back to Domino.
  Note: If SSL is not configured at Domino and you are using TFIM for the IdP, this setting would include http instead of https, for example: http://domino1.us.renovations.com.
  
  Note: You can use the string you entered in the Service Provider ID field on the Basics tab.
4. In the Single logout URL field, enter a URL if the IdP requires one, for example if your federation is Tivoli Federated Identity Manager (TFIM 2.0). The TFIM IdP with SAML 2.0 configuration requires a single logout URL to be specified at the IdP and in the Domino metadata file, even though Domino does not currently implement a SAML 2.0 single logout feature. An example of a logout URL is:
```
https://your_tfim_server.com/sps/samlTAM20/saml20
```
At the top of the form, click the Export URL button to save the created idp.xml file as an attachment to the document.
Note: This button is visible only when a previously created idp.xml file is not already attached.
Save and close the IdP Configuration document.

What to do next

Unless your Domino server running iNotes and your ID vault server are on one machine, go on to create a second IdP Config document following the previous procedure. The document should be identical except that the value in theHost names or addresses mapped to this site field, instead of a virtual DNS name for the vault server, must match the value in the Server document for the Domino server running iNotes, in the Host name(s) field on the Internet Protocols/HTTP tab. For example, the Renovations company may have an entry of domino.renovations.com.

If you use Internet Site documents, follow the steps in the related topics on them, to enable SAML and to specify the preferred session cookie.

Note: If you later change the authentication type in the Internet Site document to remove SAML, your change has no effect to disable SAML unless this IdP Configuration document is either disabled or deleted.

For additional information, see the topics "Setting up a TAM TFIM server to provide SAML authentication," "Using Domino as a SAML-based security provider with SSL," "Configuring SAML in the Internet Site document" and "Setting up Active Directory federated services" in the Notes and Domino wiki.