Security Schemes for OpenAPI Provider Rest API Descriptor in Integration Server

Author - @PriyaGupta

Overview

The OpenAPI Specification 3.0.x provides a security object that defines the security schemes for operations. Following are the supported security schemes for OpenAPI 3.0.x:

  • HTTP authentication
  • API key
  • OAuth2 (implicit, password, client credentials, and authorization code)
  • OpenID Connect Discovery

Integration Server supports the following authentication mechanisms from the OpenAPI Specification version 3.0.x:

  • HTTP authentications: Basic, Bearer, and Digest
  • OAuth 2.0 flows: Authorization Code, Implicit, Resource Owner Password Credentials or Password, and Client Credentials

The API key and the OpenID Connect Discovery security schemes are not supported by the provider REST API Descriptor (RAD).

This tutorial explains how the provider RAD that uses the OpenAPI document 3.0.x displays the security schemes.

Prerequisites

Ensure that the following are available:

  • Integration Server that processes the REST API request.
  • An integration developer implementing the business logic in the service.

Use case #1: How the provider RAD displays the basic security scheme

Consider the use case where you have an OpenAPI document with the basic security scheme. After you import the OpenAPI document successfully, the provider RAD displays the security details.
Following example shows the snippet of an OpenAPI document with the basic security scheme:

security schemes:
basictest: # arbitrary name for the security scheme
type: http
scheme: basic

Basic flow

  1. Start Software AG Designer.
  2. Create a provider RAD using the attached OpenAPI document (
    petstore_security_basic.doc (5.2 KB)
    ) that contains a basic security scheme. For more information on creating a provider RAD using an OpenAPI document, see Integration Server as a Contract-First REST API Provider using OpenAPI.
  3. After you import the OpenAPI document successfully, the provider RAD displays the basic security schemes as depicted in the following figure:

Use case #2: How the provider RAD displays the digest security scheme

This use case starts when you have an OpenAPI document containing the digest security schemes. After you import the OpenAPI document successfully, the provider RAD displays the security details.
Following example shows the snippet of an OpenAPI document with the digest security schemes:

security schemes:
digesttest: # arbitrary name for the security scheme
type: http
scheme: digest

Basic flow

  1. Start Software AG Designer.
  2. Create a provider RAD using the attached OpenAPI document (
    petstore_security_digest.doc (5.1 KB)
    ) that contains the digest security scheme.
  3. Open the provider RAD and go to the Security tab. The Security tab displays the digest security schemes.

Use case #3: How the provider RAD displays the OAuth security scheme

This use case starts when you have an OpenAPI document containing OAuth security schemes. After you import the OpenAPI document successfully, the provider RAD displays the security details.
Following example shows the snippet of an OpenAPI document with the OAuth security schemes:

security schemes:
petstore_auth:
type: oauth2
flows:
authorizationCode:
authorizationUrl: 'http://SAG-HTD8NQ2.eur.ad.sag:5555/invoke/pub.oauth:authorize'
tokenUrl: 'http://SAG-HTD8NQ2.eur.ad.sag:5555/invoke/pub.oauth:getToken'
scopes:
- 'write:pets': modify pets in your account
- 'read:pets': read your pets

Basic flow

  1. Start Software AG Designer.
  2. Create a provider RAD using the attached OpenAPI document (
    petstore_security_oauth.doc (5.4 KB)
    ) that contains the OAuth security scheme.
  3. Open the provider RAD and go to the Security tab. The Security tab displays the OAuth security schemes.

Use case #4: How to handle multiple security schemes in the Provider RAD

When an OpenAPI document contains multiple security authentication mechanisms, the provider RAD displays the following security schemes:
For example,
Consider the following combination of logical OR authentication mechanisms:

security: # basic OR oauth2
- petstore_auth:
    - 'write:pets'
-basicTest: [  ]

In this case, the provider RAD displays both basicTest and petstore_auth (The API can use either basic or OAuth).

Consider the following combination of the logical AND authentication mechanism:
security:

  • petstore_auth:
    • ‘write:pets’
      basicTest: [ ]
      In this case, the provider RAD considers only the first supported authentication mechanism (OAuth).

Consider the following combinations of both the logical OR and logical AND authentication mechanisms:

security: # (ApiKeyAuth AND petstore_auth) OR (basicTest AND digesttest)
      - ApiKeyAuth: [  ]
         petstore_auth:
            - 'write:pets'  
     - basicTest: [  ]  
        digesttest: [  ]

In this case, provider RAD considers both the combinations with the first supported authentication mechanism.

Use case #5 How the provider RAD displays the global security scheme

This use case starts when you have an OpenAPI document containing basic security Schemes. After you import the OpenAPI document successfully, the provider RAD displays the global security schemes.

Basic flow

  1. Start Software AG Designer.
  2. Create a provider RAD using the attached OpenAPI document (
    petstore_security_basic.doc (5.2 KB)
    ) that contains a global basic security scheme.
  3. Open the provider RAD and go to the Security tab. The Security tab displays the global security schemes.

For more information on creating a provider RAD using an OpenAPI document, see Integration Server as a Contract-First REST API Provider using OpenAPI.

1 Like