SAP NetWeaver Cloud Security Tutorial - Single Sign-On and Identity Federation with Microsoft Active Directory Federation Services (ADFS) 2.

SAP NetWeaver Cloud Security Tutorial - Single Sign-On and Identity Federation with Microsoft Active Single Sign-On and Identity Federation with Microsoft Active

Directory Federation Services (ADFS) 2.0 TABLE OF CONTENTS OVERVIEW... 3 PREREQUISITES AND REQUIREMENTS... 4 GETTING STARTED... 4 STEP 1: ESTABLISH TRUST TO SAP NETWEAVER CLOUD IN ITELO S CORPORATE IDP... 6 STEP 2: CREATE TEST USERS AND GROUPS IN THE CORPORATE USER DIRECTORY... 9 STEP 3: ESTABLISH TRUST TO ITELO S CORPORATE IDP IN SAP NETWEAVER CLOUD... 14 STEP 4: CONFIGURE IDENTITY FEDERATION IN ITELO S CORPORATE IDP... 16 STEP 5: CONFIGURE IDENTITY FEDERATION IN SAP NETWEAVER CLOUD... 20 STEP 6: TEST THE END-TO-END SCENARIO... 23 TROUBLESHOOTING TIPPS... 25 IdP Debug Logs... 25 SP Debug Logs... 25 User Agent SAML Message Trace... 26 REFERENCES... 28 2

This tutorial is part of a series on how to setup Single Sign-On (SSO) and Identity Federation between the SAP NetWeaver Cloud platform and existing identity and access management (IAM) systems. In this document, a complete end-to-end scenario for integrating SAP NetWeaver Cloud with Microsoft Active will be implemented based on the Security Assertion Markup Language (SAML) 2.0 protocol. OVERVIEW Based on the enterprise scenario in the SAP NetWeaver Cloud SSO and Identity Federation whitepaper [ 1], the sample application for leave request management (xleave) running on the SAP NetWeaver Cloud platform acts as the SAML Service Provider (SP) that requires user authentication to obtain access to protected resources. As specified by the SAML protocol [ 2], the system responsible to verify the identity of authorized users is the Identity Provider (IdP). In this tutorial, the IdP is an existing system running onpremise in the corporate network. The IdP is connected to the corporate directory server which manages the accounts for all users that are allowed to access the SP in the Cloud. In this role, the IdP can verify the username and password entered by the user to login to the SAP NetWeaver Cloud application against the credentials stored in the corporate directory. Upon successful login, the IdP confirms the user s identities to the trusted SP in the Cloud, and the user is logged on without being asked again for the username and password. Figure 1 Federation Scenario Overview Figure 1 illustrates the setup based on the enterprise scenario in [ 1] of the fictitious company ITelO. In this tutorial, ITelO runs Microsoft s Active [ 3] solution. For Identity Federation with SAML, ADFS 2.0 offers a SAML 2.0 compliant Identity Provider, which runs on top of Microsoft s Active Directory (AD) as the central user store. In the scenario setup, ITelO employees have an account in AD and are assigned to Groups which are also managed in AD. Using the SAML 2.0 protocol in the scenario, ITelO employees will be able to (single) sign-on to the xleave leave request application in the SAP NetWeaver Cloud using their corporate credentials. With Kerberos/SPNEGO in place for SSO in the ITelO corporate network, the user is actually only required to enter the domain username and password once in the morning when she logs on to ITelO s AD Domain. Any subsequent logons including authentication at ADFS during a SAML-based sign-on to the SAP NetWeaver Cloud will happen completely transparently from the user s perspective. As SAP NetWeaver Cloud has no permanent user storage, ADFS must issue additional user profile data required by the xleave application in the Cloud. Along with the user name derived from the Kerberos tickets used to (single) sign-on at ADFS, attributes such as the employee s first name, last name and company employee id are also added to the authentication statement (SAML Assertion) in the SAML Response sent back to the SP running on SAP NetWeaver Cloud. This also includes the employee s internal group 3

assignments in the corporate user directory which are required to authorize certain actions of the logged in user in the Cloud. To avoid complex and error-prone data synchronization and double maintenance of group assignments in the on-premise IAM system and the xleave application, permissions in the Cloud are calculated dynamically using the information obtained from the SAML Assertion that the IdP issues for each authenticated user. The NetWeaver Cloud account administrator can define a set of rules for mapping each authenticated user to roles used by the applications running on SAP NetWeaver Cloud. Such a rule, translated in human-readable form, could be something like this: "If a user authenticated by the trusted corporate IdP idp.telo.corp has a SAML 2.0 assertion with the attribute role which contains the value Manager, assign this user to the group Managers on SAP NetWeaver Cloud", or "Any user authenticated by the trusted corporate IdP idp.itelo.corp will be assigned to the group iteloemployees" (assuming that IdP idp.itelo.corp only manages accounts from company ITelO). As described in [ 1], the xleave application defines two web roles in its web.xml file following standard Java EE conventions: Employee and Manager (see Figure 2). Figure 2 xleave web role definitions in web.xml Those roles will be mapped based on a role attribute in the SAML response which contains the current group assignment in UME of the logged-in employee. PREREQUISITES AND REQUIREMENTS To deploy the xleave application on the Cloud, you need a trial [ 7] or productive account on the SAP NetWeaver Cloud platform. For more information, see [ 8]. You can download the complete source code from [ 6], import it as a project in Eclipse, and deploy from there using the SAP NetWeaver Cloud Eclipse tools. For more information about installing and configuring these tools, see [ 9]. Alternatively, the download also contains a WAR file of the application, which can be deployed with the SAP NetWeaver Cloud Console Client neo and the deploy command, e.g. neo deploy -s c:\xleave.war -a <your account name> -h netweaver.ondemand.com -u <your SCN user ID> -b xleave In addition, an instance of Microsoft ADFS 2.0 is required, which is connected to a Domain Controller running Active Directory to provide the corporate user store for this tutorial. The version of ADFS used in this tutorial is 2.0 RTW [ 4] with the Update Rollup 2 installed [ 5] on Window Server 2008 Standard, Service Pack 2. The DNS name of the server is idp.itelo.corp with an Internet Information Services (IIS) 7 running on standard ports 80 (HTTP) and 443 (HTTPS). GETTING STARTED Setting up the federation scenario comprises in total of six steps, which are explained in more detail in the following sections: 1. Establish trust to SAP NetWeaver Cloud in ITelO s corporate IdP 2. Create test users and groups in the corporate user directory 3. Establish trust to ITelO s corporate IdP in SAP NetWeaver Cloud 4. Configure identity federation in ITelO s corporate IdP 5. Configure identity federation in SAP NetWeaver Cloud 4

6. Test the end-to-end scenario 5

STEP 1: ESTABLISH TRUST TO SAP NETWEAVER CLOUD IN ITELO S CORPORATE IDP The first step in this tutorial is about creating a so-called Relying Party (RP) Trust in ADFS for the xleave application on SAP NetWeaver Cloud. In SAML terminology, an RP is similar to an SP. So before you can create the RP, the SAP NetWeaver Cloud account administrator must maintain the SP configuration for his account. After completing this step, ADFS will accept SAML Authentication Requests from the SAP NetWeaver Cloud platform. What to do What you will see Before establishing the trust relationship in ADFS to the xleave application, the Service Provider (SP) of your account in SAP NetWeaver Cloud must be configured. Open the Account Page at https://account.netweaver.ondemand.c om (or https://account.nwtrial.ondemand.com if you have a trial account) and log in as an administrator for your SAP NetWeaver Cloud account. Go to Trust Local Service Provider, click on the Edit button, and make the following changes: Configuration Type: Custom Local Provider Name: https://netweaver.ondemand.com/de mo Click on the Generate Key Pair button to create a new Signing Key and Certificate pair for your SP in the Cloud. Click on Save to store your new settings. To simplify the creation of the new RP Trust in ADFS, export the SP SAML metadata in SAP NetWeaver Cloud by clicking on the Get Metadata link and store the metadata file on the local file system. 6

Start the ADFS Management Console. Right-click on Relying Party Trusts and choose Add Relying Party Trust, or click on the same link in the Actions pane. On the Welcome step, click Start and choose the option Import data about the relying party from a file on the second wizard step. Click Next. Specify the Display Name (e.g. xleave on SAP NetWeaver Cloud ) and provide some optional notes for the new RP. Click Next. Select the option Permit all users to access this relying party and click Next. 7

All data in the SAML2 metadata file from the Cloud has now been imported into ADFS and can be reviewed on the different tabs. Click Next to complete the wizard and Close to end it. The Claim Rule Editor will open if you leave the checkbox activated on the last wizard page. You will continue here in step 4. 8

STEP 2: CREATE TEST USERS AND GROUPS IN THE CORPORATE USER DIRECTORY Now it is time to create the users and groups for the scenario. Two users and two groups will be created in Active Directory: - John Doe, who is a member of the group Employees - Jane Smith, who is a member of the group Managers What to do What you will see Open Start Administrative Tools and launch the tool Active Directory Users and Computers. In the directory tree, right-click on the Users node and select New Group from the context menu. Enter as Group name Employees and click on OK. Repeat this step to create another group with Group name Managers. 9

Right-click on the Users node again and select New User from the context menu. Create a new domain user with the following data: First name: John Last name: Doe Full name: John Doe User logon name: jdoe Click on Next. 10

Enter the new user s password Init1234#. Deactivate the checkbox User must change password at next login and activate the checkbox Password never expires. Click Next and Finish. Repeat the last two steps to create another user with the following data: First name: Jane Last name: Smith Full name: Jane Smith User logon name: jsmith Password: Init1234# Double-click on the new user John Doe in the list of Users to open the properties. On the Organization tab, enter Sales in the Department field. Switch to the Member Of tab. 11

Click on Add.. and enter Employees as the group name to add the user to. Click on OK to confirm the assignment. Click on OK to close the User properties dialog. Double-click on the new user Jane Smith in the Users list and enter Sales again in the Department field. Then assign user Jane Smith to the group Managers. Finally, enter the user profile attributes for the employee id with the ADSI Edit tool in Start Administrative Tools. Select the CN=Users node in the directory tree and right-click on the entry CN=John Doe. Select Properties from the context menu and search for the employeeid attribute in the list. Click on Edit to change its value. Enter a value (e.g. 12345 ) and click on OK. Click on OK to apply the property changes to the user. 12

Repeat the last two steps for user CN=Jane Smith. Enter a different value (e.g. 98765 ) for the employeeid attribute. All users and groups are now defined. Close the ADSI Edit tool. 13

STEP 3: ESTABLISH TRUST TO ITELO S CORPORATE IDP IN SAP NETWEAVER CLOUD Now the trust relationship must also be established into the opposite direction, i.e. the Cloud must also trust the corporate IdP in order to complete the end-to-end message flow defined by the SAML protocol. As a result of creating a trusted IdP in the SAP NetWeaver Cloud account, the SAML Response sent by ADFS will be accepted by the xleave application and can be used to login the user. What to do What you will see Go back to the SAP NetWeaver Cloud Account Page at https://account.netweaver.ondemand.c om (or https://account.nwtrial.ondemand.com if you have a trial account), or login again as an administrator for your SAP NetWeaver Cloud account. Select Trust Trusted Identity Provider and select the Add Trusted Identity Provider link. Enter the following data in the General tab for the new trusted IdP: Name: http://idp.itelo.corp/adfs/services/trust Note: The exact issuer name of the ADFS IdP can be looked up in the ADFS Management Console Actions pane under Edit Federation Service Properties Federation Service Identifier: Description: ITelO Corp. ADFS IDP Assertion Consumer Service: Assertion Consumer Service Single Sign-on URL: https://idp.itelo.corp/adfs/ls/ Single Sign-on Binding: HTTP- Redirect Single Logout URL: https://idp.itelo.corp/adfs/ls/ Note: The above URLs for Single Sign-on and Single Logout are based on the assumption that the ADFS server runs on a host with the DNS idp.itelo.corp and SSL port 443. If your IP/DNS setup is different, the URLs need to change as well. Single Logout Binding: HTTP- Redirect Signature Algorithm: SHA-256 Signing Certificate: <please refer to the next step> User ID Source: subject 14

The certificate required to establish the trust and used by ADFS to sign SAML Responses can be found in the ADFS Management Console by selecting Service Certificates. Double-click on the Certificate entry under Tokensigning. This opens the Certificate Viewer. Switch to tab Details and click on the button Copy to File. In the Certificate Export Wizard, choose the Export File Format Base64-encoded X.509 (.CER). After saving the certificate to a file, you can open it in a text editor. Copy the section between the BEGIN and END CERTIFICATE tags into the clipboard and paste it in the Signing Certificate form field of the previous step. Click on Save & Close to create a new trusted IdP in your SAP NetWeaver Cloud account. With this step the basic trust configuration is complete, and the trust relationship is now established on both sides. Next, the federation settings to share and map user profile attributes will be configured. 15

STEP 4: CONFIGURE IDENTITY FEDERATION IN ITELO S CORPORATE IDP Based on the established trust relationship, ADFS must now be configured to issue the employee s user profile attributes required by xleave. These include the following data: First name Last name Employee ID Organization Unit (e.g. department/cost center number or name) Role (i.e. Employee or Manager ) What to do What you will see Go back to the ADFS Management Management Console. If the Claim Rule Editor is not open, select the new RP xleave on SAP NetWeaver Cloud from the list of Relying Party Trusts and click on the link Edit Claim Rules in the right pane. Click on Add Rule and choose the Claim rule template Send LDAP Attributes as Claims. Click Next. This Claim Rule will instruct ADFS to issue the user s (Domain) logon name as the subject name identifier (Name ID) in the SAML Response sent back to SAP NetWeaver Cloud. Enter the following data: Claim rule name: Issue UPN as NameID Attribute store: Active Directory Mapping of LDAP attributes to outgoing claim types: o LDAP Attribute: User-Principal- Name o Outgoing Claim Type: Name ID Click on Finish to save the rule. 16

Click on Add Rule again to issue the remaining user profile attributes. Choose the Claim rule template Send LDAP Attributes as Claims and click on Next. This Claim Rule will instruct ADFS to issue the user s firstname, lastname, organizational id and employee id as SAML Attributes (aka Claims ) in the response. Enter the following data: Claim rule name: Issue User Proile Attributes as Claims Attribute store: Active Directory Mapping of LDAP attributes to outgoing claim types (LDAP Attribute Outgoing Claim Type): o Given-Name fname o Surname lname o Employee-ID empid o Department orgid Click on Finish to save the rule. The last two Claim Rules will issue the user s membership in the Employees and Managers group as the role attribute. Click on Add Rule again and choose the Claim rule template Send Group Membership as Claims. Click on Next. 17

Enter the following data: Claim rule name: Issue Employee Group membership as role Claim User s group: ITELO\Employees Outgoing claim type: Role Outgoing claim value: Employee Click on Finish to save the new rule. Repeat the last two steps and create another group membership rule with the following data: Claim rule name: Issue Manager Group membership as role Claim User s group: ITELO\Managers Outgoing claim type: Role Outgoing claim value: Manager Click on Finish to save the new rule. 18

Click on OK to apply the changes in the Claim Rules to the RP for SAP NetWeaver Cloud. 19

STEP 5: CONFIGURE IDENTITY FEDERATION IN SAP NETWEAVER CLOUD The previous step configured the issuance of the required user profile attributes by the ADFS IdP. Now those attributes have to be mapped to the attributes used by the xleave application. Special attention will be given to the role attribute, which is used to map the logged in user to a role defined by the xleave application. More information about federated authorizations and attribute mapping can be found in [ 1]. What to do What you will see Go to the SAP NetWeaver Cloud Account Page at https://account.netweaver.ondemand.c om (or https://account.nwtrial.ondemand.com if you have a trial account) and log in as an administrator for your SAP NetWeaver Cloud account. Click on Authorizations in the top-level navigation bar and switch to the Groups tab. In the field Group, enter Employees and click on Show Roles. Now a new role can be added to the new group Employees by clicking on the Assign button. In the new dialog box, select Application xleave and Role Employee. Click on Save to assign it to the group. Repeat the two steps by entering Managers in the Group field and press Show Roles again. 20

Now select the Manager role from xleave application and add it to the new group Managers by clicking on Save. With the new groups Employees and Managers being mapped to the according web roles in the xleave application, the federation settings can be configured. In Trust, select the Trusted Identity Provider tab and select the entry http://idp.itelo.corp/adfs/services/trust of the ADFS IdP to edit its settings. Switch to the Groups tab and click on the Add Assertion-Based Group link. Enter Employees in the Group field and define one Mapping Rule as follows: Assertion Attribute: http://schemas.microsoft.com/ws/ 2008/06/identity/claims/role Note: The Assertion Attribute name is taken from the name of the predefined Role claim in ADFS. It can be looked up in the ADFS Management Console under Service Claim Descriptions. Rule Operation: equals Rule Value: Employee Every user with a role attribute containing the specified value will now be assigned to the group Employees in the Cloud, which contains the web role Employee from the xleave application. 21

Repeat the previous step for the Managers group. Click on the Add Assertion-Based Group and enter Managers in the Group field. The mapping rule should be defined as follows: Assertion Attribute: http://schemas.microsoft.com/ws/ 2008/06/identity/claims/role Rule Operation: equals Rule Value: Manager Switch to the Attributes tab to define the mappings of the incoming SAML Assertion attributes to the user principal attributes used by the xleave application. Click on the Add Assertion-Based Attribute link. In the new empty row, enter fname for the Assertion Attribute, and map it to the Principal Attribute with name firstname (as referred to in the xleave application code). Repeat the step to add the remaining mappings (Assertion Attribute Principal Attribute): lname lastname orgid orgid empid userid Note: Mappings are CASE-SENSITIVE! To save your new federation settings, click on the Save & Close button. 22

STEP 6: TEST THE END-TO-END SCENARIO Now it s time to test the complete end-to-end scenario with the two test users John Doe and Jane Smith. John will create a new leave request which will be approved by his manager Jane. What to do What you will see Start a new web browser on a computer with connectivity to the corporate IdP. You can also use the ADFS host itself. In the address bar, enter the URL of the xleave application in the Cloud following the URL schema https://xleave<account name>.netweaver.ondemand.com/xl eave You will be redirected by the Cloud to the corporate IdP. Note: For testing purposes, Integrated Windows Authentication (IWA) has been removed (commented out) from the list of ADFS authentication handlers in file C:\inetpub\adfs\ls\web.config: Since IWA is switched off, sign on to ADFS with John Doe s domain credentials User Name jdoe, Password Init1234# in the ADFS Form Sign in page. Upon successful authentication at the IdP, you are logged in as user jdoe in the Cloud. All attributes from the corporate directory have been passed with the SAML Response to the xleave application (e.g. OrgUnit Sales or the first and last name). As user John Doe has been dynamically assigned to the web role Employee based on the content of his role attribute, he can create a new leave request by clicking on the New request button. 23

Enter some data for the new leave request and click on Send to save it. Click on the Logout button on the top right corner to logout. You have now globally logged out from the IdP and SP. Close the browser and start it again. Go again to URL https://xleave<account name>.netweaver.ondemand.com/xl eave This time, log in at the IdP with user name jsmith and password Init1234#. Upon successful authentication at the IdP, Jane Smith is single signed-on to the xleave application and assigned to the Cloud role Manager. Since she also belongs to the same OrgUnit as John ( Sales ), Jane can approve or reject John s leave request. Click on Approve and logout from the xleave application. Congratulations! With the completion of this step the scenario has been tested successfully. 24

TROUBLESHOOTING TIPPS In complex security setups like this, just a single wrong configuration setting can break the interoperability between the IdP on-premise and the SP in the Cloud. Thus, it is important to know how to identify the root cause for the issue and where to start with a detailed error analysis. For SAML scenario, the potential places to look at are IdP debug logs SP debug logs SAML message flow trace at the User Agent (Web Browser) This section proposes different troubleshooting strategies according to those places. IdP Debug Logs To activate the debug log in ADFS, start the Event Viewer application on the ADFS host and right-click on the node Applications and Services Logs View Show Analytic and Debug Logs (see Figure 3). Figure 3 Show Debug Logs for ADFS A new folder AD FS 2.0 Tracing will appear in the navigation tree on the right side. Right-click on its Debug entry and select Enable Log from the context menu (see Figure 4). Figure 4 Enable Debug Log SP Debug Logs Increasing the debug log level for the xleave application in the Cloud can be done either with the SAP NetWeaver Cloud Command Client ( neo deploy with the log parameter severity <log_level>), or using the Account Page administration page. The command client will apply the same log level to all loggers, whereas in the Account Page also specific loggers can be configured. Clicking on the Logs link of the xleave entry in the table of the Applications tab opens the dialog shown in Figure 5. 25

Figure 5 Debug level configuration for SAML2 in SAP NetWeaver Cloud Enter saml2 as a filter string to and search for the logger with name com.sap.core.jpaas.security.saml2.sp in the results. This is a good place to start if for example everything seems to work fine on the IdP side, but the SAML Response is not processed correctly in the Cloud (e.g. xleave application throws HTTP 500 error). User Agent SAML Message Trace Having a closer look at the actual messages sent back and forth between the SP and IdP might also help to resolve interoperability issues in certain situations. Since the SAML protocol completely relies on the user s web browser to forward all messages between the Cloud and on-premise, a tool like SAML Tracer available as an Add-on for Mozilla Firefox can capture the complete communication flow and make it available for further analysis. 26

Figure 6 SAML Tracer Add-on for Firefox in action Figure 6 shows the tool in action with a sample trace taken during testing of the scenario. The SAML-related HTTP requests are marked with a SAML label in the message trace, and can be examined in more detail in the specific viewer (SAML tab). 27

REFERENCES 1. Cloud Single Sign-On and On-Premise Identity Federation with SAP NetWeaver Cloud Whitepaper: http://scn.sap.com/docs/doc-32675 2. SAML 2.0 Specifications: http://saml.xml.org/saml-specifications 3. ADFS 2.0 Documentation: http://technet.microsoft.com/en-us/library/adfs2(v=ws.10).aspx 4. ADFS 2.0 Download: http://www.microsoft.com/en-us/download/details.aspx?id=10909 5. Update Rollup 2 for ADFS 2.0: http://support.microsoft.com/kb/2681584 6. Leave Sample Application Download: Click here to download 7. Get your free developer license for SAP NetWeaver Cloud in 5 minutes: http://scn.sap.com/docs/doc-28197 8. SAP NetWeaver Cloud Account Types: https://help.netweaver.ondemand.com/default.htm?account_types.html 9. Setting up the Tools and SDK: https://help.netweaver.ondemand.com/default.htm?setting_up_tools.html#concept_9e86cb16f64947 99B5CF516B38B7503F_17 10. SAP NetWeaver Cloud Security Tutorial - Single Sign-On and Identity Federation with ForgeRock OpenAM: https://scn.sap.com/docs/doc-35456 11. SAP NetWeaver Cloud Security Tutorial - Single Sign-On and Identity Federation with SAP NetWeaver Identity Management: https://scn.sap.com/docs/doc-35457 28

www.sap.com 2013 SAP AG. All rights reserved. SAP, R/3, SAP NetWeaver, Duet, PartnerEdge, ByDesign, SAP BusinessObjects Explorer, StreamWork, SAP HANA, and other SAP products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of SAP AG in Germany and other countries. Business Objects and the Business Objects logo, BusinessObjects, Crystal Reports, Crystal Decisions, Web Intelligence, Xcelsius, and other Business Objects products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of Business Objects Software Ltd. Business Objects is an SAP company. Sybase and Adaptive Server, ianywhere, Sybase 365, SQL Anywhere, and other Sybase products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of Sybase Inc. Sybase is an SAP company. Crossgate, m@gic EDDY, B2B 360, and B2B 360 Services are registered trademarks of Crossgate AG in Germany and other countries. Crossgate is an SAP company. All other product and service names mentioned are the trademarks of their respective companies. Data contained in this document serves informational purposes only. National product specifications may vary. These materials are subject to change without notice. These materials are provided by SAP AG and its affiliated companies ("SAP Group") for informational purposes only, without representation or warranty of any kind, and SAP Group shall not be liable for errors or omissions with respect to the materials. The only warranties for SAP Group products and services are those that are set forth in the express warranty statements accompanying such products and services, if any. Nothing herein should be construed as constituting an additional warranty.