Skip to main content

Announcing Support for Multiple Authentication Schemes in API Transformer

· 5 min read

We now support multiple authentication schemes and related information in our API Transformer for all applicable API description formats including OpenAPI, RAML, Postman and Insomnia. You can now convert between these formats without losing important authentication details.

What was Supported Before?​

Only a single authentication scheme was loaded per API and all other schemes were ignored. This meant that:

  • If some endpoints of the API used one authentication scheme while others used a different scheme, only the first authentication scheme was globally applied and assumed for all endpoints that required authentication. The endpoint level authentication was used to override global authentication only when it needed to specify different OAuth 2.0 scopes.
  • If an endpoint needed multiple authentication schemes to complete its authentication flow, only the first authentication scheme was considered and information about the other schemes was ignored.
  • Each OAuth 2.0 grant type was considered as a separate authentication scheme. If an API allowed multiple grant types, information about only the first grant type was imported.

The authentication scheme was exported with a custom name and the user-defined name was ignored.

What's New?​

Support for multiple authentication schemes and related features has been added for the following API description formats: OpenAPI (v3.x, v2.0, v1.x), RAML (v1.0, v0.8), Postman Collections (v2.x, v1.0), Insomnia (v3). A detailed breakdown of what has been added is discussed below.

Support Added for Multiple Authentication Schemes​

If your API defines multiple authentication schemes, these schemes will now be transformed with complete information including authentication type specific details as well as user-defined authentication scheme name and descriptive content.

Supported authentication schemes are listed here.

Merging APIs With Different Authentication Schemes​

If you are merging multiple APIs together that make use of different authentication schemes, these authentication schemes will now also be merged together without conflicts. This is in contrast to before when the merging process was terminated if it encountered different authentication schemes.

Support Added for Applying Different Authentication Schemes​

Support has been added in API Transformer for the various mechanisms to apply authentication on endpoints which are discussed below:

  • Global vs Endpoint Level Authentication

    In OpenAPI, RAML, and Postman collections, authentication schemes can be applied either globally to all endpoints or for specific endpoints only. The endpoint level authentication overrides any globally applied authentication.

  • Authentication Options and Groups

    Regardless of where the authentication is applied, however, an endpoint can have a list of authentication scheme options out of which one must be satisfied. An authentication option can also be an authentication scheme group (supported only in OpenAPI v3.0 and v2.0) where multiple authentication schemes need to be satisfied in order to complete the authentication process. RAML (v1.0, v0.8) supports only ungrouped authentication options. On the other hand, Postman collections (v2.x, v1.0) and Insomnia allows only one authentication scheme to be applied per endpoint.

    note

    When exporting to formats like Postman collection or Insomnia where only single authentication schemes are supported per endpoint, a non-grouped authentication scheme will be given more precedence, if available.

Ability to Extend Applied Authentication Information Via Extensions​

When specifying security options in OpenAPI (v3.0, v2.0), you can now extend the security information with additional metadata like name or description to improve output, where applicable. This can be done through our new vendor extension x-security-options-meta, more details of which you can find here.

Support Added for Optional Authentication​

RAML (v1.0, v0.8) and OpenAPI (v3.x, v2.0) support optional authentication for endpoints. This is now supported in API Transformer as well.

#%RAML 1.0
title: Example API
version: v3
baseUri: https://api.example.com
securitySchemes:
  oauth_2_0:
    type: OAuth 2.0
    settings:
      authorizationUri: https://www.example.com/oauth2/authorize
      accessTokenUri: https://example.com/oauth2/token
      authorizationGrants: [ authorization_code ]
/users:
  get:
    securedBy: [null, oauth_2_0]

New Validation Rules Added​

The following new validation rules related to authentication have been added:

How to Avoid Changes in Output?​

If you wish to avoid receiving any changes to your output which are discussed above, you can opt out of them by setting the import flag value ImportMultipleAuthentication to false in a metadata file uploaded along with your API description file. For more details on how to create a metadata file and add import settings, please visit this link.

If you are merging multiple APIs together, you will additionally need to set the MergeMultipleAuthentication merge setting value to false as well. For more details, please visit this link.