SAP API Management Unit 4.4: Closer look at API Owner Policy Designer PUBLIC

Objectives After completing this unit, you will be able to: - Add Policies to existing API Proxies - Understand some of commonly used policies like - Security - Verify API Key - URL Masking - Access Control - Basic authentication - CORS (Cross-Origin Resource Sharing) - Traffic Management - Quota Handling - Spike Arrest - Caching - Mediation / protocol transformation - Raise Fault - Key Value Maps 2 2016 SAP SE or an SAP affiliate company. All rights reserved. Public 2

SAP Policy Designer Overview

Overview 1/2 The Policy Designer allows modify / enhance incoming and outgoing requests in the API Management system. A set of predefinied policies for Security, Traffic management, protocol transformation and others are available out of the box Customer specific enhancements can be implemented via custom code (e.g. JavaScript, Python, ) 4 2016 SAP SE or an SAP affiliate company. All rights reserved. Public 4

Overview 2/2 Each policy is assigned to a Flow in the call (e.g. ProxyEndpoint: PreFlow / PostFlow, TargetEndpoint: PreFlow / PostFlow) The policies are represented in a flow diagram in the center of the screen Available Policy templates can be used on the right Created Policy can be accessed on the bottom right 5 2016 SAP SE or an SAP affiliate company. All rights reserved. Public 5

API Proxy Execution Sequence Pre Flow Condition Flows * Post Flow Pre Flow Condition Flows * Post Flow Incoming Stream (Request / Inbound) Proxy End Point Route Rules # Target End Point Client Backend Outgoing Stream (Response/ Outbound ) Condition Condition Post Flow Pre Flow Post Flow Pre Flow Flows * Flows * * All conditions flows whose conditions matches # First route rule whose condition matches 6 2016 SAP SE or an SAP affiliate company. All rights reserved. Public 6

A lot of options SAP Official documentation can be found here: https://help.hana.ondemand.com/apim_od/frameset.htm Although not 1:1 compatible, documentation at Apigee is quite good & comprehensive with lots of examples, http://docs.apigee.com/api-services/reference/reference-overview-policy Additional sample policies can be found on GitHub, https://blogs.sap.com/2016/09/17/public-sap-hcpapi-management-api-proxy-github-now-available/ Often there are context variables / flow variables available that you can use; see http://docs.apigee.com/api-services/reference/variables-reference or search on apigee.com (Code completion in Editor is missleading!) 7 2016 SAP SE or an SAP affiliate company. All rights reserved. Public 7

Some general remarks Do not use special characters when working with Policies (neither in the name nor elsewere). Don t use spaces in the name. You might need to reference them later Be careful when working with the XML coding-snippets. Currently even the order of tags can be the cause of an error. 8 2016 SAP SE or an SAP affiliate company. All rights reserved. Public 8

Security Policies

Verify API Key Verify Key API Key Security API keys grant access to an API Proxy in the same way you would protect your password. Each application that a developer is subscribing gets an individual application key which can is used to authenticate the used API Proxies. This also enables the API Owner to run analytics scenarios on the API Keys 10 2016 SAP SE or an SAP affiliate company. All rights reserved. Public 10

Verify API Key Verify Key Verify API Key Policy Configure where the API Key should be retrieved from, e.g. request.queryparam.apikey => from Query ( GET ) name apikey request.header.apikey from header, name ApiKey See https://help.hana.ondemand.com/apim_od/frameset.htm?4d15a0427494452dbb42a319 e9bb420f.html http://docs.apigee.com/api-services/reference/verify-api-key-policy 11 2016 SAP SE or an SAP affiliate company. All rights reserved. Public 11

URL Masking JavaScript Protect Backend Services SAP API Management protects and hides the systems in the backend. To ensure that also the response of a service does not contain the backend server information a URL Masking can rewrite backend URLs with the API Proxy URL 13 2016 SAP SE or an SAP affiliate company. All rights reserved. Public 13

URL Masking JavaScript Java Script Policy Policy calls the actual JavaScript urlrewrite.js file Get the response.content from the context Use regular expression to replace & ignore case ( gi ) the backend server name and the path with values from APIM Put response.content back See https://help.hana.ondemand.com/apim_od/frameset.htm?5b63ed7782ab4b4ea96bf84119059039.html & http://docs.apigee.com/api-services/reference/javascript-policy 14 2016 SAP SE or an SAP affiliate company. All rights reserved. Public 14

var rc = context.getvariable("response.content"); var newstr = rc.replace(/sapes4.sapdevcenter.com:443/gi, "d046471trialtrial.apim1.hanatrial.ondemand.com"); var newpath = newstr.replace(/\/sap\/opu\/odata\/iwbep\/gwsample_basic/gi, "/d046471trial/gwsample_basic_valora2"); context.setvariable("response.content", newpath); 15 2016 SAP SE or an SAP affiliate company. All rights reserved. Public 15

Access Control Access Control Limit access to API Proxy to IP ranges In addition to protect APIs via an API Key, Access Control can be used to either explicitly allow or deny access from certain IP ranges to the API Proxies 17 2016 SAP SE or an SAP affiliate company. All rights reserved. Public 17

Access Control Access Control Access Control Policy Set MatchRules to ALLOW or DENY access from certain SourceAddresses, Mask: 8,16,24,32 keep the first x bits See https://help.hana.ondemand.com/apim_od/frameset.htm?3f72aea27065452 7afb0a743fa52702a.html http://docs.apigee.com/api-services/reference/access-control-policy <AccessControl name="acl"> <IPRules norulematchaction="deny"> <MatchRule action="deny"> <SourceAddress mask="24">10.10.0.0</sourceaddress> <SourceAddress mask="24">10.20.0.0</sourceaddress> <SourceAddress mask="24">10.30.0.0</sourceaddress> </MatchRule> <MatchRule action="allow"> <SourceAddress mask="16">10.10.0.0</sourceaddress> <SourceAddress mask="16">10.20.0.0</sourceaddress> <SourceAddress mask="16">10.30.0.0</sourceaddress> </MatchRule> </IPRules> </AccessControl> 18 2016 SAP SE or an SAP affiliate company. All rights reserved. Public 18

Traffic Management

Quota Handling Quota Limit number of calls to API Proxy In order to control or monteize access to your API Proxies a quota can be applied. This allow to limit the number of calls in a certain period of time. In addition to limit the calls on an API Proxy the number of calls can be differentiated per API Key (which allows different applications to have different quotas) 21 2016 SAP SE or an SAP affiliate company. All rights reserved. Public 21

Quota Handling Access Control General Quota Settings: TimeUnit: second, minute, hour, day, month Inverval: number of Time Units Allow count: number of calls API Dependent Quota Settings Identifier ref="verifyapikey.checkapikey.client_id Policy Template Policy Name See http://docs.apigee.com/api-services/reference/quota-policy https://help.hana.ondemand.com/apim_od/frameset.htm?1f742c1e1a5c4a21bd839940 71ddaea0.html 2016 SAP SE or an SAP affiliate company. All rights reserved. Public 22 22

Maintain Quotas in API Product Access Control Different API Products (Tiers) can lead to different quotas (e.g. Silver has less calls than Gold ) Verify API Key Policy makes additional variables available which can be referenced verifyapikey.<apikeypolicy>.apiproduct.develo per.quota.limit verifyapikey.<apikeypolicy>.apiproduct.develo per.quota.interval verifyapikey.<apikeypolicy>.apiproduct.develo per.quota.timeunit Fixed values need to be provided as fallback! 23 2016 SAP SE or an SAP affiliate company. All rights reserved. Public 23

Raise Fault Policy Raise Fault Setting explixit custom error messages By default SAP API Management returns an Internal error HTTP Code 500 In case of Quota failure there is a specific HTTP Code 429 xxx, which can be setup via a Raise Fault policy. Obviously similar error codes could be set if required for other scenarios. 25 2016 SAP SE or an SAP affiliate company. All rights reserved. Public 25

Raise Fault Policy Access Control Previous Policy-Step: ContinueOnError = true Condition String: ratelimit.setquota.failed = "true" Policy Name RaiseFault Policy: set FaultResponse See http://docs.apigee.com/api-services/reference/raise-fault-policy 26 2016 SAP SE or an SAP affiliate company. All rights reserved. Public 26

Spike Arrest Spike Arrest Limiting number of calls in short period of time Quota handling is good to limit number of calls over a certain period of time, e.g. 1 Mio calls per month. To protect the backend system you have to ensure that these 1 Mio calls are not done within 1 minute. In addition to Quota Handling Spike arrest can limit / reduce the number of calls in a short period of time. 28 2016 SAP SE or an SAP affiliate company. All rights reserved. Public 28

Spike Arrest Spike Arrest Identifier: Similar as with Quota to ensure a per-application handling of calls MessageWeight: To distinguish between heavy and simple calls Flow Variable: ratelimit.<policyname>.failed = "true" Rate: Calls per Second (ps), Minute (pm) Per-minute rates get smoothed into full requests allowed in intervals of seconds. For example, 30pm gets smoothed like this: 60 seconds (1 minute) / 30pm = 2-second intervals, or 1 request allowed every 2 seconds. A second request inside of 2 seconds will fail. Also, a 31st request within a minute will fail. Per-second rates get smoothed into full requests allowed in intervals of milliseconds. For example, 10ps gets smoothed like this: 1000 milliseconds (1 second) / 10ps = 100-millisecond intervals, or 1 request allowed every 100 milliseconds. A second request inside of 100ms will fail. Also, an 11th request within a second will fail. See http://docs.apigee.com/api-services/reference/spike-arrest-policy 2016 SAP SE or an SAP affiliate company. All rights reserved. Public 29 29

Concurrent Rate Limit Concurrent Rate Limit Limiting number of calls concurrent calls The ConcurrentRatelimit policy helps to limit the number of connections to your backend services from API proxies running on SAP API Management. Generally in a distributed environment, many API Proxies can point to the same backend service. In such a case the backend service is flooded with requests. In order to manage traffic to backend services, you use the Concurrent Rate Limit policy. App App App App App App App App App SAP API Management Backend Systems Limit number of concurrent calls to backend 31 2016 SAP SE or an SAP affiliate company. All rights reserved. Public 31

Concurrent Rate Limit Concurrent Rate Limit Fairly simple to configure but hard to test (so no Exercise). AllowConnection: Specifies the number of connections to the backend service. TTL determins the number of seconds after which the counter is automatically decremented (in case there was not proper decrement via the response path) Distributed: specify whether the counter should be shared accross instances Not fully configurable in the UI as the policy also needs to be placed in the Fault Rules See also: http://docs.apigee.com/api-services/reference/concurrent-rate-limit-policy 32 2016 SAP SE or an SAP affiliate company. All rights reserved. Public 32

Comparison of Quota, Spike Arrest and Use it to: Don't use it to: Stores a count? Best practices for attaching the policy: Quota Spike Arrest Concurrent Rate Limit Limit the number of connections apps can make to your API proxy's target backend over a specific period of time. Don't use it to protect your API proxy against traffic spikes. For that, use the Spike Arrest policy or Concurrent Rate Limit policy. Protect your API proxy's target backend against severe traffic spikes and denial of service attacks. Don't use it to count and limit the number of connections apps can make to your API proxy's target backend over a specific period of time. For that, use the Quota policy. Yes No Yes Attach it to the ProxyEndpoint Request PreFlow, generally after the authentication of the user. This enables the policy to check the quota counter at the entry point of your API proxy. From: http://docs.apigee.com/api-services/content/comparing-quota-spike-arrest-and-concurrent-rate-limit-policies Attach it to the ProxyEndpoint Request PreFlow, generally at the very beginning of the flow. This provides spike protection at the entry point of your API proxy. Limit the number of concurrent connections apps can make to your API proxy's target backend. Don't use it to limit the number of connections apps can make to your API proxy's target backend over a specific period of time. For that, use the Quota policy. This policy must be attached in these three locations: TargetEndpoint Request PreFlow TargetEndpoint Response PreFlow TargetEndpoint DefaultFaultRule HTTP status 500 (Internal Server Error) code when Your org can optionally be configured to return an HTTP limit has been status code of 429 (Too Many Requests) instead. * reached: Good to know: Quota counter is stored in Cassandra. Configure the policy to synchronize the counter asynchronously to save resources. Asynchronous counter synchronization may cause a delay in the rate limiting response, which may allow calls slightly in excess of the limit you've set. 500 (Internal Server Error) Your org can optionally be configured to return an HTTP status code of 429 (Too Many Requests) instead. * Performs throttling based on the time at which the last traffic was received. This time is stored per message processor. If you specify a rate limit of 100 calls per second, only 1 call every 1/100 second (10 ms) will be allowed on the message processor. A second call within 10 ms will be rejected. Even with a high rate limit per second, nearly simultaneous requests may result in rejections. 503 (Service Unavailable) Keeps a count of concurrent connections per message processor. While an individual API proxy may be handling just a few connections, collectively, the connections to a set of replicated API proxies pointing to the same backend service may swamp the capacity of the service. Use this policy to limit this traffic to a manageable number of connections. Get more Quota policy Spike Arrest policy Concurrent Rate Limit policy details: 33 2016 SAP SE or an SAP affiliate company. All rights reserved. Public 33

Backend Authentication

Basic Authentication Assign Message Basic Authentication Authentice with technical user to backend Backend systems are usually protected via certain means of authentication. SAP API Management can hide this authentication (to provide a unified authentication accross different backend systems to the consumer). Basic authentication adds an authentication header to the backend call so the API Proxy can connect via a technical user. App App App App App SAP API Management Backend Systems Authentication via API Key One Technical User for authentication Step 1) the Username and password is added to a variable. Step 2) encodes and adds this variable as Basic authentciation in the header 35 2016 SAP SE or an SAP affiliate company. All rights reserved. Public 35

Basic Authentication Assign Message Basic Authentication Assign Message Allows to set variables, like a username and password See http://docs.apigee.com/api-services/reference/assign-messagepolicy Basic Authentication Retrieves and encodes information (like username and password) and sets header variables See http://docs.apigee.com/api-services/reference/basicauthentication-policy 36 2016 SAP SE or an SAP affiliate company. All rights reserved. Public 36

Caching

Caching Response Cache Caching allows API Management to cache the response from the server and return this information to a request without calling the backend system As applications make requests to the same URI, you can use this policy to return cached responses instead of forwarding requests to the backend server. Response Cache policy improves API's performance through reduced latency and network traffic. See http://docs.apigee.com/api-services/reference/response-cache-policy 39 2016 SAP SE or an SAP affiliate company. All rights reserved. Public 39

Caching Response Cache CacheKey is an identify for a cache entry. KeyFragment request.queryparm.apikey takes the APIKey (make sure to check queryparm / header) as a first identifier KeyFragment proxy.pathsuffix adds the path suffix as an additional identifier [in the exercise we will only use request.uri] TimeoutInSec defines the validity of the cache SkipCacheLookup allows to manually force a cache-refresh See: http://docs.apigee.com/api-services/reference/response-cache-policy 40 2016 SAP SE or an SAP affiliate company. All rights reserved. Public 40

CORS

Cross-origin resource sharing (CORS) A web page may freely embed images, stylesheets, scripts, iframes, videos and some plugin content (such as Adobe Flash) from any other domain. However embedded web fonts and AJAX (XMLHttpRequest) requests have traditionally been limited to accessing the same domain as the parent web page (as per the same-origin security policy). "Crossdomain" AJAX requests are forbidden by default because of their ability to perform advanced requests (POST, PUT, DELETE and other types of HTTP requests, along with specifying custom HTTP headers) that introduce many cross-site scripting security issues. CORS defines a way in which a browser and server can interact to determine safely whether or not to allow the cross-origin request. [2] It allows for more freedom and functionality than purely same-origin requests, but is more secure than simply allowing all cross-origin requests https://en.wikipedia.org/wiki/cross-origin_resource_sharing 43 2016 SAP SE or an SAP affiliate company. All rights reserved. Public 43

CORS Example Swagger / OpenAPI is a simple yet powerful representation of your RESTful API. Via http://editor.swagger.io/ API specifications can be created an tested. Testing an API from SAP API Management from swagger.io leads to an error due to a cross-origin request 44 2016 SAP SE or an SAP affiliate company. All rights reserved. Public 44

CORS Example When setting the right headers in the API via Policies, e.g. Access-Control-Allow-Origin = * The call is successful 45 2016 SAP SE or an SAP affiliate company. All rights reserved. Public 45

CORS Routing Rules Routing Rules enables to call different Target Endpoints depending on certain conditions Since in a CORS request the browser performs a request with verb OPTIONS a new Route Rule noroutes is definied which does not route the request to an endpoint See https://help.hana.ondemand.com/apim_od/frameset.htm?4dfd54a754 6c42cfb8dd157ab1355011.html 46 2016 SAP SE or an SAP affiliate company. All rights reserved. Public 46

CORS Routing Rules Routing Rules Routing Rules enables to call different Target Endpoints depending on certain conditions Since in a CORS request the browser performs a request with verb OPTIONS a new Route Rule noroutes is definied which does not route the request to an endpoint See https://help.hana.ondemand.com/apim_od/frameset.htm?4dfd54a754 6c42cfb8dd157ab1355011.html 47 2016 SAP SE or an SAP affiliate company. All rights reserved. Public 47

CORS New Proxy Endpoint Routing Rules A new preflight endpoint with Condition string request.verb == OPTIONS is added. This will be called when the browser checks if CORS support is possible. 48 2016 SAP SE or an SAP affiliate company. All rights reserved. Public 48

CORS Set CORS Headers Assign Message In the PostFlow of the ProxyEndpoint the AssignMessage policy will add the required CORS headers to the outgoing request Access-Control-Allow-Origin Access-Control-Allow-Credentials Access-Control-Expose-Headers Access-Control-Allow-Methods Access-Control-Allow-Headers 49 2016 SAP SE or an SAP affiliate company. All rights reserved. Public 49

Basic Authentication of Users

Basic Authentication Basic Authentication Basic Authentication is the simplest way to authenticate a user in a standard way. The user will be prompted to provide username and password, which will then be sent as HTTP Authorization header (base64 encoded). This mechanism does not secure the password in any way. A full basic authentication works as follows: 1. Server to send challenge for User Name and password with HTTP 401 response including header: WWW-Authenticate: Basic realm= <Name> 2. Client to provide username and password in HTTP Header: Authorization: Basic dxnlcjpwyxnz. Value is username:password encoded in base 64. 52 2016 SAP SE or an SAP affiliate company. All rights reserved. Public 52

Basic Authentication Basic Authentication To challenge the user for a password the raise fault policy is used. It will trigger when no HTTP Authorization header is set. URL: https://accounts.sap.com/service/users/password Success (200): To validate User name and Password an external identity store is used. In our case we use SAP Cloud ID (accounts.sap.com) SAP Cloud ID is accessed through a service call out. This means a rest API will be invoked with the previously supplied credentials (HTTP POST). If Successful, the status code is 200 and user details are provided. If not, the code is HTTP 401. Fault (401) 53 2016 SAP SE or an SAP affiliate company. All rights reserved. Public 53

Key Value Maps

Key Value Maps Key Value Map In API Management Key Value Maps can be used to avoid hard-coding specific values within the API Proxy. Key Value maps: Are durable Are accessible though dedicated APIs (Create, Delete, Read) Are accessible though the Key Value Map Policy Represent a collection of Keys and Values Can have the following scope: environment (only scope maintainable through API) apiproxy policy 55 2016 SAP SE or an SAP affiliate company. All rights reserved. Public 55

Key Value Map API Key Value Map Key Value Map API is part of API Portal It is OData compliant Url is: https://<apiportalhost>/apiportal/api/1.0/manageme nt.svc/keymapentries Requires CSRF Token: Authenticated Call using HEAD Verb and Header x- csrf-token: fetch Subsequent call using supplied csrf token (and all supplied cookies) Header: csrf-token: <token value> Authorization: Basic dxnlcjpwyxnz Body: { "name":"km1", "keymapentryvalues":[ { "name":"username", "value":"user", "map_name":"km1" }, { "name":"password", "value":"pwd", "map_name":"km1" } ] } 56 2016 SAP SE or an SAP affiliate company. All rights reserved. Public 56

Key Value Map Policy Key Value Map Key Value Map Policy allows: Initial Entries Put Delete Get (most common) Get assigns a key value map entry to a variable in API Management 57 2016 SAP SE or an SAP affiliate company. All rights reserved. Public 57

Thank you.