Skip to main content

Gate: Request OAuth2 Authenticator Plugin

The Request OAuth2 Authenticator plugin for Gate is a powerful tool for adding OAuth2 access tokens to outgoing requests in machine-to-machine communication scenarios. This plugin enables Gate to authenticate and authorize itself to an upstream service by generating OAuth2 access tokens based on its client credentials.

Features​

  • Supports the OAuth2 Client Credentials grant type for machine-to-machine authentication
  • Generates access tokens based on the configured client credentials
  • Adds the generated access token to the outgoing request header
  • Supports both opaque and JWT access token formats
  • Integrates with various secret management systems for secure retrieval of client credentials
  • Allows configuring the required scopes for the generated access token

Configuration​

To use the Request OAuth2 Authenticator plugin, you need to configure it in your Gate configuration file. Here's an example configuration with all the available options:

gate:
  plugins:
    - id: add_authnz
      type: request-oauth2-authenticator
      enabled: true
      parameters:
        header_for_token: "Authorization"
        oauth2_token_format: "opaque"
        oauth2_token_creation_endpoint: "https://auth.example.com/oauth2/token"
        oauth2_token_client_id: "gate_client_id"
        oauth2_token_client_secret: "gate_client_secret"
        oauth2_scopes:
          - read
          - write
        refresh_client_secret: false
        secret_engine: "aws"
        aws_region: "us-west-2"
        aws_access_key_id: "your_aws_access_key_id"
        aws_secret_access_key: "your_aws_secret_access_key"
        gcp_project_id: "your_gcp_project_id"
        gcp_client_id: "your_gcp_client_id"
        gcp_client_secret: "your_gcp_client_secret"
        gcp_refresh_token: "your_gcp_refresh_token"
        azure_vault_url: "https://your-vault.vault.azure.net/"
        azure_client_id: "your_azure_client_id"
        azure_client_secret: "your_azure_client_secret"
        azure_tenant_id: "your_azure_tenant_id"
        vault_address: "https://your-vault.example.com"
        vault_secret_path: "secret/data/gate"
        vault_token: "your_vault_token"

urls:
  - pattern: "/api/*"
    target: http://api-server:8000
    plugins:
      add_authnz:
        enabled: true

Here's a breakdown of all the configuration options:

  • header_for_token (required): The header where the generated access token will be added (e.g., "Authorization").
  • oauth2_token_format (required): The format of the access token, either "opaque" or "jwt".
  • oauth2_token_creation_endpoint (required): The endpoint for creating OAuth2 access tokens (e.g., "https://auth.example.com/oauth2/token").
  • oauth2_token_client_id (required): The client ID used to authenticate Gate to the OAuth2 token endpoint.
  • oauth2_token_client_secret (optional): The client secret used to authenticate Gate to the OAuth2 token endpoint. If not provided, the plugin will attempt to retrieve the client secret from the configured secret management system.
  • oauth2_scopes (optional): The required scopes for the generated access token.
  • refresh_client_secret (optional, default: false): Specifies whether to refresh the client secret from the secret management system on each request.
  • secret_engine (optional): The secret management system to use for storing and retrieving the client secret. Supported values are "aws", "gcp", "azure", and "vault".

The following configuration options are specific to the selected secret management system and are optional:

  • AWS Secrets Manager:

    • aws_region: The AWS region where the secrets are stored.
    • aws_access_key_id: The AWS access key ID for accessing the secrets.
    • aws_secret_access_key: The AWS secret access key for accessing the secrets.

  • Google Cloud Secret Manager:

    • gcp_project_id: The Google Cloud project ID where the secrets are stored.
    • gcp_client_id: The Google Cloud client ID for accessing the secrets.
    • gcp_client_secret: The Google Cloud client secret for accessing the secrets.
    • gcp_refresh_token: The Google Cloud refresh token for accessing the secrets.

  • Azure Key Vault:

    • azure_vault_url: The URL of the Azure Key Vault where the secrets are stored.
    • azure_client_id: The Azure client ID for accessing the secrets.
    • azure_client_secret: The Azure client secret for accessing the secrets.
    • azure_tenant_id: The Azure tenant ID for accessing the secrets.

  • HashiCorp Vault:

    • vault_address: The address of the HashiCorp Vault server.
    • vault_secret_path: The path to the secret in the HashiCorp Vault.
    • vault_token: The token for authenticating to the HashiCorp Vault.

The urls section specifies the API endpoint pattern ("/api/*") and the target API server. The add_authnz plugin is enabled for the specified URL pattern.

Usage​

Once the Request OAuth2 Authenticator plugin is configured, it intercepts outgoing requests to the specified URL pattern ("/api/*" in the example configuration). The plugin generates an OAuth2 access token based on the configured client credentials and adds it to the specified header ("Authorization" in the example).

The generated access token is then included in the outgoing request to the upstream service, allowing Gate to authenticate and authorize itself.

If the refresh_client_secret option is enabled, the plugin will retrieve the client secret from the configured secret management system on each request, ensuring that the most up-to-date secret is used.

Benefits​

The Request OAuth2 Authenticator plugin offers several benefits:

  • Secure Authentication: By generating OAuth2 access tokens, Gate can securely authenticate itself to upstream services without exposing its client credentials.
  • Flexible Token Format: The plugin supports both opaque and JWT access token formats, allowing compatibility with different OAuth2 server implementations.
  • Scope-based Authorization: The required scopes can be configured for the generated access token, enabling fine-grained authorization control.
  • Integration with Secret Management: The plugin allows storing client credentials securely using various secret management systems, enhancing the overall security posture.

Conclusion​

The Request OAuth2 Authenticator plugin for Gate simplifies the process of adding OAuth2 access tokens to outgoing requests in machine-to-machine communication scenarios. By generating access tokens based on configured client credentials and integrating with secret management systems, Gate can securely authenticate and authorize itself to upstream services.

Leverage the Request OAuth2 Authenticator plugin to enhance the security and interoperability of your machine-to-machine communication flows.