383 lines
11 KiB
Markdown
383 lines
11 KiB
Markdown
# Authentication
|
|
|
|
The `Authenticator` defines how to configure outgoing HTTP requests to authenticate on the API source.
|
|
|
|
Schema:
|
|
|
|
```yaml
|
|
Authenticator:
|
|
type: object
|
|
description: "Authenticator type"
|
|
anyOf:
|
|
- "$ref": "#/definitions/OAuth"
|
|
- "$ref": "#/definitions/ApiKeyAuthenticator"
|
|
- "$ref": "#/definitions/BearerAuthenticator"
|
|
- "$ref": "#/definitions/BasicHttpAuthenticator"
|
|
```
|
|
|
|
## Authenticators
|
|
|
|
### ApiKeyAuthenticator
|
|
|
|
The `ApiKeyAuthenticator` sets an HTTP header on outgoing requests.
|
|
The following definition will set the header "Authorization" with a value "Bearer hello":
|
|
|
|
Schema:
|
|
|
|
```yaml
|
|
ApiKeyAuthenticator:
|
|
type: object
|
|
additionalProperties: true
|
|
required:
|
|
- header
|
|
- api_token
|
|
properties:
|
|
"$parameters":
|
|
"$ref": "#/definitions/$parameters"
|
|
header:
|
|
type: string
|
|
api_token:
|
|
type: string
|
|
```
|
|
|
|
Example:
|
|
|
|
```yaml
|
|
authenticator:
|
|
type: "ApiKeyAuthenticator"
|
|
header: "Authorization"
|
|
api_token: "Bearer hello"
|
|
```
|
|
|
|
For more information see [ApiKeyAuthenticator Reference](https://docs.airbyte.com/connector-development/config-based/understanding-the-yaml-file/reference#/definitions/ApiKeyAuthenticator)
|
|
|
|
### BearerAuthenticator
|
|
|
|
The `BearerAuthenticator` is a specialized `ApiKeyAuthenticator` that always sets the header "Authorization" with the value `Bearer {token}`.
|
|
The following definition will set the header "Authorization" with a value "Bearer hello"
|
|
|
|
Schema:
|
|
|
|
```yaml
|
|
BearerAuthenticator:
|
|
type: object
|
|
additionalProperties: true
|
|
required:
|
|
- api_token
|
|
properties:
|
|
"$parameters":
|
|
"$ref": "#/definitions/$parameters"
|
|
api_token:
|
|
type: string
|
|
```
|
|
|
|
Example:
|
|
|
|
```yaml
|
|
authenticator:
|
|
type: "BearerAuthenticator"
|
|
api_token: "hello"
|
|
```
|
|
|
|
More information on bearer authentication can be found [here](https://swagger.io/docs/specification/authentication/bearer-authentication/).
|
|
|
|
For more information see [BearerAuthenticator Reference](https://docs.airbyte.com/connector-development/config-based/understanding-the-yaml-file/reference#/definitions/BearerAuthenticator)
|
|
|
|
### BasicHttpAuthenticator
|
|
|
|
The `BasicHttpAuthenticator` set the "Authorization" header with a (USER ID/password) pair, encoded using base64 as per [RFC 7617](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication#basic_authentication_scheme).
|
|
The following definition will set the header "Authorization" with a value `Basic {encoded credentials}`
|
|
|
|
Schema:
|
|
|
|
```yaml
|
|
BasicHttpAuthenticator:
|
|
type: object
|
|
additionalProperties: true
|
|
required:
|
|
- username
|
|
properties:
|
|
"$parameters":
|
|
"$ref": "#/definitions/$parameters"
|
|
username:
|
|
type: string
|
|
password:
|
|
type: string
|
|
```
|
|
|
|
Example:
|
|
|
|
```yaml
|
|
authenticator:
|
|
type: "BasicHttpAuthenticator"
|
|
username: "hello"
|
|
password: "world"
|
|
```
|
|
|
|
The password is optional. Authenticating with APIs using Basic HTTP and a single API key can be done as:
|
|
|
|
Example:
|
|
|
|
```yaml
|
|
authenticator:
|
|
type: "BasicHttpAuthenticator"
|
|
username: "hello"
|
|
```
|
|
|
|
For more information see [BasicHttpAuthenticator Reference](https://docs.airbyte.com/connector-development/config-based/understanding-the-yaml-file/reference#/definitions/BasicHttpAuthenticator)
|
|
|
|
### OAuth
|
|
|
|
OAuth authentication is supported through the `OAuthAuthenticator`, which requires the following parameters:
|
|
|
|
- token_refresh_endpoint: The endpoint to refresh the access token
|
|
- client_id: The client id
|
|
- client_secret: The client secret
|
|
- refresh_token: The token used to refresh the access token
|
|
- scopes (Optional): The scopes to request. Default: Empty list
|
|
- token_expiry_date (Optional): The access token expiration date formatted as RFC-3339 ("%Y-%m-%dT%H:%M:%S.%f%z")
|
|
- access_token_name (Optional): The field to extract access token from in the response. Default: "access_token".
|
|
- expires_in_name (Optional): The field to extract expires_in from in the response. Default: "expires_in"
|
|
- refresh_request_body (Optional): The request body to send in the refresh request. Default: None
|
|
- grant_type (Optional): The parameter specified grant_type to request access_token. Default: "refresh_token"
|
|
|
|
Schema:
|
|
|
|
```yaml
|
|
OAuth:
|
|
type: object
|
|
additionalProperties: true
|
|
required:
|
|
- token_refresh_endpoint
|
|
- client_id
|
|
- client_secret
|
|
- refresh_token
|
|
- access_token_name
|
|
- expires_in_name
|
|
properties:
|
|
"$parameters":
|
|
"$ref": "#/definitions/$parameters"
|
|
token_refresh_endpoint:
|
|
type: string
|
|
client_id:
|
|
type: string
|
|
client_secret:
|
|
type: string
|
|
refresh_token:
|
|
type: string
|
|
scopes:
|
|
type: array
|
|
items:
|
|
type: string
|
|
default: []
|
|
token_expiry_date:
|
|
type: string
|
|
access_token_name:
|
|
type: string
|
|
default: "access_token"
|
|
expires_in_name:
|
|
type: string
|
|
default: "expires_in"
|
|
refresh_request_body:
|
|
type: object
|
|
grant_type:
|
|
type: string
|
|
default: "refresh_token"
|
|
refresh_token_updater:
|
|
title: Token Updater
|
|
description: When the token updater is defined, new refresh tokens, access tokens and the access token expiry date are written back from the authentication response to the config object. This is important if the refresh token can only used once.
|
|
properties:
|
|
refresh_token_name:
|
|
title: Refresh Token Property Name
|
|
description: The name of the property which contains the updated refresh token in the response from the token refresh endpoint.
|
|
type: string
|
|
default: "refresh_token"
|
|
access_token_config_path:
|
|
title: Config Path To Access Token
|
|
description: Config path to the access token. Make sure the field actually exists in the config.
|
|
type: array
|
|
items:
|
|
type: string
|
|
default: ["credentials", "access_token"]
|
|
refresh_token_config_path:
|
|
title: Config Path To Refresh Token
|
|
description: Config path to the access token. Make sure the field actually exists in the config.
|
|
type: array
|
|
items:
|
|
type: string
|
|
default: ["credentials", "refresh_token"]
|
|
```
|
|
|
|
Example:
|
|
|
|
```yaml
|
|
authenticator:
|
|
type: "OAuthAuthenticator"
|
|
token_refresh_endpoint: "https://api.searchmetrics.com/v4/token"
|
|
client_id: "{{ config['api_key'] }}"
|
|
client_secret: "{{ config['client_secret'] }}"
|
|
refresh_token: ""
|
|
```
|
|
|
|
For more information see [OAuthAuthenticator Reference](https://docs.airbyte.com/connector-development/config-based/understanding-the-yaml-file/reference#/definitions/OAuthAuthenticator)
|
|
|
|
### JWT Authenticator
|
|
|
|
JSON Web Token (JWT) authentication is supported through the `JwtAuthenticator`.
|
|
|
|
Schema
|
|
|
|
```yaml
|
|
JwtAuthenticator:
|
|
title: JWT Authenticator
|
|
description: Authenticator for requests using JWT authentication flow.
|
|
type: object
|
|
required:
|
|
- type
|
|
- secret_key
|
|
- algorithm
|
|
properties:
|
|
type:
|
|
type: string
|
|
enum: [JwtAuthenticator]
|
|
secret_key:
|
|
type: string
|
|
description: Secret used to sign the JSON web token.
|
|
examples:
|
|
- "{{ config['secret_key'] }}"
|
|
base64_encode_secret_key:
|
|
type: boolean
|
|
description: When set to true, the secret key will be base64 encoded prior to being encoded as part of the JWT. Only set to "true" when required by the API.
|
|
default: False
|
|
algorithm:
|
|
type: string
|
|
description: Algorithm used to sign the JSON web token.
|
|
enum:
|
|
[
|
|
"HS256",
|
|
"HS384",
|
|
"HS512",
|
|
"ES256",
|
|
"ES256K",
|
|
"ES384",
|
|
"ES512",
|
|
"RS256",
|
|
"RS384",
|
|
"RS512",
|
|
"PS256",
|
|
"PS384",
|
|
"PS512",
|
|
"EdDSA",
|
|
]
|
|
examples:
|
|
- ES256
|
|
- HS256
|
|
- RS256
|
|
- "{{ config['algorithm'] }}"
|
|
token_duration:
|
|
type: integer
|
|
title: Token Duration
|
|
description: The amount of time in seconds a JWT token can be valid after being issued.
|
|
default: 1200
|
|
examples:
|
|
- 1200
|
|
- 3600
|
|
header_prefix:
|
|
type: string
|
|
title: Header Prefix
|
|
description: The prefix to be used within the Authentication header.
|
|
examples:
|
|
- "Bearer"
|
|
- "Basic"
|
|
jwt_headers:
|
|
type: object
|
|
title: JWT Headers
|
|
description: JWT headers used when signing JSON web token.
|
|
additionalProperties: false
|
|
properties:
|
|
kid:
|
|
type: string
|
|
title: Key Identifier
|
|
description: Private key ID for user account.
|
|
examples:
|
|
- "{{ config['kid'] }}"
|
|
typ:
|
|
type: string
|
|
title: Type
|
|
description: The media type of the complete JWT.
|
|
default: JWT
|
|
examples:
|
|
- JWT
|
|
cty:
|
|
type: string
|
|
title: Content Type
|
|
description: Content type of JWT header.
|
|
examples:
|
|
- JWT
|
|
additional_jwt_headers:
|
|
type: object
|
|
title: Additional JWT Headers
|
|
description: Additional headers to be included with the JWT headers object.
|
|
additionalProperties: true
|
|
jwt_payload:
|
|
type: object
|
|
title: JWT Payload
|
|
description: JWT Payload used when signing JSON web token.
|
|
additionalProperties: false
|
|
properties:
|
|
iss:
|
|
type: string
|
|
title: Issuer
|
|
description: The user/principal that issued the JWT. Commonly a value unique to the user.
|
|
examples:
|
|
- "{{ config['iss'] }}"
|
|
sub:
|
|
type: string
|
|
title: Subject
|
|
description: The subject of the JWT. Commonly defined by the API.
|
|
aud:
|
|
type: string
|
|
title: Audience
|
|
description: The recipient that the JWT is intended for. Commonly defined by the API.
|
|
examples:
|
|
- "appstoreconnect-v1"
|
|
additional_jwt_payload:
|
|
type: object
|
|
title: Additional JWT Payload Properties
|
|
description: Additional properties to be added to the JWT payload.
|
|
additionalProperties: true
|
|
$parameters:
|
|
type: object
|
|
additionalProperties: true
|
|
```
|
|
|
|
Example:
|
|
|
|
```yaml
|
|
authenticator:
|
|
type: JwtAuthenticator
|
|
secret_key: "{{ config['secret_key'] }}"
|
|
base64_encode_secret_key: True
|
|
algorithm: RS256
|
|
token_duration: 3600
|
|
header_prefix: Bearer
|
|
jwt_headers:
|
|
kid: "{{ config['kid'] }}"
|
|
cty: "JWT"
|
|
additional_jwt_headers:
|
|
test: "{{ config['test']}}"
|
|
jwt_payload:
|
|
iss: "{{ config['iss'] }}"
|
|
sub: "sub value"
|
|
aud: "aud value"
|
|
additional_jwt_payload:
|
|
test: "test custom payload"
|
|
```
|
|
|
|
For more information see [JwtAuthenticator Reference](https://docs.airbyte.com/connector-development/config-based/understanding-the-yaml-file/reference#/definitions/JwtAuthenticator)
|
|
|
|
## More readings
|
|
|
|
- [Requester](./requester.md)
|
|
- [Request options](./request-options.md)
|