EPO Consulting Wiki - EPO Connector - how to consume an OAuth JSON webservice

This documentation shows an easy example how to consume a webservice, using the OAuth authentication. For the basic usage, please refer How to consume a JSON webservice.

The main class used is /EPO1/CL_JSON_BASE_OUT_OAUTH, based on /EPO1/CL_JSON_BASE_OUT.

The SAP Outbound call is done with function module /EPO1/EPOCLIENT.

Overview

After creating an object of the class /EPO1/CL_JSON_BASE_OUT_OAUTH, a webservice can be called with one of the methods 'CALL_SERVICE' or 'CALL_SERVICE_DOWNLOAD'.

During the first call, or when the token has expired, a fresh token will be requested from the authentication - webservice. This token will be used for subsequent webservice calls.

Authorization methods

Currently, only the authentication with a bearer token is supported.

The authorization method is passed to the constructor with the parameter IV_OAUTH_TOKEN_TYPE.

Bearer token

In the most simple use case, a webservice call with username and client-secret returns a token, which will be used for subsequent webservice calls.

The username and the client-secret has to be stored with transaction /EPO1/EC_EB_WSSP12:

• SAP System = the SAP-ID
• Service name = the EPO service name
• Name ..

= 'client_id' for the client-id

= 'client_sec' for the client-secret

• Value = the client-id / client-secret

Optional: in order to use the bearer token, pass the predefined constant /EPO1/CL_JSON_BASE_OUT_OAUTH=>CV_OAUTH_TOKEN_TYPE_BEARER to the constructor - parameter IV_OAUTH_TOKEN_TYPE (this is the default value - and currently the only available option).

Parameters for the constructor

The class '/EPO1/CL_JSON_BASE_OUT_OAUTH' is based on the class '/EPO1/CL_JSON_BASE_OUT', so that many parameters are already known. Here are the additional parameters:

IV_OAUTH_SERVICE_OPERATION (optional)

In most cases, the operation for the token access is different to the 'normal' webservice operation. If not specified, the value of parameter IV_SERVICE_OPERATION is used.

IV_OAUTH_API_PATH (optional)

If specified, this path will be used for the webservice call, which gets the token. Please note, that the API path can also be specified in the EPO customizing of the outgoing operation.

IV_OAUTH_TOKEN_TYPE (optional)

If not specified, the 'bearer' token will be used for authentification.

IV_OAUTH_RESOURCE (optional)

Specify a 'resouce' string, if required by the token-webservice.

IV_OAUTH_SCOPE (optional)

Specify a 'scope' string, if required by the token-webservice.

IV_OAUTH_GRANT_TYPE (optional)

Specify a 'grant' type, if required by the token-webservice. If not specified, the default value 'client_credentials' is used.

IV_OAUTH_ERROR_RETRY (optional)

If set to 'X', an error during the webserver call will clear the stored token and try another call. This error handling could help, if the token has been supplied without expiry time.

IV_PERSISTENT_TOKEN (optional)

If set to 'X', the token and the expire timestamp will be stored into table '/EPO1/AUTH_TOKEN'; the next webservice call within the expire timestamp will take the token from the database, which is much faster than a new authentication-webservice call. Please note, that for different accounts / scope / grant type, distinguished EPO services should be used in order to get different tokens (with different access rights).

Code example

This example is just a copy of how to comsume.., with a little extra bit.

Please note, that the 'ZJSON_GEO_WEBSERVICE' does not actually require / support OAuth; this example is only used to indicate the minor changes wich are required to use OAuth authentification on a webservice.

  " init
  CREATE OBJECT lo_json  " now: of class /EPO1/CL_JSON_BASE_OUT_OAUTH
    EXPORTING
      iv_service_id_outbound     = 'ZJSON_GEO_WEBSERVICE'
      iv_service_operation       = 'cities'
      " ..with some additional parameters:
      iv_oauth_service_operation = 'oauth2'
      iv_oauth_token_type        = /epo1/cl_json_base_out_oauth=>cv_oauth_token_type_bearer.  " could be omitted - because 'bearer' is default

  " call the webservice
  lo_json->call_service(
    EXPORTING
      iv_api_path    = '/citiesJSON?north=44.1&south=-9.9&east=-22.4&west=55.2&lang=de&username=demo'
      iv_http_method = 'GET'
    IMPORTING
      es_response_data = ls_response
      es_callstatus    = ls_callstatus ).

Comparing to the small example, we only had to ..

• change the class of the object LO_JSON to /EPO1/CL_JSON_BASE_OUT_OAUTH,
• add some parameters to the constructor,
• customize the operation 'oauth2' for the token access and
• specify client-id / client-secret in transaction /EPO1/EC_EB_WSSP12

..in order to use OAuth authentification for a webservice.

Maybe, that the service requires some additional headers; they may be customized in the EPO connector or added during runtime.