Skip to content

Latest commit

 

History

History
230 lines (190 loc) · 5.94 KB

authentication.md

File metadata and controls

230 lines (190 loc) · 5.94 KB

Authentication

The current version supports API key and Auth token authentication schemes. The configuration is inspired from securitySchemes with env variables. The connector supports the following authentication strategies:

  • API Key.
  • Basic Auth.
  • Bearer Auth.
  • Cookie.
  • OAuth 2.0.
  • Mutual TLS.

The configuration automatically generates environment variables for those security schemes.

API Key

There is a value field with the environment variable to be replaced in runtime. The name of the variable is generated from the security scheme key. For example:

securitySchemes:
  api_key:
    type: apiKey
    value:
      env: API_KEY # the constant case of api_key
    in: header
    name: api_key
api_key: {{API_KEY}}

Basic Auth

Set username and password environment variables:

securitySchemes:
  basic:
    type: basic
    header: Authorization
    username:
      value: PET_STORE_USERNAME
    password:
      value: PET_STORE_PASSWORD

Bearer Auth

Configure the value environment variable, header name, and scheme. For example, the below configuration will inject the bearer token into incoming requests:

securitySchemes:
  bearer:
    type: http
    header: Authorization
    value:
      env: PET_STORE_BEARER_TOKEN
    scheme: bearer
Authorization: Bearer {{PET_STORE_BEARER_TOKEN}}

OAuth 2.0

The client credentials grant is built-in supported. You can set the tokenUrl, scopes, client ID, and client secret variables. The connector automatically refreshes access tokens and injects them into incoming requests.

securitySchemes:
  petstore_auth:
    type: oauth2
    flows:
      clientCredentials:
        tokenUrl:
          value: http://localhost:4444/oauth2/token
        clientId:
          env: OAUTH2_CLIENT_ID
        clientSecret:
          env: OAUTH2_CLIENT_SECRET
        scopes:
          read:pets: read your pets
          write:pets: modify pets in your account

For other OAuth 2.0 flows, you need to enable headers forwarding from the Hasura engine to the connector.

Cookie

For Cookie authentication and OAuth 2.0, you need to enable headers forwarding from the Hasura engine to the connector.

Headers Forwarding

Enable forwardHeaders in the configuration file.

# ...
forwardHeaders:
  enabled: true
  argumentField: headers

And configure in the connector link metadata.

kind: DataConnectorLink
version: v1
definition:
  name: my_api
  # ...
  argumentPresets:
    - argument: headers
      value:
        httpHeaders:
          forward:
            - Cookie
          additional: {}

See the configuration example in Hasura docs.

Mutual TLS

Basic

If the mutualTLS security scheme exists the TLS configuration will be generated in the settings field.

settings:
  servers:
    - url:
        env: PET_STORE_URL
  securitySchemes:
    mtls:
      type: mutualTLS
  tls:
    # Provide the certificate contents as a base64-encoded string.
    certPem:
      env: PET_STORE_CERT_PEM
    # Provide the key contents as a base64-encoded string.
    keyPem:
      env: PET_STORE_KEY_PEM
    # Provide the CA cert contents as a base64-encoded string.
    caPem:
      env: PET_STORE_CA_PEM
    # Additionally you can configure TLS to be enabled but skip verifying the server's certificate chain (optional).
    insecureSkipVerify:
      env: PET_STORE_INSECURE_SKIP_VERIFY
      value: false

Full Configuration:

[!NOTE] It's recommended to use inline bases64-encoded PEM data *_PEM variables if you deploy the connector to Hasura DDN cloud.

settings:
  servers:
    - url:
        env: PET_STORE_URL
  securitySchemes:
    mtls:
      type: mutualTLS
  tls:
    # Path to the TLS cert to use for TLS required connections.
    certFile:
      env: PET_STORE_CERT_FILE
    # Alternative to cert_file. Provide the certificate contents as a base64-encoded string instead of a filepath.
    certPem:
      env: PET_STORE_CERT_PEM
    # Path to the TLS key to use for TLS required connections.
    keyFile:
      env: PET_STORE_KEY_FILE
    # Alternative to key_file. Provide the key contents as a base64-encoded string instead of a filepath.
    keyPem:
      env: PET_STORE_KEY_PEM
    # Path to the CA cert.
    caFile:
      env: PET_STORE_CA_FILE
    # Alternative to ca_file. Provide the CA cert contents as a base64-encoded string instead of a filepath.
    caPem:
      env: PET_STORE_CA_PEM
    # Additionally you can configure TLS to be enabled but skip verifying the server's certificate chain (optional).
    insecureSkipVerify:
      env: PET_STORE_INSECURE_SKIP_VERIFY
      value: false
    # Whether to load the system certificate authorities pool alongside the certificate authority (optional).
    includeSystemCACertsPool:
      env: PET_STORE_INCLUDE_SYSTEM_CA_CERT_POOL
      value: false

    ## ServerName requested by client for virtual hosting (optional).
    serverName:
      env: PET_STORE_SERVER_NAME

    ## Minimum acceptable TLS version (optional).
    minVersion: "1.0"

    ## Maximum acceptable TLS version (optional).
    maxVersion: "1.3"

    ## Explicit cipher suites can be set. If left blank, a safe default list is used (optional).
    # cipherSuites:
    #   - TLS_AES_128_GCM_SHA256

Different Certificates per servers.

If the service has many servers, you can configure different TLS configurations for each server. However, you need to manually patch the configuration:

settings:
  servers:
    - url:
        env: PET_STORE_URL
    - url:
        env: PET_STORE_URL_2
      tls:
        certFile:
          env: PET_STORE_CERT_FILE_2
        # ...
  securitySchemes:
    mtls:
      type: mutualTLS
  tls:
    certFile:
      env: PET_STORE_CERT_FILE
    # ...