OAuth 2.0 Standard Solution with Grant Type as Password in SAP PO 7.5(with Latest Updates)

This blog portrays the OAuth2.0 authorization with grant type as ‘Password’.This is implemented in SAP PO 7.5 SPS 16 Patch 15. Lets take a tour into the Standard solution in elucidate with latest updates. ? Over to content below:

1. Introduction:

 OAuth(Open Authorization) is an open standard for access delegation, commonly used as a way for Internet users to grant websites or applications access to their information on other websites but without giving them the passwords.

   OAuth introduces an authorization layer separating the role of the client from that of the resource owner.In OAuth, the client requests access to resources controlled by the resource owner and hosted by the resource server, and is issued a different set of credentials than those of the resource owner.The OAuth 2.0 authorization framework enables a third-party application to obtain limited access to an HTTP service: 

(i) On behalf of a resource owner by orchestrating an approval interaction between the resource owner and the HTTP service  (or)

(ii) by allowing the third-party application to obtain access on its own behalf.

2. Purpose:

 The purpose of this blog is to explain OAuth 2.0 in SAP PO 7.5 SPS 16 with grant type as password.Regards to OAuth 2.0 solution worked with SAP in testing this solution and identifying bugs which resulted in correction notes published in the SAP marketplace to make this solution more robust to solve different OAuth 2.0 authentication integrations with varied systems/applications.

3. Authorization Code Grant flow:

 Below diagram depicts the Authorization Grant Flow to retrieve the access token and refresh token, POST a call to the authorization server. The client requests authorization from the resource owner and receives grant and then requests tokens by authenticating with the authorization server and presenting the grant. Authorization server validates, if valid then issues the initial access token and initial refresh token with access token expiry(lifetime in secs). 

Below diagram elucidate that the client requests the protected resources from the resource server and authenticates by presenting the access token. The resource server validates the access token, and if valid, serves the requests and retrieves the response from the protected resources.

4. SAP PO REST Adapter Configurations:

Before proceeding with the REST receiver communication channel configurations below is the Authorization server (which grants tokens) HTTP request header and HTTP request Body parameters look alike ?

HTTP Request Headers:

HTTP Request Body:

HTTP Response Body:

Below is the Resource server(which does the actual business call) HTTP request header and HTTP request Body parameters look alike

HTTP Request Headers:

HTTP Request Body:

 In the REST receiver communication channel that allows you to configure with OAuth 2.0 Client Credentials Grant and Resource Owner Password Credentials Grant. Below configurations explains only about the resource owner password credential grant type.

To Configure the REST receiver channel following are the steps below:

   1. To enable new OAuth 2.0 Grant flows, in the “General” tab, check “Authorize with OAuth” checkbox and select “OAuth 2.0 Grant Type Flow”.You can choose from the following grant flows:

• Client Credentials Grant – flow described in https://tools.ietf.org/html/rfc6749#section-4.4
• Resource Owner Password Credentials Grant – flow described in https://tools.ietf.org/html/rfc6749#section-4.3
• Important Note: Other grant flows – Authorization Code Grant and Implicit Grant and these are not supported by the REST adapter.

   2. You can configure how to use the received access token as defined in https://tools.ietf.org/html/rfc6750.

Select following values for the field “Use credentials and OAuth 2.0 access token as” :

• HTTP Header – adds the access token to the request HTTP headers in the following format “Authorization: Bearer <access_token>”
• Query Parameter – adds the access token to the resource URL in the following format: http://<host>:<port>/<resource_path>?access_token=<access_token_value>
• Important Note: This OAuth2.0 functionality extracts only the access token and not the refresh token.
• Sending access token as “Form-Encoded Body Parameter” is not supported.

3. You can configure the following parameters for OAuth 2.0 Grant Type flows:

For Client Credentials Grant:

• Authorization Server URL – the server, which will provide the access token(required).
• Scope – The scope of the access request as described in https://tools.ietf.org/html/rfc6749#section-3.3 (optional).
• Client ID – The client identifier issued to the client during the registration process as described in https://tools.ietf.org/html/rfc6749#section-2.2 (required).
• Client Secret – The client secret as described in https://tools.ietf.org/html/rfc6749#section-2.3.1 (required).

For Resource Owner Password Credentials Grant :

• Authorization Server URL – the server which will provide the access token. (required)
• Resource Owner Client ID – The client identifier as described in https://tools.ietf.org/html/rfc6749#section-2.2 (optional)
• Authorization Server Username and Password – used for authentication with Authorization server as defined in https://tools.ietf.org/html/rfc6749#section-3.2.1 (required)
• Resource Owner Username and Password – resource owner credentials as defined in https://tools.ietf.org/html/rfc6749#section-4.3.2 (required)
• Scope – The scope of the access request as described in https://tools.ietf.org/html/rfc6749#section-3.3. (optional).

4. OAuth 2.0 Additional parameters need to maintained for the remaining HTTP header and HTTP Query parameters. You can specify the “Parameter Type” to be one of the following:

• Query –  Parameter will be added to the URL query(HTTP Body).
• HttpHeader – Parameter will be added as HTTP Header.
• Important Note: As per SAP note 2721684 and 2782239 ,which denotes that in order to send ‘OAuth 2.0 additional  HTTP header parameter; with the request.Patch needs to be applied which matches the respective Support Package version(as per SAP Note 952402).It works only with >SAP PO 7.5 SPS 15 Patch 0001. With out any patch upgrade below is the error:

Error while obtaining authorization code – response code: 400 response:

{“errorCode”: “GTW-ERROR-001″,”message”: “appkey not found in Header or it’s not correct.”}

5. In the REST URL, provide the resource server URL which does the actual business API call.

6. Below is the HTTP headers of the resource server:

In the HTTP Headers, there is no necessity to enforce Authorization: Bearer <access_token>.It will be added since in ‘General tab’ it is defined use access token as HTTP header.

‘appkey‘ is a valid application key passed in HTTP Header which allows you to track your API usage per application.’Content-Type‘ is the type of representation desired at resource side.

5. Additional Feature- Resource Owner Password Credentials Grant:

When partner server does not support Authorization Basic HTTP Header which got added as Authorization: Basic <credentials> since the authorization user name and password is configured in Communication Channel. There is no configuration which is used to exclude this header before and same is raised with SAP for the additional feature.

As per OAuth2.0 standard Authentication framework, the client must not use more than one authentication method in each request.Refer: https://tools.ietf.org/html/rfc6749#section-2.3

Solution from SAP:  New module parameter is defined to the REST receiver channel that allows you to specify how the user authentication is requested from the partner authorization server.Refer SAP Note 2878625.

Note: When you use a value query do not use the field Resource Owner Client ID. This will cause the client_id twice in the query string.

Result: Now using the above Parameter name as ‘’Oauth20AutorizationServerRequestType’ and Parameter value as ‘none’ in the module configuration. Basic Authentication is now ignored from the HTTP header and dispatched as part of the HTTP body only as ‘username’ and ‘password’ appropriately to get the access_token.

Important Note: As per SAP note 2878625 which denotes that in order to send ‘OAuth 2.0 additional query or header parameter; with the request.Patch needs to be applied which matches the respective Support Package version(as per SAP Note 952402).It works only with >SAP PO 7.5 SPS 16 Patch 000014. With out patch upgrade below is the error:

Error while obtaining authorization code – response code: 400 response:

{“error_description”: “Client authentication failed”,”error”: “invalid_request”}

6. OAuth Token Caching:

PI REST receiver channel with configure OAuth 2.0 Authentication and grants type flow allows the generated Token to be reused depending on the value of the ‘expires_in‘ parameter.

The access token is usable from the moment it is generated until the number of seconds defined by expire_in elapses.

‘Expires_in’ parameter is described in https://tools.ietf.org/html/rfc6749#section-4.2.2

To enable the OAuth 2.0 Token Caching, in the “General” tab, under “OAuth” section, check the new “Use OAuth Token Caching” checkbox*.

* Please, note that this checkbox is enabled by default.

Token caching behavior with respect to server node and parallel call as per SAP implementation and reply from technical team,

1. Token Caching is implemented completely in-memory without any persistence, thus the fact that on each server node there will be separate cache instance. When the token is expired on the first call will remove it from cache. 
2. Latest token value is  to be stored, thus the expiration time will be the maximum offset in the future.  There is no problem update or removal expired token when there is parallel calls to the adapter to use existing tokens or update new token.

Access token is extracted and added to ‘OAuth20TokenCache’ with

Key: authorizationUrl_client_id

Value: *access_token* expiresIn: 2020-01-31T09:18:09.542 (yyyy-MM-ddTHH:mm:ss.SSS).

 This expiry is based upon the field “expires_in” from the HTTP response json payload.

  Say 1799 seconds it exactly calls a new token. Token is searched in ‘OAuth20Token’ Cache and uses the access token for the next consecutive and Concurrent calls till its expiry.After the access Token expiry,  Authentication API is immediately called and retrieves a fresh access token and update in Cache(OAuth20Token).Access Token expire exactly after 30 minutes and the expiry timestamp format used is ‘yyyy-MM-ddTHH:mm:ss.SSS’.

7. Troubleshooting:

1. Goto PI Message monitoring, check for the message logs.’Authorization’ will not be visible in audit logs and secured.

2. Goto to NWA log viewer for a detailed debug traces.

3. Enable XPI inspector log with corresponding REST adapter channel and check the HTTP client log, we can see the HTTP request header, body of adapter configuration and response header and body message Authorization server.

Note: Please Ensure SPS or Patch upgrade are applied on Sandbox environment and smoke tested thoroughly and then implemented in other environments.

Happy Reading!?