auth-bundle chart

The auth bundle provides all necessary components to enable auth capabilities in a giantswarm cluster.

Apps

• dex-app
• athena
• rbac-bootstrap-app
• ingress-nginx

Installing

Quick Start

The auth-bundle can be installed using Giant Swarm's web interface or via direct Kubernetes resource deployment. For a quick installation, follow these steps:

1. Web Interface Installation:

   • Navigate to our web interface.
   • Select your organization, then your cluster and choose the option to install a new app.
   • Search for auth-bundle from the Giant Swarm Catalog and follow the on-screen instructions.

2. Direct Kubernetes Resource Deployment:

   • Ensure you have the app CRD installed in your management cluster.
   • Create an App resource in the management cluster as explained in Getting started with App Platform.

Configuring

The auth-bundle can be configured in 2 different ways: "Default configuration" and "Full configuration". These 2 ways can be combined if needed.

Default configuration

Default configuration minimizes manual setup and performs the most of the auth-bundle apps' configuration automatically. You only need to provide the configuration of Dex connectors you intend to use and basic rbac setup. Everything else is taken care of automatically.

Default configuration is suitable for basic use cases, which do not require any fine-tuning.

Config properties

# Optional: Default configuration root object
defaultConfig:

  # Optional: Determines whether the K8s Authenticator is deployed together with Dex.
  # The K8s Authenticator is deprecated and will be removed in the future versions of the platform.
  # It does not need to be deployed unless there is an existing need for it originating in the past while using legacy versions of the platform.
  deployDexK8SAuthenticator: false

  # Required: In case the defaultConfig is defined, the oidc property is required
  oidc:

     # Optional: Defines expiration rules for tokens generated by Dex
     expiry:
        signingKeys: 6h
        idTokens: 30m

     # Required: Specification of Dex connectors
     customer: 
        connectors:
           - id: CONNECTOR_ID # common name is "customer"
             connectorName: CONNECTOR_NAME
             connectorType: CONNECTOR_TYPE # e.g. "microsoft", "github", etc.
             connectorConfig: |- # specific configuration based on connector type, structure comes from Dex.
                clientID: CLIENT_ID
                clientSecret: CLIENT_SECRET
                tenant: TENANT_ID
                redirectURI: CALLBACK_URL # optional: if omitted, it will be provided automatically

  # Optional but recommended: RBAC setup
  rbac:
  - role: ROLE_NAME # required
    namespaces: # optional: if omitted, cluster-wide bindings are created
    - NAMESPACE
    groups: # either groups or users or both are required
    - CUSTOMER_GROUP_NAME
    users:
    - USER_NAME

Ensure that you enable the required OIDC settings on the cluster resource.

Most Dex connectors require credentials to be provided in the configuration. Therefore, it is recommended to include the default configuration in a secret when installing the auth-bundle.

Connector configuration (defaultConfig.oidc.customer.connectors[n].connectorConfig) format depends on the connector type (defaultConfig.oidc.customer.connectors[n].connectorType). All supported connector types and configuration formats can be found in Dex documentation.

Example configuration

This example shows the minimum required configuration for Microsoft connector in Dex.

defaultConfig:
  oidc:
     customer: 
        connectors:
           - id: customer
             connectorName: your_name_here
             connectorType: microsoft
             connectorConfig: |
                clientID: CLIENT_ID
                clientSecret: CLIENT_SECRET
                tenant: TENANT_ID
  rbac:
  - role: cluster-admin
    groups:
    - CUSTOMER_GROUP_NAME

Full configuration

Full configuration enables you to set up each app in the auth-bundle separately. It requires more values to be provided manually, but it supports more advanced and fine-tuned configurations for more complex use cases.

Each app within the auth-bundle can be configured to meet your specific needs. For each app you can use userConfig to supply values or extraConfigs as secret or configmap

In case both Default configuration and Full configuration are specified, the Full configuration takes priority and overwrites the intersecting sections of the Default configuration.

Example configuration

apps:
  athena:
    userConfig:
      configMap:
        values: |
          managementCluster:
            name: op2df
  dex-app:
    userConfig:
      configMap:
        values: |
          isWorkloadCluster: true
          deployDexK8SAuthenticator: false
      secret: true
  ingress-nginx:
    enabled: false

Dex-app Configuration

• Enable access to your cluster via dex: ensure that the needed oidc settings are enabled on the cluster resource.
• Deploying Dex K8s Authenticator: Optional based on requirements. Can be enabled with deployDexK8SAuthenticator: true.
• Copying OIDC Configuration: It's possible to copy the OIDC part from the MC to the WC, ensuring seamless authentication across clusters.

Athena Configuration

• Setup Guide: Detailed instructions on setting up Athena for authentication management, highlighting its integration with Dex in Workload Clusters.

Troubleshooting Common Issues

• Dex-app Authentication Failure: Verify the Secret contains the correct OIDC provider details. Ensure the dex-app configuration matches your provider's requirements.
• RBAC Permissions Issues: Check the rbac-bootstrap-app has been configured with correct policies. Ensure roles and role bindings are correctly applied.
• Ingress and External-DNS: Ingress and External DNS configuration challenges, including ingress class settings and external DNS behavior when nginx is not in the kube-system namespace, or when the ingress is not pubilcally accessible.