Gen 8.6 Consuming REST APIs: Authentication

Products

• Gen
• Gen - Host Encyclopedia
• Gen - Run Time Distributed
• Gen - Workstation Toolset

Issue/Introduction

When the Consuming REST APIs for Java and CICS Applications feature was originally released in January 2022, security schemes that might be defined in a REST service’s Open API specification were not natively supported.  It was still possible, however, to implement certain security schemes by making some modifications to the Open API specification as a workaround. The Knowledge Base Article Gen 8.6 Consuming REST APIs: Security described the types of modifications needed and provided examples of implementing different security schemes.

The June 2022 enhancement to the Consuming REST APIs for Java and CICS Applications feature added native support for BasicAuth, BearerAuth, ApiKeyAuth, and OAuth2 (Client Credentials Flow) security schemes.  This document shows how this enhancement simplifies the implementation of these security schemes, as compared to the workarounds documented in the aforementioned Knowledge Base Article.

Environment

Gen 8.6
Java applications
COBOL applications on CICS

Resolution

Implementing Basic Authentication

The article Gen 8.6 Consuming REST APIs: Security described how to add the Authorization header parameter to the Open API spec.  It also showed example PAD logic to create a token string composed of username:password, Base64-encoded this string using Inline Code, and finally matched the entire token value to the Authorization header parameter on the Call REST statement.

With native support for BasicAuth, all that is required is to send the username and password values to the Action Diagram containing the Call REST statement and match those values to the Authentication.Basic.Username and Authentication.Basic.Password parameters.

The following is an example of using the native support for the BasicAuth security scheme.

      +- PING_REST_BASIC

      |    IMPORTS:

      |      Work View   in ping_server_config (mandatory,transient,import only)

      |        host_url (mandatory)

      |      Work View   in user_principle (mandatory,transient,import only)

      |        passwd (mandatory)

      |        user (mandatory)

      |    EXPORTS:

      |      Work View   out pingresp (transient,export only)

      |        httptext (nullable)

      |        httpcode (nullable)

      |        pingval (nullable)

      |    LOCALS:

      |    ENTITY ACTIONS:

      | 

    1 |  CALL REST Web Service "PINGBASIC:GET:/api/ping"

      +--

 

Implementing API Key Authentication

The article Gen 8.6 Consuming REST APIs: Security described how the Gen Toolset already understood ApiKeyAuth, so no additional changes to the Open API spec were required.  All that was needed was to pass the value for the API Key parameter and match it to the API-KEY header parameter on the Call REST statement.

With native support for ApiKeyAuth, this has not changed.

The following is an example of using the native support for the ApiKeyAuth security scheme.

      +- PING_REST_APIKEY

      |    IMPORTS:

      |      Work View   in ping_server_config (mandatory,transient,import only)

      |        host_url (mandatory)

      |      Work View   in auth_token (mandatory,transient,import only)

      |        value (mandatory)

      |    EXPORTS:

      |      Work View   out pingresp (transient,export only)

      |        httptext (nullable)

      |        httpcode (nullable)

      |        pingval (nullable)

      |    LOCALS:

      |    ENTITY ACTIONS:

      | 

    1 |  CALL REST Web Service "PINGKEY:GET:/api/ping"

      +--

 

 

Implementing OAuth2 Client Credentials Flow Authentication

The article Gen 8.6 Consuming REST APIs: Security described how to create an Open API spec for your authorization server, as well as how to add the Authorization header parameter to the REST service’s Open API spec.  It showed example PAD logic to create the necessary token values for both the authorization server and the REST service.   It also showed two example Call REST statements – one for the authorization server and one for the REST service.

With native support for OAuth2 (Client Credentials Flow), all that is required is to send the username, password, and authorization server token URL values to the Action Diagram containing the Call REST statement and match those values to the Authentication.OAuth2.clientCredentials.ClientId,  Authentication.OAuth2.clientCredentials.ClientSecret, and Authentication.OAuth2.clientCredentials.TokenURL parameters.

The following is an example of using the native support for the OAuth2 (Client Credentials Flow) security scheme.

      +- PING_REST_OAUTH

      |    IMPORTS:

      |      Work View   in ping_server_config (mandatory,transient,import only)

      |        host_url (mandatory)

      |      Work View   in auth_server_config (mandatory,transient,import only)

      |        host_url (mandatory)

      |      Work View   in user_principle (mandatory,transient,import only)

      |        passwd (mandatory)

      |        user (mandatory)

      |    EXPORTS:

      |      Work View   out authresp (transient,export only)

      |        httptext (nullable)

      |        httpcode (nullable)

      |      Work View   out pingresp (transient,export only)

      |        httptext (nullable)

      |        httpcode (nullable)

      |        pingval (nullable)

      |    LOCALS:

      |    ENTITY ACTIONS:

      | 

    1 |  CALL REST Web Service "PINGOAUTH:GET:/api/ping"

      +--

 

Wrap-up

While article Gen 8.6 Consuming REST APIs: Security showed that it was possible to implement security schemes using some workarounds, the enhancement to add native support for security schemes greatly reduces the effort required to access a REST service that requires authentication.

Additional Information

For additional information, please see hub article: Gen 8.6 Consuming REST APIs (Call REST) feature