Platform Connectivity and Authentication

Platform Connectivity and Authentication provides the essential mechanisms for client applications to establish secure and authenticated connections with the backend platform. It centralizes the configuration of connection endpoints, manages various authentication flows, and handles credential management, enabling reliable and secure interaction with platform services.

Core Features

• Flexible Endpoint Configuration: Define the target platform endpoint, including options for a separate console endpoint and an HTTP proxy for OAuth requests.
• Robust Security Controls: Support for secure (SSL/TLS) connections, with options to skip certificate verification or specify custom CA certificates. Insecure connections are also supported for development environments.
• Multiple Authentication Flows: Implement various OAuth 2.0 authentication modes, including PKCE (Proof Key for Code Exchange), Client Credentials, Device Flow, and the ability to integrate with external command-line tools for token acquisition.
• Credential Management: Centralized handling of client IDs, client secrets (loaded from environment variables, files, or directly), and OAuth scopes.
• Automated Configuration Loading: Automatically load connection and authentication settings from configuration files and environment variables, simplifying deployment and management across different environments.

Common Use Cases

• Interactive User Authentication: Authenticate end-users for client applications using the PKCE flow, typically involving a browser redirect for user consent.
• Service-to-Service Authentication: Enable backend services or automated scripts to authenticate with the platform using client credentials, ideal for machine-to-machine communication where no user interaction is involved.
• Custom Authentication Integrations: Integrate with proprietary identity providers or complex authentication systems by leveraging external commands to generate and refresh access tokens.
• Development and Testing: Quickly establish insecure connections to local or development environments for rapid iteration.
• Enterprise Deployments: Configure secure connections with custom CA certificates and integrate with corporate HTTP proxies for outbound OAuth requests.

Platform Configuration

The PlatformConfig object encapsulates all necessary settings for connecting to the platform. You can instantiate PlatformConfig directly or use its auto method for convenient loading from various sources.

from flytekit.configuration import PlatformConfig

# Direct instantiation for a specific endpoint
# This is useful when all parameters are known at runtime or hardcoded.
config = PlatformConfig.for_endpoint("my-flyte-admin.example.com:443", insecure=False)

# For a local insecure setup, often used during development
local_config = PlatformConfig(endpoint="localhost:30080", insecure=True)

Automated Configuration Loading

The PlatformConfig.auto() method is the recommended approach for most deployments. It automatically reads connection and authentication settings from standard configuration files (e.g., config.yaml) and environment variables. This method prioritizes environment variables over configuration file settings.

from flytekit.configuration import PlatformConfig

# Load configuration automatically from default paths or a specified config file.
# This method simplifies deployment by externalizing configuration.
auto_config = PlatformConfig.auto()

# Example of a 'config.yaml' file that PlatformConfig.auto() would read:
# admin:
#   endpoint: "my-prod-admin.example.com:443"
#   insecure: false
#   authType: Pkce
#   clientId: "my-app-client-id"
#   clientSecretEnvVar: "FLYTE_CLIENT_SECRET" # Refers to an environment variable
#   caCertFilePath: "/etc/ssl/certs/my_custom_ca.pem"

Authentication Modes

The auth_mode parameter within PlatformConfig (backed by AuthType) dictates the authentication flow used to obtain and refresh credentials.

• PKCE (Proof Key for Code Exchange): This is the default (AuthType.STANDARD or AuthType.PKCE) and is recommended for interactive user authentication. It typically involves opening a browser for the user to log in and grant consent.

  from flytekit.configuration import PlatformConfig, AuthType
  
  pkce_config = PlatformConfig(
      endpoint="auth-enabled-admin.example.com:443",
      client_id="your-pkce-client-id",
      auth_mode=AuthType.PKCE,
      scopes=["openid", "profile", "email", "offline_access"]
  )

• Client Credentials: Use AuthType.CLIENT_CREDENTIALS or AuthType.CLIENTSECRET for service accounts or machine-to-machine authentication. The client secret can be provided directly, via an environment variable, or from a file. Loading from environment variables or files is more secure than direct embedding.

  from flytekit.configuration import PlatformConfig, AuthType
  import os
  
  # Option 1: Client secret from an environment variable
  # Ensure the environment variable is set before running the application.
  os.environ["FLYTE_SERVICE_SECRET"] = "your-very-secret-key"
  client_credentials_config_env = PlatformConfig(
      endpoint="auth-enabled-admin.example.com:443",
      client_id="your-service-client-id",
      # 'client_credentials_secret_env_var' is read by PlatformConfig.auto()
      # If instantiating directly, you would use 'client_credentials_secret'
      client_credentials_secret=os.getenv("FLYTE_SERVICE_SECRET"),
      auth_mode=AuthType.CLIENT_CREDENTIALS, # or AuthType.CLIENTSECRET
      scopes=["api"]
  )
  
  # Option 2: Client secret from a file (e.g., a mounted secret in a container)
  # Assuming 'client_secret.txt' contains the secret.
  # with open("client_secret.txt", "w") as f:
  #     f.write("another-very-secret-key")
  client_credentials_config_file = PlatformConfig(
      endpoint="auth-enabled-admin.example.com:443",
      client_id="your-service-client-id",
      # 'client_credentials_secret_location' is read by PlatformConfig.auto()
      # For direct instantiation, you'd read the file content yourself.
      client_credentials_secret=open("client_secret.txt").read().strip(),
      auth_mode=AuthType.CLIENT_CREDENTIALS,
      scopes=["api"]
  )
  
  # Option 3: Client secret directly (less secure, avoid if possible in production)
  client_credentials_config_direct = PlatformConfig(
      endpoint="auth-enabled-admin.example.com:443",
      client_id="your-service-client-id",
      client_credentials_secret="direct-secret-value",
      auth_mode=AuthType.CLIENT_CREDENTIALS,
      scopes=["api"]
  )

• External Command: For advanced scenarios, AuthType.EXTERNAL_PROCESS or AuthType.EXTERNALCOMMAND allows an external script or command to provide the access token. The command should output the token to standard output. This offers maximum flexibility for integrating with custom or complex identity providers.

  from flytekit.configuration import PlatformConfig, AuthType
  
  # Example: A script that fetches a token (e.g., from a cloud provider's CLI).
  # Ensure 'get_token.sh' is executable and outputs the token to stdout.
  # #!/bin/bash
  # echo "my-custom-access-token"
  external_command_config = PlatformConfig(
      endpoint="custom-auth-admin.example.com:443",
      command=["./get_token.sh"],
      auth_mode=AuthType.EXTERNAL_PROCESS
  )

• Device Flow: AuthType.DEVICEFLOW is suitable for input-constrained devices that cannot easily perform browser-based redirects.

  from flytekit.configuration import PlatformConfig, AuthType
  
  device_flow_config = PlatformConfig(
      endpoint="auth-enabled-admin.example.com:443",
      client_id="your-device-client-id",
      auth_mode=AuthType.DEVICEFLOW,
      scopes=["openid", "profile"]
  )

Secure Connections

By default, connections are secure using SSL/TLS. You can configure various aspects of this security:

• Insecure Connections: Use insecure=True for development or local setups without SSL. This bypasses certificate validation entirely.
• Skip Certificate Verification: insecure_skip_verify=True can be used to skip SSL certificate validation, but this is not recommended for production environments as it makes connections vulnerable to man-in-the-middle attacks.
• Custom CA Certificates: Specify ca_cert_file_path to provide a custom root CA certificate for verifying the platform's SSL certificate, useful in corporate environments with internal CAs.

from flytekit.configuration import PlatformConfig

# Secure connection with a custom CA certificate
secure_config = PlatformConfig(
    endpoint="secure-admin.example.com:443",
    ca_cert_file_path="/etc/ssl/certs/my_custom_ca.pem"
)

# Insecure connection (for local development or testing)
dev_config = PlatformConfig(endpoint="localhost:30080", insecure=True)

# Connection skipping certificate verification (use with extreme caution)
risky_config = PlatformConfig(
    endpoint="admin.example.com:443",
    insecure_skip_verify=True
)

HTTP Proxy for OAuth Requests

If your environment requires an HTTP proxy for outbound OAuth requests (e.g., to reach the identity provider's token endpoint), specify the http_proxy_url.

from flytekit.configuration import PlatformConfig, AuthType

proxy_config = PlatformConfig(
    endpoint="auth-enabled-admin.example.com:443",
    client_id="your-client-id",
    auth_mode=AuthType.PKCE,
    http_proxy_url="http://proxy.example.com:8080"
)

Best Practices and Considerations

• Security First: Always prioritize secure connections (SSL/TLS) and avoid insecure_skip_verify in production environments.
• Secret Management: For client secrets, prioritize loading from mounted files or environment variables over direct embedding in code. This minimizes exposure and improves security posture.
• Automated Configuration: Leverage PlatformConfig.auto() to simplify configuration management across different environments, promoting consistency and reducing manual errors.
• Scopes: Request only the necessary OAuth scopes to adhere to the principle of least privilege, limiting the access granted to your application.
• Error Handling: Implement robust error handling for connection and authentication failures to ensure your application can gracefully recover or inform the user.
• External Commands: Ensure any external commands used for token generation are robust, secure, and handle token refresh logic if necessary to maintain continuous authentication.