Skip to main content

SAML & OIDC Setup

This guide explains how to configure SAML and OIDC (OAuth2) authentication for Comper.

Comper Cloud​

Dedicated Environment (Custom URL)​

If you are using a dedicated Comper Cloud environment (e.g., yourcompany.comper.io), we can configure SAML/OIDC for you.

Please send us:

  1. The relevant metadata file (XML) from your Identity Provider (IdP).
  2. Any specific configuration details (attribute mappings, etc.).

Shared Environment​

SAML/OIDC configuration is not available for the shared Comper Cloud environment (app.comper.io).

Self-Hosted​

If you are hosting Comper yourself, you can configure SAML via environment variables or Helm chart values.

Comper supports SAML 2.0 authentication and can work with any SAML 2.0-compliant Identity Provider (IdP), including:

  • Google Workspace
  • Generic SAML 2.0 providers
  • Keycloak
  • Azure AD / Microsoft Entra ID
  • Okta
  • Other SAML 2.0-compliant IdPs

Google Workspace SAML Setup​

To configure SAML with Google Workspace as your Identity Provider:

  1. Get your IdP metadata from Google Workspace:

    • Follow the Google Workspace SAML setup guide to set up a custom SAML app
    • Download the IDP metadata file from the Google Admin console (Step 5 in the guide)
    • Alternatively, copy the SSO URL, Entity ID, and Certificate if your setup requires manual configuration

  2. Configure Comper with the information from Google Workspace:

    • ACS URL: https://<your-comper-domain>/api/saml/callback
    • Entity ID: Your Comper domain URL (e.g., https://comper.example.com)
    • Start URL (optional): Can be set in Google Workspace to redirect users after authentication

  3. In Google Workspace, provide Comper's Service Provider details:

    • ACS URL: https://<your-comper-domain>/api/saml/callback
    • Entity ID: https://<your-comper-domain> (or your preferred Entity ID)
    • Name ID: Use the primary email address (default)

For detailed instructions on configuring Google Workspace as an IdP, refer to the official Google Workspace SAML documentation.

Docker Configuration​

To enable SAML in your Docker deployment, set the following environment variables:

  • SAML_ENABLED: Set to true to enable SAML.
  • SAML_IDP_METADATA_PATH: Path to the IdP metadata XML file. This file must be accessible by the Comper container (e.g., mounted via a volume).
  • SAML_SP_ENTITY_ID: The Entity ID for the Service Provider (Comper). This is typically your Comper URL or a specific URI defined in your IdP.
  • SAML_SP_ACS_URL: The Assertion Consumer Service (ACS) URL. This is usually https://<your-comper-domain>/api/saml/callback.
  • SAML_PROVIDER: The provider type. Common values include generic, keycloak, azure-ad, okta, google-workspace.

Example docker-compose.yml snippet:

services:
  comper:
    environment:
      - SAML_ENABLED=true
      - SAML_IDP_METADATA_PATH=/config/idp-metadata.xml
      - SAML_SP_ENTITY_ID=https://comper.example.com
      - SAML_SP_ACS_URL=https://comper.example.com/api/saml/callback
      - SAML_PROVIDER=generic
    volumes:
      - ./idp-metadata.xml:/config/idp-metadata.xml

Kubernetes (Helm Chart)​

The Comper Helm chart supports SAML configuration.

Download the Helm chart:

After downloading:

# Extract the zip file
unzip comper-helm-chart.zip

# Navigate to the chart directory
cd helm-chart

You can provide the necessary values in your values.yaml file.

Step 1: Create a ConfigMap/Secret for Metadata First, create a ConfigMap or Secret containing your IdP metadata XML.

kubectl create configmap saml-metadata --from-file=metadata.xml=./path/to/idp-metadata.xml

Step 2: Configure Values

Update your values.yaml to enable SAML and mount the metadata file:

auth:
  saml:
    enabled: true
    # Path where the metadata file will be mounted
    idpMetadataPath: "/etc/comper/saml/metadata.xml"
    spEntityId: "https://comper.example.com"
    spAcsUrl: "https://comper.example.com/api/saml/callback"
    provider: "generic"

# Mount the ConfigMap as a volume
volumes:
  - name: saml-metadata
    configMap:
      name: saml-metadata

volumeMounts:
  - name: saml-metadata
    mountPath: /etc/comper/saml
    readOnly: true

Comper Support SAML​

Comper Support SAML allows the Comper support team to authenticate to your Comper instance for troubleshooting and support purposes. This feature is useful if your Comper instance is accessible on the internet and you need assistance from our support team.

Important Notes​

  • Access Control: Even with Comper Support SAML enabled, support team members must still be invited to individual boards by board administrators. This ensures that support access is granted only where needed.
  • Internet Access Required: Your Comper instance must be accessible on the internet for this feature to work.
  • Security: The support team uses SAML authentication through Comper's identity provider, ensuring secure access.

Enabling Comper Support SAML​

To enable Comper Support SAML, set the following environment variable:

  • COMPER_SUPPORT_SAML: Set to true to enable Comper Support SAML.

The configuration uses a pre-configured metadata file (comper-support-idp-metadata.xml) that is included with Comper. No additional configuration is required.

Example docker-compose.yml snippet:

services:
  comper:
    environment:
      - COMPER_SUPPORT_SAML=true

Kubernetes (Helm Chart) configuration:

auth:
  comperSupportSaml:
    enabled: true

Once enabled, Comper support team members can authenticate to your instance using SAML, but they will still need to be invited to specific boards by your board administrators.

OIDC (OAuth2) Configuration​

Comper supports OIDC via specific OAuth2 providers. The following providers are supported:

  • Google
  • GitHub
  • Microsoft Entra ID (formerly Azure AD)

You can configure these using the following environment variables.

Supported Providers​

Google​

  • GOOGLE_OAUTH_CLIENT_ID
  • GOOGLE_OAUTH_CLIENT_SECRET

GitHub​

  • GITHUB_OAUTH_CLIENT_ID
  • GITHUB_OAUTH_CLIENT_SECRET

Microsoft Entra ID (Azure AD)​

  • MICROSOFT_OAUTH_CLIENT_ID
  • MICROSOFT_OAUTH_CLIENT_SECRET
  • MICROSOFT_OAUTH_TENANT_ID (optional, defaults to common if not specified)

Docker Configuration​

To enable OIDC providers in your Docker deployment, set the environment variables for the providers you want to use:

Example docker-compose.yml snippet:

services:
  comper:
    environment:
      # Google OAuth
      - GOOGLE_OAUTH_CLIENT_ID=your-google-client-id
      - GOOGLE_OAUTH_CLIENT_SECRET=your-google-client-secret
      
      # GitHub OAuth
      - GITHUB_OAUTH_CLIENT_ID=your-github-client-id
      - GITHUB_OAUTH_CLIENT_SECRET=your-github-client-secret
      
      # Microsoft Entra ID OAuth
      - MICROSOFT_OAUTH_CLIENT_ID=your-microsoft-client-id
      - MICROSOFT_OAUTH_CLIENT_SECRET=your-microsoft-client-secret
      - MICROSOFT_OAUTH_TENANT_ID=your-tenant-id  # Optional, defaults to 'common'

Kubernetes Configuration​

For Kubernetes, these secrets are typically managed via the auth.oauth section in values.yaml:

auth:
  oauth:
    microsoft:
      clientId: "..."
      tenantId: "..."
      clientSecret: "..."
    google:
      clientId: "..."
      clientSecret: "..."
    github:
      clientId: "..."
      clientSecret: "..."