SAP NetWeaver Cloud Security Tutorial Single Sign-On and Identity Federation with ForgeRock OpenAM

Transcription

1 Single Sign-On and Identity Federation with ForgeRock OpenAM

2 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... 5 STEP 2: ESTABLISH TRUST TO ITELO S CORPORATE IDP IN SAP NETWEAVER CLOUD... 9 STEP 3: CONFIGURE IDENTITY FEDERATION IN ITELO S CORPORATE IDP STEP 4: CONFIGURE IDENTITY FEDERATION IN SAP NETWEAVER CLOUD STEP 5: CREATE TEST USERS AND GROUPS IN THE CORPORATE USER DIRECTORY STEP 6: TEST THE END-TO-END SCENARIO TROUBLESHOOTING TIPPS IdP Debug Logs SP Debug Logs User Agent SAML Message Trace REFERENCES

3 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 the Open-Source IAM-solution OpenAM from ForgeRock 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, 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 the Open Source-based OpenAM [ 3] IAM solution from ForgeRock, who continue to develop and support the former OpenSSO IAM product from Sun Microsystems. For Identity Federation, OpenAM offers a SAML 2.0 compliant Identity Provider, which can be integrated with various user directory products. In the scenario setup, ITelO employees have an account in the central corporate user directory running on OpenDJ [ 4], which is also part of the ForgeRock Open Source IAM stack. 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. As SAP NetWeaver Cloud has no permanent user storage, the OpenAM-based IdP must issue additional user profile data required by the leave request application in the Cloud. Along with the username entered by the user to authenticate against the IdP, 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 the SAP NetWeaver Cloud. This also includes the employee s internal group 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 3

4 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.telo.corp will be assigned to the group iteloemployees" (assuming that IdP idp.telo.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 [ 6] or productive account on the SAP NetWeaver Cloud platform. For more information, see [ 8]. You can download the complete source code from [ 5] 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 [ 8] 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 ForgeRock OpenAM is required. OpenAM can be deployed on Apache Tomcat and comes with an embedded version of OpenDJ, which is used as the corporate user store in the following steps. The version of OpenAM used in this tutorial is running on Apache Tomcat The DNS name of the instance in this tutorial is idp.itelo.corp, running on port 8080, with a context root set to the default value openam. 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. Establish trust to ITelO s corporate IdP in SAP NetWeaver Cloud 3. Configure identity federation in ITelO s corporate IdP 4. Configure identity federation in SAP NetWeaver Cloud 5. Create test users and groups in the corporate user directory: 6. Test the end-to-end scenario 4

5 STEP 1: ESTABLISH TRUST TO SAP NETWEAVER CLOUD IN ITELO S CORPORATE IDP The tutorial starts with creating a so-called hosted IdP and SP in OpenAM. To create the hosted SP, the SAP NetWeaver Cloud account administrator must maintain the SP configuration for his account. After completing this step, OpenAM will accept SAML Authentication Requests from the xleave application running on the SAP NetWeaver Cloud platform. What to do What you will see Login to the OpenAM Administration Console as the system administrator amadmin and create a new hosted IdP under tab Common Tasks. Choose a new IdP name or keep the default name (here ) and select the test key for signing the IdP metadata in this test environment. For the Circle of Trust (COT) identifier enter itelo. Create the new hosted IdP by clicking on the Configure button. On the confirmation page, click on Finish. Back on the main configuration page, click on the Federation tab and select the new IdP with name from the table Entity Providers. 5

6 In tab Assertion Content, scroll to section NameID Format/NameID Format List, and remove all entries apart from urn:oasis:names:tc:saml:1.1:nameidformat:unspecified in the Current Values list box. In section NameID Format/NameID Value Map, remove all entries and enter urn:oasis:names:tc:saml:1.1:nameidformat:unspecified=uid in the New Value field. Press Add to the new mapping. Upon successful authentication of the user, OpenAM will now use the SAML2 NameID Format unspecified in the SAML Response sent back to SAP NetWeaver Cloud, and use the uid attribute from the user profile as the value for the user s login name. Click on Save on the top or bottom of the page to update the IdP configuration. Click Back to return to the main configuration page. Before establishing the trust relationship in OpenAM to the xleave application, the Service Provider (SP) of your account in SAP NetWeaver Cloud must be configured. Open the Account Page at om (or 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: 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. 6

7 To simplify the creation of the new hosted SP in OpenAM, 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. Go back to the OpenAM Administration console and select Register Remote Service Provider in tab Common Tasks Choose File for the metadata location and click on Upload to select the file with the SAML2 metadata of the SAP NetWeaver Cloud Service Provider you just downloaded. After uploading the file, click on the Configure button to register the new hosted SP in OpenAM. Confirm the dialog box with OK and return to the main menu. Switch to the Federation tab and select the newly created SP from the list of Entity Providers by clicking on the link in the table. 7

8 Activate the checkbox for Logout Response Signed, because SAP NetWeaver Cloud expects those messages to be signed by the IdP. Click on Save to apply the change. 8

9 STEP 2: 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 OpenAM 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 om (or 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: Description: ITelO Corp. OpenAM IdP Assertion Consumer Service: Assertion Consumer Service Single Sign-on URL: ORedirect/metaAlias/idp Single Sign-on Binding: HTTP- Redirect Single Logout URL: SloRedirect/metaAlias/idp Single Logout Binding: HTTP- Redirect Signature Algorithm: SHA-1 Signing Certificate: <please refer to the next step> User ID Source: subject Note: The above URLs for Single Signon and Single Logout are based on the assumption that the OpenAM server runs on a host with the DNS idp.itelo.corp and HTTP port If your IP/DNS setup is different, the exact URLs can be found in the OpenAM Administration Console at Federation Entity Providers <Your IDP> Services IDP Service Attributes In a production environment, it is also highly recommended to use SSL/TLS protected endpoints instead of HTTP. 9

10 The certificate required to establish the trust and used by OpenAM to sign SAML Responses can be found in the configuration directory specified during the installation of the server (e.g. <HOME>/openam/openam). In a default configuration, a self-signed certificate with alias test for testing purposes only is created. To print out its value, the keytool command from the Java Development Kit can be used as follows: keytool exportcert v rfc alias test keystore keystore.jks The default password for the keystore file is changeit. The printed value can be copy & pasted (without the tags BEGIN/END CERTIFICATE ) into the Signing Certificate text 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. 10

11 STEP 3: CONFIGURE IDENTITY FEDERATION IN ITELO S CORPORATE IDP Based on the established trust relationship, OpenAM 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 OpenAM Administration Console and select the Federation tab. In the table Entity Providers, click on the entry for the SP of your SAP NetWeaver Cloud account ( o) Select the tab Assertion Processing and define the SAML Attributes that will be issued by the IdP for this SP. In the New Value field, enter the mapping fname=givenname and click Add. This will map the user profile attribute givenname to the SAML Attribute fname in the Assertion. Repeat this step with the following mappings for the remaining attributes: lname=sn orgid=departmentnumber empid=employeenumber role=ismemberof Click on Back to return to the main administration page. To issue the profile attributes departmentnumber, employeenumber and ismemberof, those attributes must be added to the list of LDAP User Attributes in the data store configuration for OpenAM. To add them, click on the Access Control tab, and select the Top Level Realm ( / ) from the Realms table. Next, click on the Data Stores tab for the realm and select the embedded store from the table. 11

12 Scroll down to section User Configuration/LDAP User Attributes and enter departmentnumber in the New Value field. Click Add to add it to the Current Values list. Repeat this step for the two other attributes employeenumber and ismemberof. To apply your changes, click on the Save button on the top or bottom of the page, and restart the Apache Tomcat Server. 12

13 STEP 4: CONFIGURE IDENTITY FEDERATION IN SAP NETWEAVER CLOUD The previous step configured the issuance of the required user profile attributes by the OpenAM 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 om (or 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. 13

14 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 of the OpenAM 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: role Rule Operation: equals Rule Value: cn=employee,ou=groups,dc=ope nsso,dc=java,dc=net 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. 14

15 Repeat the previous step for the Managers group. Click on Add Assertion-Based Group and enter Managers in the Group field. The Mapping Rule should be defined as follows: Assertion Attribute: role Rule Operation: equals Rule Value: cn=manager,ou=groups,dc=open sso,dc=java,dc=net 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. 15

16 STEP 5: CREATE TEST USERS AND GROUPS IN THE CORPORATE USER DIRECTORY Now it is time to create the users for testing the scenario. Two users and two groups will be created in the corporate directory running on OpenDJ: - John Doe, who is a member of the group Employee - Jane Smith, who is a member of the group Manager What to do What you will see In the OpenAM Administration Console, click on the Access Control tab and select the Top Level Realm ( / ) from the Realms table Switch to Subjects and click on the New button in the Users table Create a new user with the following values: ID: jdoe First Name: John Last Name: Doe Full Name: John Doe Password: abcd1234 User Status: Active Click on OK to save the new user. Repeat the step for another test user: ID: jsmith First Name: Jane Last Name: Smith Full Name: Jane Smith Password: abcd1234 User Status: Active 16

17 Back on the Subjects User tab, click on the link of the new user John Doe in the User table, and enter the address in the Address field. Click on Save to save the changes and Back to Subjects to return to the previous page. Repeat the step for the new test user Jane Smith and address To enter the user s department and employee numbers, the command line tool ldapmodify is used, which is located in the local OpenAM configuration directory (e.g. <HOME>/openam/opends). ldapmodify reads the modification of a directory object from a simple text file, that must contain the unique name of the object, the attribute, and its new value. jdoe.ldif: dn: uid=jdoe,ou=people,dc=opensso,dc=java,dc=net changetype: modify add: departmentnumber departmentnumber: 1234 jdoe2.ldif: dn: uid=jdoe,ou=people,dc=opensso,dc=java,dc=net changetype: modify add: employeenumber employeenumber: Create a file jdoe.ldif as shown in the right column, and enter the command ldapmodify h localhost p D cn=directory Manager w <password> -a f jdoe.ldif. Repeat the same step with a different input file (jdoe2.ldif) that adds the employeenumber attribute to John Does directory entry. Repeat the previous step for user Jane Smith, who belongs to the same department ( 1234 ) as John Doe, but has a different employee number ( ). jsmith.ldif: dn: uid=jsmith,ou=people,dc=opensso,dc=java,dc=net changetype: modify add: departmentnumber departmentnumber: 1234 jsmith2.ldif: dn: uid=jsmith,ou=people,dc=opensso,dc=java,dc=net changetype: modify add: employeenumber employeenumber:

18 Go back to the OpenAM Administration Console and switch to the Group tab in Subjects and click on New in the table Group. Enter Employee for the ID of the new Group and click OK. Repeat the step for another Group with ID Manager. Click on the link of the new Employee group in the Group table. 18

19 Switch to the User tab and select John Doe from the Available list. Then click the Add button to move the user to the Selected list. Click on Save to confirm the new group assignment of user John Doe, and then Back to Subjects. Repeat the previous step with Group Manager and assign user Jane Smith to it. 19

20 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. In the address bar, enter the URL of the xleave application in the Cloud following the URL schema name>.netweaver.ondemand.com/xlea ve You will be redirected by the Cloud to the login page of the corporate IdP. Sign in to OpenAM with User Name jdoe, Password abcd1234. 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 1234 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. 20

21 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. Click on the here link to logon again. This time, log in at the IdP with user name jsmith and password abcd

22 After 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 (1234), 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. 22

23 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 for SAML-based federation in OpenAM, start from the Administration Console main page and follow the navigation path Configuration Servers and Sites. In the table Servers, choose the IdP s Server ( ), and scroll to the section Debugging in the General tab (see Figure 3). Figure 3 Debugging settings in OpenAM As a result of setting the Debug Level to Message, a detailed log output is written to the subdirectory openam/debug of your local OpenAM configuration directory (e.g. <HOME>/openam). For SAML-related error analysis, the best source is the Federation log file. 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 4. 23

24 Figure 4 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. Figure 5 SAML Tracer Add-on for Firefox in action 24

25 Figure 5 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). REFERENCES 1. Cloud Single Sign-On and On-Premise Identity Federation with SAP NetWeaver Cloud Whitepaper: 2. SAML 2.0 Specifications: 3. ForgeRock OpenAM: 4. ForgeRock OpenDJ: 5. xleave Sample Application Download: 6. Get your free developer license for SAP NetWeaver Cloud in 5 minutes: SAP NetWeaver Cloud Account Types: 8. Setting up the Tools and SDK: 799B5CF516B38B7503F_17 25

26 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, 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.