Intro
OAuth2 is finally here - being delivered with HANA SPS 09. Great! But what is the OAuth2 hype all about?
Welcome to a series of posts showing you how to use the OAuth2 authentication mechanism in HANA XS. The mechanism enables you to use APIs from providers like Google, Facebook, Twitter or any one of the others offering this authentication. Of course you will also learn how to authenticate against the HANA Cloud Platform or an ABAP server.
In this first post we will look at the prerequisites regarding your HANA XS knowledge and the theory behind OAuth itself. The next post will show you how to use the delivered Google OAuth configuration package as a first example. Follow up posts become more advanced i.e. describing how to create own configurations, how to debug outgoing requests and the like.
Currently the series contains following posts:
- OAuth2 Authentication using HANA XS – Basics (1) (start off with this one, if you are new to OAuth)
- OAuth2 authentication using HANA XS – XS OAuth client lib calling Google's API (2) (end to end description in a step by step manner)
I will try to keep things as simple as possible, without loosing advanced users with a lengthy explanation of details.
Prerequisites
This is a rather advanced topic in the area of SAP HANA XS. So if you are totally new to it (you have never heard of .xsjs, .xsapp, .xsaccess, …), here are a couple of resources to get you started:
If you already know about these, but aren’t so sure about .xshttpdest or trust stores, you may be better off with this series in the first place:
- Outbound httpS with HANA XS (part 1) - set up your HANA box to use SSL/TLS
- Outbound httpS with HANA XS (part 2) - set up the trust relation
- Outbound httpS with HANA XS (part 3) - call the https outbound service in XS server side JavaScript ...
After reading the OAuth series you will also understand the XS artifacts .xsoauthclientconfig and .xsoauthclientflavor and where they belong in the big puzzle.
So let's get started with a basic introduction to OAuth.
If you already know about OAuth I recommend to check out the chapter 'The theory behind OAuth 2.0 in HANA XS' nevertheless and advance to the next post.
Why OAuth?
OAuth is an open standard to authorization, but why is it so popular today?
Currently there is a strong trend away from a rich client or heavy weight architecture towards distributed systems with lightweight architectures based on plain text (i.e. JSON ) web services. Representational state transfer (REST) is the most popular flavor of this architectural style. And OAuth is a perfect match to this architecture. Why?
Usually a REST web service offers it’s API via Hypertext Transfer Protocol (HTTP), using it’s very standard methods (GET, PUT, POST, …) for actions to perform. This protocol, and hereby REST, is supported out of the box in practically all common coding languages. This ubiquitous support, an easier consumption compared to SOAP / WSDL based web services, the growing number of cloud scenarios and REST being a performing and maintainable architecture (please see REST's implementation constraints for details) furthermore foster this trend.
REST services often are powerful and need an advanced security concept. OAuth is a natural fit, as it
- is specifically designed to work with HTTP
- implements role based authorizations
- supports frequent and easy updates to user accounts
- is a centralized service
What is OAuth?
OAuth2 specifies a protocol enabling client/web applications to act on behalf of a user after the user explicitly granted permissions. Another web application/web service (the resource server) finally carries out the actions a client is allowed to perform. The user approves the actions by telling an authorization server that he trusts the client to do what it is asking for.
The most common way for a client to present itself to a resource server is using a bearer token, which is obtained from the authorization server and stored by the client. OAuth does not specify the token itself – only the protocol how to obtain it. To finally access a resource server the client sends a special http header in the form:
Authorization: Bearer <TOKEN_VALUE>
The token can be decoded by the resource server only (opaque to the client as well) in order to check whether client and user have permissions to access the requested resource.
This is where scopes (a key aspect of OAuth 2.0) come into play. A scope is an access range. As opposed to unlimited access - as it would be without scopes (e.g. using basic authentication) - OAuth enables an application to call services with exactly the right portion of privileges. The scopes are derived by the resource server solely by decoding the token. Other information can be encoded in the token as well. The most important values (besides the scopes) are client ID, target resource ID and the current user ID.
Prominent examples of OAuth 2.0 authorization servers are Google, Facebook and Twitter. All of them also provide resource servers (respectively Google APIs, graph API, streaming API). You will find plenty more providers at e.g. Wikipedia. Wikipedia also serves a good explanation of OAuth.
A real life example
Let's look at a real life example.
The user accesses an application in the browser. This application runs on HANA XS and needs information from another application server, e.g. SAP JAM. To access the data, JAM allows the application to authenticate its users by OAuth. For this purpose, JAM acts as authorization server and issues access tokens for the user. These are consumed by the resource server of JAM to provide access to the required services.
As a prerequisite to access resources, the first check determines whether an OAuth token is already existing for this user. This is not done directly by the application, but by the OAuth 2.0 client functionality of HANA XS. Assuming no token is available, the OAuth client initiates the token flow to the OAuth authorization server. The access token request contains the requested scopes and information authenticating both - the calling system and the end user. The resulting access token response contains the access token and additional information regarding token lifetime and granted scopes. This data is persisted for future re-use in the token storage. Now we have a token. Hence, in a subsequent call the access token is retrieved from the token storage and added to the http request enabling direct access to the resource.
The theory behind OAuth 2.0 in HANA XS
As we now know about OAuth and HANA XS, let’s see how they come together. Before continuing with a concrete example in the next post, we'll look at the theory (which you may skip, if you want to).
To connect to a remote service, an OAuth HANA XS client application uses the destination service. In analogy to the destination service in NW AS JAVA or SM59 in NW AS ABAP, it contains all configuration information required for the remote connectivity, like the target URL.
The application uses the HTTP client which facilitates the HTTP protocol. This client is initialized with an HTTP destination. If the latter is configured to use OAuth, the OAuth client is initialized for the target system. To send the HTTP request to the resource server (e.g. JAM, Google), control is passed over to the OAuth client.
The OAuth client first checks whether an adequate access token already exists for the current user and OAuth client ID combination and that this token is covering the scopes desired by the application. If no token is found, the access token request is prepared and send using a new HTTP client instance (to separate the cookie containers from the end-user's client). It contains the client and user credentials, plus the requested scopes. The list of scopes that is requested is the collection of all scopes as declared in the application configuration for this OAuth client ID. The access token response is then evaluated by extracting the access token and persisting it to the latter one to the token storage, together with the validity and the list of granted scopes. When finally calling the resource server, the HTTP request is enriched with the valid access token.
Obtaining client and current user's credentials or what about flows?
In HANA XS the client credentials are maintained during the configuration and persisted in the secure store. Depending on the OAuth flow, different ways exist how to obtain the user's credentials.
The most important flow is the authorization code flow. It’s being used by most ID providers and we are going to look at an example in the next post. To receive an access token using this flow the following steps have to be carried out:
- create a client application at the authorization provider and remember the presented credentials
- obtain an authorization code from the authorization server using these credentials and by granting permissions in the user consent
- exchange this authorization code for an access token and a refresh token
- use the access token to make API calls as long as it is valid
- get a new access token via the refresh token when the lifetime of the access token is over
Another important flow, being used by e.g. JAM, is the SAML flow. This flow involves the creation of a SAML assertion for a user. The OAuth client initializes the SAML issuer for JAM, which includes the JAM-specific SAML configuration. The SAML issuer than creates a SAML assertion for the current user. This assertion is added to the access token request.
Other OAuth flows, such as Implicit flow, Resource Owner Password Credentials or Client Credentials are currently not supported.
Conclusion
I hope you got properly equipped for the upcoming practical part and start implementing straight away.
- SAP Managed Tags:
2 Comments
