How to setup SAML with ActiveDirectory (ADFS)

Here I will outline the current process & steps for setting up single sign-on with your corporate identity provider (active directory) using ADFS (active directory federation services).

SAP BusinessObjects Cloud supports SAML2.0, and should work with any identity provider capable of supporting this standard.

Step 1.   Retrieve metadata from your Active Directory

Browse to https://<SERVER>/FederationMetadata/2007-06/FederationMetadata.xml  where <server> will be the server where ADFS is installed.

Your browser will download/open an XML file.

Step 2.  Submit the file from step 1 to SAP with a BCP ticket, requesting a SAML SSO configuration

While this step requires  ticket submission, we expect to make this self service in the near future.

Step 3.  Receive the Service Provider (SP) metadata XML file from SAP

You (or more specifically the Active Directory administrator) will need to import this file to its Active Directory configuration.

Steps 1-3 are essentially an exchange of SAML files to establish a trust between cloud analytics and your active directory.

Step 4.  Configure Active Directory

The majority of work is on the ADFS side.  For details on AD setup, refer to Active directory Follow these steps:

1. Add Relying Party Trusts
   1. Open AD FS 2.0 Management
   2. ExpandAD FS 2.0 -> Trust Relationships
   3. Right click Relying Party Trusts, choose Add Relying Party Trust
   4. In Welcome step, click start
   5. In Select Data Source step, select Import data about relying party from a file, click Browse to select the metadata file  you received from SAP, click Next
   6. In Specify Display Name step, Input the Display name (such as "SAP BusinessObjects Cloud) and Notes, click Next
   7. In Choose Issuance Authorization Rules step, choose Permit all users to access this relying party, click Next
      1. To understand difference between permit all & deny see MS documentation.
   8. In Ready to Add Trust step, review all the information, then click Next
   9. In Finish step, click Close
2. Change properties of the relying party trust
   1. Double click the relying party trust that you have just added to open the properties dialog
   2. In Advanced tab, Change the Secure Hash algorithm to SHA-1
      1. Note:  This will be changed to SHA-256 in the near future, this blog will be updated accordingly.
   3. Click OK
      
3. (Optional) Configure SAML logout page.  This sets where you want the users to be redirected when they click "logout" from the application.    You can redirect them to your corporate home page for example.  
   - Note that redirecting them to the application logon page probably won't make sense as that would redirect the user back to the SAML logon provider and start the logon workflow again.

1. Expand AD FS 2.0 -> Trust Relationships -> Relying Party Trusts
2. Double click your trust to open the properties dialog
3. Click the Endpoints tab
4. Select the SAML Logout Endpoints, and click Edit button
5. Input theResponse URL, then clickOK to save the changes
   The response URL is suggested to be https://<server>/sap/fpa/ui/public/formLogin/
6. Click OK to close the properties dialog
   

     4.  Setup which value will be used as the user mapping by editing Claim Rules.  For example username, or email.

1. Expand AD FS 2.0 -> Trust Relationships -> Claim Provider Trusts
2. Right click the provider that you will use to edit the claim rules of relying party trust, select Edit Claim Rules
3. In Acceptance Transform Rules tab, click Add Rule
4. In Choose Rule Type step, select Send LDAP Attributes as Claims, click Next
5. In Configure Claim Rule step, input the claim rule name, selectActive Directoryas Attribute store, map the LDAP AttributeSAM-Account-Name to Outing Claim Type (here we use UserID as an example, you can specify yours )
   
6. Click Finish to close Add Transform Claim Rule Wizard
7. Click OK to close the Edit Claim Rules for Active Directory dialog

5. Edit Claim Rules of Relying Party Trust

1. Expand AD FS 2.0 -> Trust Relationships -> Relying Party Trusts
2. Right click the trust that you just added, select Edit Claim Rules
3. In Issuance Transform Rules tab, click Add Rule
4. In Choose Rule Type step, select Transform an Incoming Claim, then click Next
5. In Configure Claim Rule step, input Claim Rule name, input the name you specify as Outing Claim Type in Claim Rules of Claim Provider Trust (Here we use UserID) for Incoming claim Type, select Name ID as Outgoing claim type, select Unspecified as Outing name ID format, select Pass through all claim rules, then click Finish
   
   
6. Click OK to close Edit Claim Rules dialog

6. Edit SAML user attributes, this will allow to pull in additional information.  Not all of it is required, if you don't want to pull in phone numbers for example.

1. Expand AD FS 2.0 -> Trust Relationships -> Relying Party Trusts
2. Right click your trust, select Edit Claim Rules
3. In Issuance Transform Rules tab, click Add Rule
4. In Choose Rule Type step, select Send LDAP Attributes as Claims, then click Next
5. In Configure Claim Rule step, input Claim Rule name, select Active Directory as Attribute store, map all the LDAP Attributes to the names you want, then click Finish
   
   The Mapping is suggested to be

   LDAP Attribute	Outgoing Claim Type
   SAM-Account-Name	ID
   SAM-Account-Name	USERNAME
   Given-Name	FIRST_NAME
   Surname	LAST_NAME
   Display-Name	DISPLAY_NAME
   E-Mail-Address	EMAIL
   Telephone-Number	OFFICE_PHONE
   Company	COMPANY
   Street-Address	OFFICE_ADDRESS
   Title	JOB_TITLE
   mobile	MOBILE

6. Click OK to close Edit Claim Rules dialog

5. Step 5: Add users into the cloud system

Add users in the administration console with the appropriate SAML mappings.  If a user is not mapped in, they will get a 403 access denied when logging on.

In the above step, the AD user ID is used.  To use email, you would change the LDAP attribute mappings above into the example below, would insert the "email" value from active directory as the ID attribute of the SAML assertion received. 

6.   Step 6 Test the logon.

You will have received the logon URL setup for SAML as part of the SAP BCP ticket.  Users should now be able to logon via SAML.

Troubleshooting

• Upon logon user gets an error "StatusCode in ResponseMessage != OK; please refer to the database trace for more information"
  • Most likely because of the mismatch in SHA-1 to SHA-256.  In Step 4 above, confirm point #2 around secure hash algorithm.
• Users are not getting redirected to the ADFS logon page
  • Confirm the logon URL.   It will have a pattern such as https://<server>/t/#    where # is the internal representation of your tenant ID.
  • You can also find the ID in the administration console
    
    in this example, my logon URL would be https://<server>/t/T