End-to-end steps for configuring SAMLv2 with AD FS

1

Understanding how SAML 2.0 works

Security Assertion Markup Language (SAML) is an XML-based OASIS standard for exchanging user identity and security attributes information. It uses security tokens containing assertions to pass information about a principal (usually an end user) between an Identity Provider (IdP) and a web service. For more information, see SAMLv2-authentication.

2

Creating certificates

(on BMC Atrium Single Sign-On server)

You must create signing certificates so that they can be used for establishing trust relationship between AD FS server and BMC Atrium Single Sign-On server. For more information, see Creating-signing-and-encryption-certificates.

Note: Instead of creating a new certificate and a private key pair, you can use the existing certificates in SAMLv2 KeyStore.

3


 

Exchanging certificates

Exchange the certificates between AD FS server and BMC Atrium Single Sign-On server.

3.1 Exporting certificates with KeyStore Explorer tool
 (on BMC Atrium Single Sign-On server)

1. Open file in KeyStore Explorer.
2. Double click the certificate name. The Certificate Details dialog box is displayed.
3. Click PEM and export the certificate.
4. Save the certificate to a file.

3.2 Importing certificates with KeyStore Explorer tool

1. Open the truststore file using the KeyStore Explorer.
2. Select Tools and click Import Trusted Certificate.
3. Select the file and import it.

3.3 Importing certificates to AD FS via MMC
 

Note: When you are exchanging certificates in HA environment, import the load balancer certificate into AD FS server.

1. From the Run dialog box, type mmc to open Microsoft Management Console (MMC).
2. Open the File menu and click Add/Remove Snap-in…
3. Select Certificates from the list of available snap-ins and click Add.
   The Certificates snap-in dialog box is displayed.
4. Select My User Account, and click Finish and OK.
5. Open Personal>Certificates from the explorer panel.
6. On the Action menu, point to All Tasks, and then click Import to start the Certificate Import Wizard.
7. Type the file name containing the certificate to be imported. You can also click Browse and navigate to the file and import the following certificates: test_enc, test_sig, tomcat
8. Open Trusted Root Certification Authorities>Certificates from the explorer panel
9. Type the file name containing the certificate to be imported. You can also click Browse and navigate to the file and import the tomcat certificate.

3.4 Exporting ADFS certificates

(on AD FS server)

1. Open ADFS 2.0 Management console.
2. Open Service>Certificates from the explorer panel.
3. Export each the following three certificates: : test_enc, test_sig, tomcat
   1. Double click the certificate name.
   2. Select the Details… tab.
   3. Click Copy to File… and click Next.
   4. Select Do not export the private key and click Next.
   5. Select DER… and select the file to save it.
   6. Click Finish.

4

Configuring BMC Atrium Single Sign-On as local SP

(on BMC Atrium Single Sign-On server)

You must set BMC Atrium Single Sign-On as your local Service Provider (SP). Follow these steps for configuring BMC Atrium Single Sign-On as local SP.

1. On BMC Atrium SSO Admin Console, click the realm for which you want to configure SP. The Realm Editor console is displayed.
2. On the Realm Editor console, add a new local SP named sp and add the following parameters and click Save.
   1. Services tab
      
      • Name: sp
      • Binding: HTTP-Redirect or Post. This option determines the way in which SAML messages are sent and received between the IdP and the SP.
   2. Signing/Encryption tab
      
      • Signing certificate: test_sig sha1. This certificate can have any name.
      • Select check boxes for signing: Authentication Request, Logout Request, Logout Response.
   3. Authentication request
      • Default Authentication Context: <same value as claim rule>
        Note: You must add the same value which you have added while creating the claim rule for this parameter.
      •  Name Id Formats: Ensure that only the Transient check box is selected and use the upward arrow to move this name-id (Transient) to the top of the list.
        
   4. Logging tab
      
      • Enable the logging for SP and select the logging level.
   5. Assertion Processing tab. You can skip this step if you are Kerberos authentication instead of Internal LDAP in the Realm Authentication panel.
      
      • Auto Federation: Selected
      • Use Name ID as User ID: Selected
      • Clear the Attribute Mapping list and add the following pair: upn = uid
        Note: If you have not selected Use Name ID as User ID option, the attribute should have the full attribute name: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn  

Modify other parameters as per your environment requirements. For understanding the parameters for local Service Provider, see Configuring-BMC-Atrium-Single-Sign-On-as-an-SP.

5

Getting the metadata XML URL from the  AD FS server

(on AD FS server)

You must identify the IdP metadata URL for establishing the SAMLv2 relationship between AD FS and BMC Atrium Single Sign-On server. For example, open https://adfs-server.sso.com/federationmetadata/2007-06/Federationmetadata.xml.

You must use this URL in the next task. Alternatively, you can also download the XML file and upload it in the next task.

6

Configuring remote IdP

(on BMC Atrium Single Sign-On server)

You must configure your IdP in BMC Atrium Single Sign-On using remote Identity Provider (IdP) console. Follow these steps for configuring remote IdP.

1. On BMC Atrium SSO Admin Console, click the realm you want to edit.
   The Realm Editor console is displayed.
2. On the Realm Editor console, add a new remote IdP URL. For example: https://adfs-server.sso.com/federationmetadata/2007-06/Federationmetadata.xml.
   Alternatively, you can upload the metadata XML file to the BMC Atrium Single Sign-On server from a copy that has been downloaded from the AD FS server and stored on the computer on which you are using your browser.

7

Configure the agents for federation

(on BMC Atrium Single Sign-On server)

As part of configuring BMC Atrium Single Sign-On to host a SP,  you must modify the J2EE agents configuration to work with SAMLv2 federation.

Note: Each time a BMC product is integrated with the BMC Atrium Single Sign-On SP, you must modify the agent configuration so that the integrating product can work in the Federated SSO.

1. On the BMC Atrium SSO Admin Console, click Agent Details. For more information about agent properties, see Agent-manager-in-multi-tenant-environment.
2. Select the agents associated with a BMC product integrated with this Atrium Single Sign-On server. For example, arsystem@sample.bmc.com:8443.
3. Click Edit.
4. Select the realm that you want to modify and click Edit.
5. Modify the Login and Logout URI:
   1. Delete the URLs in the login URI field.
   2. Enter the Federated login URL. For information about the log in URL syntax, see Federated log in URL syntax.
   3. Delete the URLs in the logout URI field.
   4. Enter the Federated logout URL. For information about the log out URL syntax, see Federated log out URL syntax.

   5. Click Save.

      Note

      For more information about mapping realm URLs to the agent in a multi-tenant environment, see Mapping-realm-URLs-to-an-agent-for-multi-tenancy.

8

Setting up AD FS configuration

(on AD FS server)

After configuration of local Service Provider and remote Identity Provider in the BMC Atrium SSO Admin Console, you must set up AD FS on the Active Directory server. For more information, see Configuring-the-AD-FS-server.

9

Verifying AD FS configuration

• IdP verification - Open the following link: https://adfs-server.sso.com/adfs/ls/IdPInitiatedSignon.aspx  
• SP verification – Open the following link: https://sso-server.bmc.com:8443/atriumsso/spssoinit?metaAlias=/Realm/sp&idpEntityID=http://adfs-server.sso.com/adfs/services/trust

Note: You must use the meta-alias, host name, port, and IdP entity ID in your verification. The SP verification link is used as an example here.

10

Modifying properties using the OpenAM Console

You must modify some of the properties using the OpenAM console as they are not available on the BMC Atrium SSO Admin Console for BMC Atrium SSO 8.1 and 2013.02 releases.

1. Enable the OpenAM Console.

   Click here to read the tasks related to enabling or disabling OpenAM Console.

   a. Stop the BMC Atrium Single Sign-On server.

   b. To enable the OpenAM Console, set the value of the allow.access parameter to true in the web.xml file available at the following location:

       • For Microsoft Windows: <installationDirectory>\tomcat\webapps\atriumsso\WEB-INF\

       • For UNIX: <installationDirectory>/tomcat/webapps/atriumsso/WEB-INF/

   c. To disable the OpenAM Console, set the value of the allow.access parameter to false.

   d. After enabling or disabling the console, restart the BMC Atrium Single Sign-On server.

2. Open the OpenAM console using the following URL: http://<host-name>:<port>/atriumsso. You must use /atriumsso in the URL instead of /atriumsso/atsso/console/ssoadmin/ssoadmin.html. The OpenAM console is displayed.
3. Click the Federation tab.
4. In the Entity Providers section:
   1. Click the remote IdP from the list of entry providers.
   2. Select the Logout Response and Logout Request check boxes.
   3. Click Save.
5. Log off from the OpenAM Console.
6. Disable the OpenAM Console.