SAP HANA Cloud Platform Security Tutorial Securing your Web API with OAuth 2.0

Transcription

1 Securing your Web API with OAuth 2.0

2 TABLE OF CONTENTS INTRODUCTION TO OAUTH OAuth Protocol... 4 Delegated Authentication... 6 Why OAuth?... 7 BUSINESS SCENARIO... 7 Mobile use case... 8 Integration with the Corporate IdP... 9 Integration with the SAP HANA Cloud Platform OAuth 2.0 AS Protection of xleave s web API Prerequisites and Requirements STEP 1: RUNNING THE MOBILE SCENARIO ON THE LOCAL SAP HANA CLOUD PLATFORM RUNTIME STEP 2: DEPLOYING XLEAVE IN THE SAP HANA CLOUD PLATFORM TRIAL ACCOUNT STEP 3: CONFIGURING THE MOBILE SCENARIO IN THE CLOUD STEP 4: RUNNING THE MOBILE SCENARIO IN THE CLOUD STEP 5: RUNNING THE BROWSER SCENARIO IN THE CLOUD AND USING THE OAUTH END-USER UI SUMMARY

3 The Open Authorization Framework, commonly known under the abbreviation OAuth, started in 2007 as an informal initiative driven by a small group of implementers to standardize an open authorization protocol for a long-standing security issue: Authorizing a client application to access protected server resources on behalf of a user without seeing or knowing the user s secret credentials. The purpose of this tutorial is to explain how OAuth can be used to secure access to an application deployed on the SAP HANA Cloud Platform. INTRODUCTION TO OAUTH 2.0 Figure 1 illustrates a typical scenario for OAuth: A social media web site asks the user for her mailbox username and password to browse through her contacts in order to update her connections. What first sounds like a useful service to the user actually asks her for giving away the keys to her house in order to let the web site riffle through her address book. This security issue also referred to as the Password Anti- Pattern, can be defeated by OAuth. OAuth provides an access-delegation framework that enables the client application (the social media web site in the example) to access the user s resources ( contacts) via some web API exposed by the resource server (mailbox server) on behalf of the user without the need to share her username and password. Figure 1 Password Anti-Pattern The first version of OAuth mainly focused on the above scenario where the client application is a web site. OAuth version 2.0, which has been finalized in October 2012 as Request for Comments (RFC) by the Internet Engineering Task Force (IETF), adds support for native mobile client apps, desktop applications and (Java) script clients running in a browser. All of these client applications have in common that they use HTTP(S) to invoke a web API exposed by a resource server that returns the user s data in a format that can be easily parsed by the client, such as XML or JSON. The increasing popularity of web APIs to enable integration with non-browser based clients can be followed best on Programmable Web ( a service that keeps track of the fast growing number of public web APIs in a central directory. According to their statistics in November 2013, more than out of registered web APIs were based on the Representational State Transfer (REST 3 ) design pattern, which usually makes use of the HTTP protocol and its methods (e.g. GET, POST, PUT, or DELETE) to implement common operations on the user s data. For those RESTful web APIs, OAuth is a very popular authorization framework, used by many well-known web sites such as Twitter or Facebook

4 OAuth Protocol To support different types of client applications, OAuth 2.0 introduced the notion of an Authorization Grant Type and their associated Flows. Section 4 ( Obtaining Authorization 4 ) in RFC 6749 specifies four of them, but they can be extended by additional Grant Types if required. To get started, let s look at the first and most commonly used one, the authorization code grant flow. So what is an Authorization Grant? It is basically a credential that represents the user s confirmation that she authorized a specific client application to access her protected data. The authorization grant can even be further limited by the user to a clearly defined scope under which the client application will be allowed to act on the user s behalf. Once the client application has obtained the authorization grant from the user, it request an OAuth access token for it, which it finally uses to make authenticated and authorized calls of the resource server s web API. Figure 2 High-level OAuth 2.0 Protocol Flow on SAP HANA Cloud Platform Figure 2 illustrates these steps in more detail based on an application running on SAP HANA Cloud Platform: 1. The user launches the client application (e.g. a native mobile client app on her smartphone) for the first time and needs to authorize it for making calls to the web API exposed by the application deployed on SAP HANA Cloud Platform (resource server) on her behalf. The client application therefore sends an authorization request to a central component in SAP HANA Cloud Platform, the OAuth 2.0 Authorization Server (AS). 2. The AS needs to ask the user for confirmation of the client application s authorization request. To do so, the AS authenticates the user first, and then shows a page similar to Figure 3 where the user has to authorize or cancel the request. If the OAuth client application is a native mobile client app on a smartphone, it will launch an embedded web browser or web view for this step to interact with the user

5 Figure 3 SAP HANA Cloud Platform OAuth 2.0 Authorization Server s Authorization Page If the user confirmed the request by clicking on the Authorize button, the AS sends back an HTTP response response with status code 302 (HTTP Redirect) and provides an additional, client application-specific URL in URL in the Location header field. The web browser on the mobile device makes a second request to the new new URL specified in the Location field, which contains the authorization code intended for the native client client application. In order to capture the code when the AS sends a response to this client-specific redirection URL, the native client application has to intercept this event. Section 5

6 3. Integration with the Corporate IdP on page 9 explains in more detail how this can be done in a native mobile client app based on the Apache Cordova 5 platform. 4. After the authorization code has been successfully received by the client application, it uses the code to request the OAuth access token from the AS. If the authorization code is still valid (it only has a limited lifetime), the AS responds back with an access token and, optionally, a refresh token. Like the authorization code, the access token can also have a limited lifetime. After its expiration, the refresh token can be used by the client application to retrieve a new access token. By passing the access token in the Authorization header field with each request, the client application is now now able to invoke the OAuth-protected web API exposed by the resource server. Section 5 6

7 5. Protection of xleave s web API on page 14 explains what needs to be configured by the developer to protect the API with OAuth. In SAP HANA Cloud Platform, applications can protect their web API using OAuth 2.0 and the authorization code grant flow according to the final version of RFC To do so, the developer of the Cloud application has to configure certain settings in the application s web.xml deployment descriptor. There is no need to write additional application code or even develop your own AS. All of this is taken care by the platform, which provides the following main components: A Servlet filter class in the SDK 6. The filter can be applied to the URLs of the Cloud application s web API to check if the requests contain a valid OAuth token to access the protected resources. The filter can be optionally configured to specify a set of scopes that must have been authorized by the user to successfully invoke the API. Scopes are basically permissions that can be used to implement fine-grained access control for the protected resources. For the business scenario in this tutorial, the sample application to manage employee leave requests in the Cloud defines two scopes for viewing and creating leave requests. An OAuth 2.0 AS which exposes two endpoints for OAuth-enabled client applications: An authorization endpoint to obtain the authorization code after successful authentication of the resource owner A token endpoint for requesting the access token (with a valid authorization code) The AS also verifies access tokens received by the Cloud applications. The integration is done by the Servlet filter and no additional coding is required. It also hosts the authorization page (Figure 3) and the web interface for end users to manage their tokens as shown in Figure 4. From here they can revoke a token issued to one of their client applications at any point in time and thus deny access to their data on SAP HANA Cloud Platform immediately. Figure 4 End-user interface to manage tokens issued to client applications Administration interfaces in the Cockpit 7 of the SAP HANA Cloud Platform to let the account operator register client applications and scopes for Cloud applications. Before a client application can request an access token for a specific scope, the account operator has to register the client with the AS, which results in a unique identifier (client_id) issued for it. Each registered client is assigned to a Cloud application deployed in the account, and for each Cloud application, the account operator can register the scopes the client can be authorized for. Delegated Authentication

8 Figure 2 shows that the user at no point in time passes her username and password to the client application. Instead, she only authenticates with her credentials at the AS in step 2 before authorizing the client. On SAP HANA Cloud Platform, the AS cannot verify the user s credentials. Instead, it delegates this task to the trusted Identity Provider (IdP) of the user s account. By default, this is the SAP ID Service 8. SAP s public IdP in the Cloud is also used by other SAP Cloud solutions and web sites (e.g. the SAP Community Network, SAP JAM). Depending on the account s trust settings, the AS may also delegate the user s authentication to her company s corporate IdP. In this case, the user s device obviously needs to be connected to same network as the IdP. Otherwise, the AS won t be able to delegate the user s web browser to the corporate IdP for authentication. For corporate data access from a native mobile client app running on the employee-owned smartphone ( Bring Your Own Device, BYOD), corporate security policy usually blocks connectivity from those devices to the corporate network, which might even apply to corporate-issued devices as well. In this case, the AS cannot send the authorization code as a redirect response (Figure 2, step 3) to the client. Instead, it has to be transferred differently from the AS to the client application running on the device, e.g. via a Quick Response (QR) Code generated by the AS and scanned on the device. Section 8 8

9 Integration with the Corporate IdP on page 9 looks at this scenario in more detail. 9

10 Why OAuth? Rather than relying on the user s password to access the web API, OAuth uses an access token, which gives one client application access to a specific Cloud application s web API on behalf of a single user, maybe even limited to a scope. If the access token falls into the wrong hands, the potential damage for the legitimate owner is significantly lower compared with a stolen password, which is like the user s master key to get access to a much larger number of applications and services. BUSINESS SCENARIO This tutorial will implement a solution for BestRun Inc., a fictitious company that sells PCs and accessories. BestRun wants to increase cloud computing and mobile adoption for its core business functions. As a pilot project, BestRun s business application to manage employee leave requests, xleave, will be deployed on SAP HANA Cloud Platform. Figure 5 Setup of the Business Scenario BestRun wants to support two main use cases for its employees to access xleave: With a regular web browser from their desktop or laptop which is connected to the corporate network. Therefore, the Cloud application can delegate the employee to the corporate IdP for authentication and Single Sign-On (SSO). The protocol used by SAP HANA Cloud Platform to integrate with the IdP is the Security Assertion Markup Language (SAML 9 ) 2.0, a widely adopted security standard which has been specified in 2005 by OASIS, a global consortium for web standards. The SAML 2.0 protocol addresses web browser-based SSO across different networks and security domains. Important to notice is that the use of SAML requires the user agent (i.e. the user s client application to access the SAML-enabled application) must understand HTML and JavaScript to automate the protocol s message flow between the application(s) and the IdP. Thus, SAML is very well-suited for SSO to cloud applications when using a web browser, but lacks support for other types of clients such as the SAP GUI, native desktop or mobile client apps. More information on SAML 2.0 and its use in SAP HANA Cloud Platform for SSO and Identity Federation can be found in the whitepaper Cloud Single Sign-On and On-Premise Identity Federation with SAP HANA Cloud Platform

11 With a hybrid mobile client application running on the employee s smartphone. Hybrid mobile client apps are developed without any native code (Java, Objective-C, etc). Instead, they use a common programming model and APIs provided by an Application Container which allows portability of the app across mobile platforms. The hybrid mobile client app used in this tutorial runs in the Apache Cordova 11 container, a free and open source project available for Android, Blackberry, ios and others under the Apache License, Version 2.0. Cordova lets the developer write an app using common web technologies such as HTML, CSS and JavaScript, and offers an API to access native device function such as the camera or address book. Like regular native apps, Cordova-based apps can be installed from the device s app store. This tutorial uses Cordova to run the xleave mobile client app on an Android device. The screens ( views ) and business logic of the app are implemented with JavaScript, jquery and the SAPUI5 Mobile library 12, which provides a rich framework of mobile UI controls. Although not implemented with device manufacturer s SDK, the app feels and behaves like a native app, and the mobile client app developers can re-use their skills on common web technologies. Native and hybrid mobile client apps can easily act as a simple HTTP(S) client to consume RESTful web APIs exposed in the Cloud. However, protecting those APIs with SAML would require the client app to behave like a web browser in order to relay the SAML protocol messages between the Cloud application and IdP, using techniques like HTTP Redirect and POST, HTML page rendering and JavaScript execution. But a typical HTTP Client component such as the Java-based Apache HTTPComponents 13 used by a mobile client app to access the RESTful APIs is not a browser. It is a client side HTTP transport library with the main purpose to transmit and receive HTTP messages, but not to process content or execute JavaScript embedded in HTML pages. The complete source code for this tutorial can be downloaded from The download contains two archive (.zip) files: xleave-sources.zip for the xleave SAP HANA Cloud Platform application, and xleavemobile-sources.zip for the Android mobile client app. Mobile use case Therefore, the mobile use case is this scenario a good example where OAuth helps to secure and simplify the access from a non-browser based client to web APIs in the Cloud: It allows the mobile client app developer to use a regular HTTP Client component for consuming the RESTful APIs. The Cordova-based app in this scenario uses the well-known JavaScript library jquery 14 for this purpose. With each API call, a valid OAuth access token must be passed by the client in the HTTP Authorization header, which is verified by the AS in the Cloud before the protected resources (e.g. the user s leave requests) are returned to the mobile client app. This also means that the app developer has to think about a secure place where to store the access token on the device. Although one could also protect the web APIs in the Cloud with HTTP Basic Authentication on SAP HANA Cloud Platform, the impact of a stolen (corporate) username and password is much higher than from a stolen access token, due to the narrow scope of the token. Thus, OAuth is the recommended way for this scenario. If the mobile client app got compromised and the access token was stolen, the user or operator of the SAP HANA Cloud Platform account can deny the access granted to the app immediately by revoking the token via the web interface of the AS or the Cloud Cockpit

12 Integration with the Corporate IdP The corporate IdP in Figure 5 is responsible for authenticating the employees in both use cases of the scenario when they access the Cloud, be it from a web browser or the mobile client app. This means that as part of step 2 in Figure 2, the employee has to authenticate against the corporate IdP from her smartphone when she authorizes the mobile client app to act on her behalf. When the mobile client app sends the authorization request (step 1, Figure 2), the AS will redirect the employee based on the SAML protocol to the trusted corporate IdP configured for BestRun s SAP HANA Cloud Platform account. To allow the user entering their credentials in the IdP s HTML login page, a Cordova-based app can launch the InAppBrowser 15, which is a built-in web browser for apps that can be integrated with a simple API. For example, the native app launching the InAppBrowser can intercept the loading of a page by registering a listener (function) for this event. This allows the app to capture the authorization code returned in step 3 of Figure 2 by comparing the URL of the currently requested page with the client-specific redirection URL. If it the URLs are the same, the app can extract the authorization code from the request URL parameter with name code and close the InAppBrowser control. Next, it can use the authorization code to request the access token from the AS. To successfully complete the authorization code grant flow in the mobile use case, the device needs connectivity to the corporate network. Otherwise the InAppBrowser launched by the mobile client app would not be able to redirect the employee to the IdP s login page for authentication. Although BestRun s corporate security policy permits access from company-issued devices to the corporate network, it does not allow employee-owned devices to connect to it. So for employees bringing their own device ( BYOD ), an alternative way to login to the IdP, obtain the authorization code from the AS, and passing it back to the mobile client app, needs to be implemented. How this can be achieved with SAP HANA Cloud Platform is shown in

13 Figure 6: 13

14 Figure 6 QR Code-based Authorization Code Grant Flow 1. The employee (single-) signs on from a corporate network-connected desktop via the corporate IdP at the SAP HANA Cloud Platform AS end user UI. 2. From there the employee can generate an authorization code for a selected client application and (set of) scope(s). Instead of typewriting the long string on the mobile device, the AS UI also generates a Quick Response (QR) Code for the authorization code, which can be scanned from the desktop s monitor with a QR Code scanner app installed on the mobile device. 3. After successful scanning the authorization code is copied into the device s clipboard, from where the mobile client app can directly take it or store it temporarily in its configuration settings. 4. In the last step, the mobile client app calls the AS to issue a new access token by passing the QR Codescanned authorization code in the request. With this approach, the employee authenticates at the IdP from the desktop and no longer from the mobile device. The mobile device only requires Internet connectivity to request the access token from the AS on SAP HANA Cloud Platform. To simplify the setup of the corporate IdP, this tutorial uses the local test IdP 16 of the SAP HANA Cloud Platform local runtime instead of a productive IdP in your landscape. Although this lightweight IdP is only intended for testing purposes, it fully supports the SAML 2.0 protocol to enable end-to-end testing when the application is deployed in the Cloud. Therefore the basic administrative tasks to setup SSO and Identity Federation with the test IdP are the same as with a productive IdP. Integration with the SAP HANA Cloud Platform OAuth 2.0 AS According to Cordova s main configuration file config.xml in the xleave mobile client app, the start page of the container is set to index.html which executes first the SAPUI5 Application.js. From there, the application instantiates the AppView which holds the sap.m.app control that serves as root container for all mobile screens and their SAPUI5 controls. Figure 7 shows the application s assets directory which contains the files for the three pages of the app: Home, Overview and Create for new leave requests. Each page is represented by a view.js file containing the SAPUI5 controls and a controller.js file handling the view events, and thus follows the model-view-controller (MVC) concept. Figure 7 Project structure of the xleave mobile client app Figure 8 shows the home screen (HomePageView.view.js) of the xleave mobile client app. When launching the app for the first time, the employee has to authorize it by selecting the corresponding item from the Settings menu

15 Figure 8 Starting the OAuth client authorization in the xleave mobile client app This starts the OAuth authorization code grant flow by sending the authorization request (step 1 in Figure 2) to the SAP HANA Cloud Platform AS. Because the user will be asked to authenticate at the IdP from the mobile device, the mobile client app launches the above-mentioned InAppBrowser by calling window.open as follows: iab = window.open(authorizationurl, "_blank", "location=no"); The first parameter points to the URL opened by the device s web browser and where the request is sent to. It has to follow the account-specific pattern name>.<landscape domain>/oauth2/api/v1/authorize to make sure that the account s default IdP will be used to authenticate the employee. According to the OAuth 2.0 specification, the authorization request 17 passes the following request parameters in the URL: response_type: Has to be code to instruct the AS to return an authorization code after successful authentication of the employee (resource owner) and confirmation of the client s authorization request client_id: The unique identifier of the mobile client app that the authorization server issued when the account operator registered the app in the Cloud Cockpit redirect_uri: The mobile client app s redirection endpoint that has been previously established with the AS during the client registration process. The AS will redirect the InAppBrowser to this URI with the authorization response (step 3 in Figure 2) scope: The scope of the access request. Any values specified here have to be registered beforehand by the account operator in the Cloud Cockpit for the Cloud application the client is assigned to. Because the AS authorization endpoint requires authentication, the employee will first have to authenticate at the IdP trusted by the account, specified in the <account_name> section of the URL. If the trust settings were not modified by the account operator, the SAP ID Service as the default IdP authenticates the employee on the device as shown in Figure 9. In this tutorial, the local test IdP of the SAP HANA Cloud Platform local runtime is used for this step, representing a corporate SAML 2.0-compliant IdP

16 Figure 9 Delegated authentication to the account s trusted IdP (here SAP ID Service) on the mobile device when the authorization request is sent to the OAuth AS To intercept the response sent by the AS, the mobile client app registers an event listener callback function that is called whenever the InAppBrowser starts to load a new URL: iab.addeventlistener('loadstart', this.iabloadstart); If the event s URL equals the mobile client app s redirect URI, it has to be the authorization response 18 from the AS which includes a code parameter with the authorization code. A sample response looks like the following example: HTTP/ Found Location: Once the authorization code is retrieved in the callback function, the request for an access token can be issued to the AS token endpoint, which again follows an account-specific URL pattern: name>.<landscape domain>/oauth2/api/v1/token

17 Due to the fact that the access token request (step 4 in Figure 2) does not require the employee to further interact with the AS, it is sent by the mobile client app as a direct REST call to the above token endpoint, using the ajax-method from the popular jquery JavaScript library which comes with SAPUI5: jquery.ajax({ url : tokenendpoint, type : "POST", data : postparams, contenttype : "application/x-www-form-urlencoded", success: function(result, textstatus, jqxhr) { console.debug("access Token Response successfully received: " + JSON.stringify(result)); var oauthaccesstoken = result.access_token; sap.m.messagetoast.show("successfully authorized the client application."); setpreference("accesstoken", oauthaccesstoken); }, error: function(jqxhr, textstatus, errorthrown) { // exception handling... } }); All of the application logic discussed so far to retrieve the authorization code and access token from the AS is implemented in the HomePageController.controller.js file of the mobile client app. Currently the access token is stored unencrypted in the app s shared preferences to persist across user sessions. For productive usage, this may not fulfill security requirements and needs to be improved. Finally, when the mobile client app is making a call to the OAuth-protected web API of the xleave application, it passes the access token in the HTTP Authorization header according to RFC The following code sample shows again how the ajax-method from jquery is used for this purpose. jquery.ajax({ url : resourceurl, type: "GET", async: false, headers: { "Authorization": "Bearer " + accesstoken, }, success: function(result) { // return the protected resources }, error : function(jqxhr, textstatus, errorthrown) { // error handling } }); The actual resource URL of this call to the web API is determined by the SAP HANA Cloud Platform application. The next section explains in more detail how this is done

18 Protection of xleave s web API As illustrated in Figure 5, xleave is accessible from the web browser on the corporate desktop and the mobile client app on the employee s smartphone. Similar to the mobile UI, the web (browser) interface is also build with SAPUI5. As a client UI technology based on JavaScript, CSS and HTML5, the SAPUI5 web UI runs in the browser and fetches business data via RESTful web APIs exposed by the server where the SAPUI5 web application has been loaded from. Contacting a different server from the web browser UI is not possible due to the browser s same origin policy 20 which prevents the loss of data confidentiality or integrity. For the mobile client, those restrictions do not apply, because the SAPUI5 library is not executed in a web browser, but in the Cordova container which makes it behave like the native app. The mobile client app and the web application user interfaces both have in common that they consume RESTful APIs of the xleave application which are exposed under different URL paths as shown in

19 Figure 10. The xleave SAP HANA Cloud Platform application uses the Apache CXF 21 framework to define the RESTful service interfaces for the APIs, and the EclipseLink 22 project to use JPA for persisting the employee s leave requests in the cloud DB

20 Figure 10 xleave Application High-Level Architecture Based on the type of client and its preferred authentication method, the security settings in xleave s web.xml for the two API URL paths have to be configured as follows: /web/leaverequests: The RESTful API for the xleave web application is protected with SAML 2.0 (<auth-method> set to FORM) because it is called from the SAPUI5 JavaScript code which runs inside the employee s browser on the corporate desktop. With the welcome file list (<welcome-file-list>) set to the index.jsp page that is also protected by SAML 2.0, the employee s web browser gets redirected to the trusted IdP when accessing the application s root URL ( Upon successful authentication at the IdP and SSO to the Cloud, a login session cookie (JSESSIONID) for the xleave application is set in the web browser, which is used for all subsequent REST calls made to the /web/leaverequests web API by the SAPUI5 JavaScript UI. <welcome-file-list> <welcome-file>index.jsp</welcome-file> </welcome-file-list>... <login-config> <auth-method>form</auth-method> </login-config> <security-constraint> <web-resource-collection> <web-resource-name>protected Area</web-resource-name> <url-pattern>/web/*</url-pattern> <url-pattern>/js/*</url-pattern> <url-pattern>/index.jsp</url-pattern> </web-resource-collection> <auth-constraint> <role-name>employee</role-name> <role-name>manager</role-name> </auth-constraint> </security-constraint> 20

21 /api/v1/leaverequests: Any API calls made by the SAP UI5-based mobile client app to this endpoint require a valid OAuth 2.0 access token, which the xleave application has to pass to the Authorization Server for validation. From the developer s perspective, there is no additional coding required to protect the API. Instead, usage of the Servlet filter class com.sap.cloud.security.oauth2.oauthauthorizationfilter that comes with the SAP HANA Cloud Platform SDK has to be declared and configured in xleave s web.xml: <filter> <display-name>oauth scope definition for viewing leave requests</display-name> <filter-name>oauthviewrequestsscopefilter</filter-name> <filter-class>com.sap.cloud.security.oauth2.oauthauthorizationfilter</filter-class> <init-param> <param-name>scope</param-name> <param-value>view-requests</param-value> </init-param> <init-param> <param-name>http-method</param-name> <param-value>get</param-value> </init-param> <init-param> <param-name>user-principal</param-name> <param-value>true</param-value> </init-param> </filter> The scope parameter in this sample further restricts access to the API protected by this filter declaration to the scope view-requests. This means that an access token send with the API call must have been issued based on an authorization code for which the employee granted the client access under the scope to view her leave request. Because the scope parameter in this declaration only accepts a single value that must conform to the valid scope name syntax specified in Section in RFC6749, each scope and mapped API requires a different filter declaration in the web.xml. Thus, for the scope to create new leave requests ( create-requests ), another filter with name OAuthCreateRequestsScopeFilter is declared: <filter> <display-name>oauth scope definition for creating leave requests</display-name> <filter-name>oauthcreaterequestsscopefilter</filter-name> <filter-class>com.sap.cloud.security.oauth2.oauthauthorizationfilter</filter-class> <init-param> <param-name>scope</param-name> <param-value>create-requests</param-value> </init-param> <init-param> <param-name>http-method</param-name> <param-value>post</param-value> </init-param> <init-param> <param-name>user-principal</param-name> <param-value>true</param-value> </init-param> </filter>

22 Besides their different scope values, both filter declarations also make use of the http-method parameter, which allows to further restrict the API access to a specific HTTP method following best practices for RESTful services. For the read-only operation to view the employee s leave requests, the OAuthViewRequestsScopeFilter specifies the GET method, whereas to create new leave request require the support for HTTP POST requests. The user-principal parameter specifies whether or not the resource owner's (employee s) user id is passed as the user principal name in the request in case of successful authorization. With this parameter set to true, (existing) application code can continue to use the standard Java EE API request.getuserprincipal() to retrieve the current authenticated user s id. In this context it is important to note that server-side application code using request.isuserinrole(<role name>) won t return the current user s assignment to the specified role if it is invoked by an OAuth client. For OAuth, scopes define the permissions given to client on behalf of the user. Finally, both filter declarations must be mapped to the URL path of the protected API for mobile client apps by specifying the standard filter mapping in web.xml: <filter-mapping> <filter-name>oauthviewrequestsscopefilter</filter-name> <url-pattern>/api/v1/leaverequests</url-pattern> </filter-mapping> <filter-mapping> <filter-name>oauthcreaterequestsscopefilter</filter-name> <url-pattern>/api/v1/leaverequests</url-pattern> </filter-mapping> Prerequisites and Requirements To deploy the xleave application on the SAP HANA Cloud Platform, you need a (free) trial 24 or a productive 25 account. You can download 26 the complete source code (xleave-sources.zip in the download archive) and import it as a project in Eclipse with File Import Archive file The SAP HANA Cloud Platform tools 27 can be used to deploy the application to the Cloud. Alternatively, the download also contains a WAR file of the application, which can be deployed with the SAP HANA Cloud Platform Console Client neo.bat (Windows) or neo.sh (Linux) and the deploy command, e.g. neo deploy -s c:\xleave.war -a <your account name> -h hanatrial.ondemand.com -u <your SAP ID Service user ID> -b xleave To run the xleave mobile client app on the local development system, it is required to install the Android DeveloperTools (ADT). The bundle 28 includes Eclipse and the ADT plugin, the Android Platform and SDK tools, which includes the mobile device emulator, and the latest Android system image for the emulator. The emulator is used throughout this tutorial to run the xleave mobile client app and test the end-to-end scenario on the local development system. To avoid installing two Eclipse IDEs, it is also possible to run the SAP HANA Cloud Platform tools and ADT plugins side-by-side in a single Eclipse instance. The complete source code and project files for Eclipse of the xleave Mobile client app are also included in the download archive 29 (xleavemobile-sources.zip). Extract the archive and import the xleavemobile project with File Import Existing Android Code into Workspace. A new Android Virtual Device (AVD) must be

23 created with the AVD Manager (Window Android Virtual Device Manager) to run the application with the emulator. Figure 11 shows the recommended settings. Figure 11 AVD settings for the xleave Mobile client app It is also recommended to install the Intel Hardware Accelerated Execution Manager 30 to improve the performance of the Android emulator when running an Intel-based android system image. The next five chapters are a step-by-step guide through the scenario, starting with running the scenario on the local SAP HANA Cloud Platform runtime before deploying the xleave application to the Cloud and accessing it with the mobile client application

24 STEP 1: RUNNING THE MOBILE SCENARIO ON THE LOCAL SAP HANA CLOUD PLATFORM RUNTIME As a first step in this tutorial, the complete mobile use case is configured on the local SAP HANA Cloud Platform runtime. This includes setting up a local test user, registering the xleave mobile client app and scopes on the local OAuth AS, and configuring the xleave mobile client app to request the local AS endpoints and the xleave web API. Finally, the xleave mobile client application is launched in the Android emulator and authorized by a test user on the local OAuth AS to view and create leave requests on his behalf. What to do What you will see If not already done so, please create a local SAP HANA Cloud Platform runtime in Eclipse by opening File New Other and selecting Server from the list. Click Next. Select SAP HANA Cloud Platform local runtime from the list and click Next. 24

25 Set the HTTP port to a free port number on your development system (e.g. 8081). Click Next. Select the xleave application from the Available: list of resources and click on Add > to move it the right side (Configured:). Click on Finish. Doubleclick on the new Server to open its properties. On the Users tab, click on the + button to add a new local test user. 25

26 Add a new user as follows: User ID: jdoe Password: Abcd [email protected] First name: John Last name: Doe Click OK. Click on the + button for the Attributes to add another user profile attribute. Add a new attribute with the following data: Name: department Value: Sales Click on OK. Click on the + button for the Roles to assign the local test user to a web role defined by the xleave Cloud application. 26

27 Enter Employee for the Role name and click OK. Next, press Ctrl+S to save the new local test user settings. On the Servers View, select the new SAP HANA Cloud Platform local runtime and click on the Play button to run the server (or press Ctrl+Alt+R). Wait until the status has changed from Stopped to Started, Synchronized. To test if the web application is working, open a web browser and enter the URL Login with your local test user credentials (jdoe/abcd1234) against the SAP HANA Cloud Platform local runtime. Click on New request. Create a new leave request and click on Send. Afterwards, the new leave request appears in John Doe s list. Open a new tab in the web browser and access the OAuth 2.0 local runtime on the local SAP HANA Cloud Platform runtime with To register the xleave mobile client app with the OAuth 2.0 local runtime, click on the link Client Registration 27

28 Register a new client as follows: Client Name: xleavemobile Client Description: xleave Mobile Client App Client Type: public Client Redirect URI: Click on Register. Write down the generated Client ID or copy/paste it to a text editor. You will have to configure the Client ID in the mobile client app settings later. Click on Home. Register the required scopes for the mobile scenario by clicking on the Scope Registration link. Enter view-requests for the Scope ID and View leave requests for the Scope Description. Click on Register to complete this step. Next, click on Register More to create a second scope: Scope ID: create-requests Scope Description: Create leave requests As a result of the scope registration you should now see a list like this. Click on Home. 28

29 You are now ready to test the mobile scenario on the local development system. From the Eclipse IDE, launch the xleave mobile client application in the Android emulator by right-clicking on the xleavemobile project and selecting Run As 1 Android Application from the context menu From the Android Device Chooser dialog, select the previously created AVD (see Figure 11 for details) and click on OK. When the xleave mobile client app has started, click on the Settings icon on the top right corner. Select Client settings from the menu. 29

30 Click on the settings entry with label OAuth2 Token Endpoint and change port in the URL to the port number of your SAP HANA Cloud Platform local runtime (e.g. 8081). Note: The IP address is a special alias to your host loopback interface (i.e., or localhost) Click OK to save the new configuration. Repeat the step above for the entries with label OAuth2 Authorization URL and Resource URL. Click on the setting with label Client ID and enter the value you wrote down or copied to a text editor earlier when you registered the client app with the local OAuth AS. Click OK to save the new configuration. 30

31 Click on the entry with label Scopes and enter the two scopes you registered before for the xleave Cloud application: view-requests createrequests Click OK to save the new configuration. Press ESC to return to the mobile client app main page. Select Authorize Client from the Settings menu to retrieve a new access token from the local AS. To obtain the authorization code from the local AS, the user has to authenticate against the SAP HANA Cloud Platform local runtime. To authenticate the user, enter the local test user s credentials jdoe / Abcd1234 in the User and Password fields. Click on Log in. 31

32 The Authorization Page of the local AS lists the scopes the client requested, and asks the authenticated user (jdoe) to authorize the client. Click on Authorize. As a result of the authorization, the client can request an access token from the local AS. Upon successful retrieval a status message is shown. To test the granted authorization with the mobile client app, click on the Vacation menu item and enter some data. Click on Submit. You see a message that confirms the successful creation of your new leave request. 32

33 Click on the menu item Current leave requests. In the list of current leave requests, the new vacation request just created by the mobile client app on your behalf is successfully retrieved using the application s web API. Press ESC or click on the back arrow to return to the main screen. Invoking the web API without a valid access token results in an HTTP 403 (Unauthorized) response from the xleave application. You can try so by opening a web browser on the desktop and entering >/xleave/api/v1/leaverequests 33

34 STEP 2: DEPLOYING XLEAVE IN THE SAP HANA CLOUD PLATFORM TRIAL ACCOUNT Next you start with taking the scenario to the Cloud by deploying the xleave application in your SAP HANA Cloud Platform trial account. What to do What you will see In Eclipse, click on New or select File New Other Select Server and click Next. Select SAP HANA Cloud Platform as the server type from the list. Change the Server s host name to hanatrial.ondemand.com. Click Next. 34

35 Enter the following data: Application name: xleave Account name: <your trial account name> User name: <your SAP ID Service user ID or address> Password: <your SAP ID Service password> Click on Next. Select xleave from the list of Available applications, and click on Add > to move it to the right (Configured). Click on Finish. Select the new server from the list and click on the Start button (or press Ctrl+Alt+R) to deploy and run the application in your SAP HANA Cloud Platform trial account. Wait until the status changed from Stopped to Started, Synchronized. 35

36 STEP 3: CONFIGURING THE MOBILE SCENARIO IN THE CLOUD For invoking the xleave web API in the Cloud, the following configuration steps are required: Registration of the xleave Mobile Client app with the OAuth AS in the Cloud Registration of the scopes with the OAuth AS in the Cloud Configuration of the trust relationship for the local test IdP, which takes over the role of the corporate IdP in this tutorial What to do What you will see Open a web browser and go to m. On the SAP HANA Cloud Platform landing page, click on Log on and enter your SAP ID Service credentials. After successful logon, click on the xleave application in the list of Applications. 36

37 From the application content, select the OAuth menu entry. Click on Register new Client. Enter the following data for the new OAuth client: ID: Overwrite the generated ID with xleavemobileclientapp Redirect URI: Name: xleave Mobile App Description: xleave Mobile Application Click Translations to maintain the translations of your client s name and description for other languages. Click Add. 37

38 Add German and Name: xleave Mobile App Description: xleave Mobile Anwendung Click Close. Click Save. Switch to the Scopes tab and click on New Scope. Register the following scope: ID: view-requests Description: View leave requests Click Save. Repeat the previous step for the second scope: ID: create-requests Description: Create new leave requests Go back to the account level by clicking on your account object. 38

39 Select the Trust settings from the Content menu. Click Edit on the tab for the Local Service Provider of your trial account. Switch the Configuration Type from Default to Custom. Click on Generate Key Pair to generate a new Signing Key pair for your trial account s service provider. 39

40 Click Save and confirm the message box with OK. Click on the Get Metadata link to download your Service Provider s SAML 2.0 metadata file. This file contains the information displayed on this page in an interoperable XML format which is later needed to automate the trust setup with the local test IdP. Open a new tab in your web browser and download the local test IdP s SAML 2.0 metadata file by opening the URL etadata Set <port> to the port number of the SAP HANA Cloud Platform local runtime (e.g. 8081). The file localidp-metadata.xml is stored in your Download folder. It will be used next to establish the trust relationship to the local test IdP in your SAP HANA Cloud Platform trial account. Go back to the SAP HANA Cloud Platform Cloud Cockpit, and switch to the Trusted Identity Provider tab. Click on the Add Trusted Identity Provider link. 40

41 Click Browse Open the downloaded localidpmetadata.xml file. The form fields are populated automatically from the content of the file. Change the hostname of the Single Sign-on URL and Single Logout URL from localhost to (see red arrows in the screenshot on the left side). Note: This is only required to test the mobile scenario with the Android emulator in the next step, because the emulator uses this alias to your host loopback interface. For testing the web browser scenario in the Cloud, localhost must be used. Click on Save & Close. You have added successfully the trust relationship to the local test IdP running on your SAP HANA Cloud Platform local runtime. Next, you need to establish the trust relationship in the other direction. Open the Download folder, select the downloaded Service Provider metadata file with name https--- hanatrial.ondemand.com-<your account name>-metadata.xml, and press Ctrl+C to copy it in the clipboard. 41

42 Go to the Eclipse IDE, and open the folder Servers SAP HANA Cloud Platform local runtime-config config_master com.sap.core.jpaas.security.saml2.cfg localidp in the Project Explorer. If you don t see the localidp subfolder, press F5 to refresh the directory structure. Press Ctrl+V to copy the metadata file in the localidp folder. 42

43 STEP 4: RUNNING THE MOBILE SCENARIO IN THE CLOUD With the required OAuth settings in the Cloud, the xleave mobile client application will be reconfigured in this step to access the web API and OAuth AS endpoints in the Cloud. Note: If you are behind a (corporate) firewall and require a proxy to access the xleave application deployed on SAP HANA Cloud Platform from your development system, the emulator has to be configured 31 accordingly. What to do What you will see Open the Settings menu in the xleave Mobile Client app and select Client settings. Click on Client ID and change its value to the xleave mobile client app s client id xleavemobileclientapp that was registered in the previous step. Click OK. Click on the settings entry with label OAuth2 Token Endpoint and change the URL to your account-specific token endpoint of the OAuth2 AS in SAP HANA Cloud Platform. It follows the URL pattern <account_name>.hanatrial.ondemand.c om/oauth2/api/v1/token for trial accounts. Lookup the Token Endpoint URL for your account in the SAP HANA Cloud Platform Cockpit by clicking on OAuth in the account-level menu

44 Change the value according to the Token Endpoint for your account. Click OK. Click on the settings entry with label OAuth2 Authorization Endpoint and change the endpoint to your accountspecific authorization endpoint of the OAuth2 AS in the Cloud. It follows the URL pattern <account_name>.hanatrial.ondemand.c om/oauth2/api/v1/authorize for trial accounts. Lookup the Authorization Endpoint URL for your account in the SAP HANA Cloud Platform Cockpit by clicking on OAuth in the account-level menu. Click OK. Click on the settings entry with label Resource URL and change the URL to the xleave cloud application deployed in your SAP HANA Cloud Platform trial account. It follows the URL pattern l.ondemand.com/xleave/api/v1/leavere quests. Click OK and ESC to return to the xleave mobile client app main screen. 44

45 From the Settings menu, select Authorize Client to authorize the xleave Mobile Client app with the AS in the Cloud. Based on the Trust settings of your SAP HANA Cloud Platform trial account, the AS redirects you to your local test IdP to authenticate. Because the local test IdP uses the same user base as the SAP HANA Cloud Platform local runtime, you can authenticate with user jdoe, password Abcd1234. Click Log in. Now you are asked by the AS in the Cloud to confirm xleave mobile client app s authorization request to access your data in the Cloud. Click Authorize to confirm You are redirected back to the main screen and a message is shown that the xleave mobile client app has been successfully authorized, i.e. it received an access token from the Cloud AS. Click on Vacation from the main menu to create a new leave request in the Cloud. 45

46 Enter the data for your new leave request, and click Submit. A message is shown that the leave request has been successfully created. Select Current leave requests from the main screen. The new leave request is shown in the list. At any time, the user can revoke the access (token) granted to the mobile client app by accessing the AS end user UI in the Cloud. To test the access token revocation, continue with the next step. 46

47 STEP 5: RUNNING THE BROWSER SCENARIO IN THE CLOUD AND USING THE OAUTH END-USER UI Browser-based access to the xleave cloud application and AS end-user UI requires the configuration of additional identity federation settings to pass the user s attributes to the application. What to do What you will see In the SAP HANA Cloud Cockpit, switch to the Trusted Identity Provider tab in the Trust settings of your account. Click on the localidp entry to open its settings. Switch back from the Android emulator s alias to localhost by changing the Single Sign-on URL and Single Logout URL accordingly. Switch to the Attributes tab in the localidp s configuration settings. Add on the link Add Assertion-Based Attribute to pass a new attribute from the SAML Assertion to the application. 47

48 Configure the new attribute: Assertion Attribute: firstname Principal Attribute: firstname Repeat the two previous steps for the following assertion attributes: lastname lastname department department Click on Save & Close To assign user jdoe the required web role in the Cloud, select Authorizations from the menu. In the User field of the Users tab, enter jdoe and click on Show Roles. 48

49 Click Assign Select Application xleave and Role Employee. Click Save. Click Java Applications and select the xleave application from the list. Click on the Application URL. 49

50 You are redirected to the local test IdP. Enter the test user s credentials for the user (jdoe) and password (Abcd1234). Click Log in. You are logged on at the xleave application and authorized in role Employee. From the table headline, you can also see that the assertion attributes for first name, last name and department have been successfully passed through. In table, the leave request created in step 4 with the mobile client app is listed. Click the Logout button in the upper right corner. Next, you will revoke the OAuth access token for the xleave Mobile client app with the AS end-user UI. Go back to the browser tab with the SAP HANA Cloud Platform Cockpit. Click on your account name, and select the link for the End User UI listed under OAuth URLs in the OAuth accountlevel settings. A new browser tab opens, and you are again redirected to your account s trusted IdP, the local test IdP. Log on with the local test user jdoe, password Abcd1234. Click Log in. 50

51 You are logged in to the AS end-user UI. In the OAuth Tokens table, the access token issued to the xleave Mobile Client app is listed. To revoke the token, click on the Delete button in the column with label Actions. Confirm the action with OK. Next, try to retrieve the list of current leave requests with the xleave mobile client app on the Android emulator. An error message is shown that the leave requests could not be retrieved. By revoking the access token, the client application is no longer authorized to receive the leave requests on the user s behalf. Going back to the SAP HANA Cloud Platform Cockpit, an administrator s search in Authorizations Token for user jdoe s access tokens also results in an empty list. 51

52 SUMMARY This tutorial covered a complete end-to-end scenario for accessing an OAuth-protected web API of an SAP HANA Cloud Platform application. From a developer s perspective, no additional code needs to be implemented in the business application for supporting the OAuth authorization code grant flow, managing the user s OAuth access tokens, and integrating with the central OAuth AS to verify a token received from an OAuth client application. This OAuth-as-a-Service is provided out-of-the box by the platform to the applications running on top of it, and helps to simplify the implementation and security of modern, API-based web applications. 52

53 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.