Admin Essentials

On this page:

Integration Models

Integration Models UI

The main user interface (UI) for Admin Essentials | Integration Models is described below. Please note that available views, features, and interactions in the UI can be limited based on user permissions.

Create Integration Model

When you upload a Swagger 2.0 or OpenAPI 3.0 specification file, you can run validation on it using the Validate button. The OpenAPI specification file must be obtained from the targeted integration. For example, gitlab, amazon, and jenkins provide OpenAPI specifications that properly describe their APIs. Admin Essentials can ingest these files and enable integration with these technologies within IAP.

The Name of the Integration Model will be pre-populated from the OpenAPI specification file, along with a description. You can change the description, as needed, to provide specific information for your installation and to better communicate what this integration is used for within your unique circumstance. Once you click the Create button, and upon successful import, you will be redirected to the Integration Model Details page.

Create Integration Model

Current OpenAPI Support

Swagger 2.0 and OpenAPI 3.0 are currently supported for creating an Integration Model. A Swagger 2.0 document is converted to an OpenAPI 3 document on import. All OpenAPI 3.0 documents must conform to the OpenAPI v3.0 Specification.

Current Limitations

Described below are known limitations with regard to creating an Integration Model.

Servers

Currently a single server endpoint is supported for Integrations. If the OpenAPI document has more than one server listed in its servers object, the first server will be selected for use. This endpoint can be updated in the service configuration after the Integration is created.

Example Template for Single Server Endpoint

Any server URL using the OpenAPI path template expressions will have the default value for variables applied. Below is an example of a configuration using multiple servers and URLs using path template expressions.

"servers": [
    {
      "description": "The s3 multi-region endpoint",
      "url": "https://s3.{region}.amazonaws.com",
      "variables": {
        "region": {
          "default": "us-east-2",
          "description": "The AWS region",
          "enum": [
            "us-east-1",
            "us-east-2",
            "us-west-1",
            "us-west-2"
          ]
        }
      }
    },
    {
      "description": "The s3 multi-region endpoint",
      "url": "https://s3.{region}.amazonaws.com",
      "variables": {
        "region": {
          "default": "us-east-1",
          "description": "The AWS region",
          "enum": [
            "us-east-1",
            "us-east-2",
            "us-west-1",
            "us-west-2"
          ]
        }
      }
    }
]

The resulting URL used in the service configuration will be the following:

https://s3.us-east-2.amazonaws.com/

This URL result was determined by taking the first server listed in the array and applying the default variable values to the template URL. Again, this URL can be edited in the service configuration after the Integration is created.

Security Schemes and Token Management

By default and upon import of an Integration Model, only a single security scheme is supported. Furthermore, the first scheme in the securityScheme map will be selected automatically.

Supported Security Schemes

The following security schemes are supported:

  • apiKey (including AWS)
  • http
  • oauth2

The openIdConnect scheme is NOT currently supported.

Once the integration is created, an authentication object is added to the properties of the service configuration. This configuration corresponds to the security scheme type. Below is an example of the authentication format.

Important Notes:

  • Currently IAP does NOT support any token management. You will need to manage the tokens for the security schemes.
  • For Amazon Web Services (AWS), please ensure the securityScheme entry is an apiKey and has the following extension: "x-amazon-apigateway-authtype": "awsSigv4".
"securitySchemes": {
        "Authorization": {
            "type": "apiKey",
            "description": "Amazon S3 signature",
            "name": "Authorization",
            "in": "header",
            "x-amazon-apigateway-authtype": "awsSigv4"
        }
    }

Listed below are examples of each of the different security schemes that can be used with Integration Models. The property names API-Token and Authorization in the API Key and AWS examples come from the name of the securityScheme property in the OpenAPI document.

API Key
"authentication": {
  "API-Token": {
    "value": ""
  }
},
AWS
"authentication": {
  "Authorization": {
    "accessKeyId": "",
    "secretAccessKey": ""
  }
},
HTTP (Basic & Bearer)

Basic

"authentication": {
          "httpBasic": {
            "username": "",
            "password": ""
          }
      },

Bearer

"authentication": {
          "bearerAuth": ""
      },
Oauth2
"authentication": {
  "oauth2": {
    "token": {
      "access_token": "",
      "token_type": "Bearer"
    }
  }
},