 |
Need a Domino Consultant? Call NotesMail +1 212-599-2048 - HCLSoftware Business Partner
SECURING
Enabling the Domino Web server to provide SAML authentication
You enable Security Assertion Markup language (SAML) authentication on 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. See the related topics.
- 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™ Active Directory (ADFS), SSL is required.
- The administrator who performs the steps in this procedure for certificate creation and metadata export must be listed (or belong to a group) in the Server document, under Full Access Administrators, Administrators, and Sign or run unrestricted methods and operations.
- The idpcat.nsf must not be enabled for document locking.
Note: If this and the previous condition are not met, the agents in the idpcat.nsf cannot be used for accomplishing the certificate creation and metadata export steps. If you want to perform these steps instead by using a sequence of commands at the Domino server console, see the related topic on creating a Domino metadata file manually.
About this task
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 (Step 9) 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
1. 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.
Important: The IdP Catalog application cannot have an arbitrary application title; you must assign the title idpcat to the application. In the file system, the application must have the file name idpcat.nsf.
CAUTION: If your server is running on UNIX™, make sure the file name is all lower-case.
2. 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.
3. Click Add IdP Config to create a new configuration document.
Note: If you have multiple Internet Site documents in your organization, and you want SAML authentication used at these multiple 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.
4. On the Basics tab, in the Host names or addresses mapped to this site field, enter either an IP address or Web address (DNS hostname, or Internet site name) representing a service provider's Web site, or both. If you enter both, separate the IP from the Web address using a semicolon, for example, n.nn.nnn.n; www.renovations.com. The order of addresses does not matter, and you can enter multiple items, separated by semicolons.
Important: The IP or Web address 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, or the Host names or addresses mapped to this site field of the corresponding Internet Site document. In this way you can specify all host name/IP combinations that should share the common identity provider partnership.
Restriction: If your organization is using SSL as recommended, you must include an IP address.
5. 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).
6. In the Protocol version field, select a SAML version.
Important: SAML 2.0 is required if your federation is configured on Microsoft ADFS.
7. Leave State for this Configuration document as Enabled (the default).
8. In the Federation product field, select either TFIM for IBM Tivoli Federated Identity Manager or ADFS for Microsoft Active Directory Federation Services, depending on which federation service you intend to use for SAML authentication. The default is ADFS.
9. In the Service provider ID field, enter the string that identifies Domino as a service provider partner with the IdP.
This string is usually the same as the HTTP URL for the Domino HTTP server, for example, https://domino1.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.
10. 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 from file. |
| Encryption X.509 certificate | Domino imports the certificate 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. |
11. On the Client Settings tab, perform all of the following substeps:
a. Leave Enable Windows single sign-on set to Yes if this IdP document corresponds to an IdP that uses Windows™ single sign-on (SPNEGO/Kerberos) user authentication. This field is required by Notes® client federated login so that Domino knows how to set up the Notes client embedded browser.
For more information, search the Notes and Domino wiki for an article on setting up ADFS for integrated Windows authentication (IWA). IBM technote #1614543 in the related topics will eventually provide links to all such articles.
b. In the Sites that are trusted field, list trusted identity provider (IdP) web host names that differ from the host name configured in the Basics tab. Separate entries with a semicolon or a return character.
c. Leave the Enforce SSL field set to Yes if the Notes client embedded browser requires that any URL accessed at the IdP during the login sequence be protected with SSL.
12. 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:
a. 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.
You might use the name to indicate the Domino server, for example Domino US Renovations, or a virtual name if representing one particular Internet site configuration on the Domino server, for example, Domino East Coast US Renovations.
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 >).
b. 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.
c. 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_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.
d. 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.
13. At the beginning of the form, click the Export XML 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.
14. Save and close the IdP Configuration document.
What to do next
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.
Parent topic: Configuring SAML in Domino
Next topic: Creating a Domino metadata file manually
Related tasks
Setting up a TFIM server as the identity provider (IdP)
Setting up Microsoft Active Directory Federated Services (ADFS) as the federation for a Domino partner
Using Domino as a SAML-based security provider with SSL
Configuring SAML from the Internet Site (Web Site) document
Creating a Domino metadata file manually
Related reference
Cautioning client users about SAML and logout
Related information
Supplementary information on Security Assertion Markup Language (SAML) configuration combinations of IBM Domino and other products
| |