Google (OIDC)

This guide walks through running Carbon Panel with Google as an OIDC identity provider. Unlike Keycloak or Authelia, Google is an external cloud provider — no IdP container is needed.

Prerequisites

Docker and Docker Compose
A Google account (or Google Workspace organization)

Create Google OAuth credentials

Go to the Google Cloud Console — Credentials
Create or select a project
If you haven’t already, configure the OAuth consent screen:
- User type: External (or Internal if using Google Workspace and you only want org users)
- App name, support email, and developer email are required
- Scopes: add openid, profile, and email
- For external apps: add test users while in “Testing” status, or publish the app for general access
Click Create Credentials → OAuth client ID
- Application type: Web application
- Authorized redirect URIs: add http://localhost:8080/api/v1/auth/oidc/callback
- For production: add your public URL (must be HTTPS), e.g. https://panel.example.com/api/v1/auth/oidc/callback
Copy the Client ID and Client Secret

Docker Compose

Paste your Client ID and Client Secret into the compose file, then start the stack:

cd oidc/google
docker compose up -d

# SPDX-License-Identifier: MIT AND MPL-2.0
# This file includes DiscoPanel material under the MIT License,
# Copyright (c) 2025 Nicholas W. Heyer. The MIT license text is in LICENSE
# and still applies to that inherited material.
# Maintainer changes are licensed under the Mozilla Public License, v. 2.0.
# If a copy of the MPL was not distributed with this file, You can obtain
# one at https://mozilla.org/MPL/2.0/.


# Carbon Panel + Google (OIDC)
#
# This is a complete docker-compose with OIDC authentication pre-configured using Google as the identity provider.
#
# Unlike Keycloak/Authelia examples, Google is an external provider - no IdP container needed.
#
# PREREQUISITES:
#   1. Go to https://console.cloud.google.com/apis/credentials
#   2. Create or select a project
#   3. Click "Create Credentials" > "OAuth client ID"
#   4. Application type: "Web application"
#   5. Authorized redirect URIs: add "http://localhost:8080/api/v1/auth/oidc/callback"
#   6. Copy the Client ID and Client Secret into the environment variables below
#
# NOTE ON ROLES:
#   Google does not include a "groups" claim in its ID token by default.
#   Users will be assigned CARBONPANEL's default roles on first login.
#   To promote a user to admin, use the Carbon Panel UI after they log in.
#
#   If you use Google Workspace and want automatic role mapping, you can:
#     - Use "hd" (hosted domain) as CARBONPANEL_AUTH_OIDC_ROLE_CLAIM with a role mapping
#     - Or use Google Workspace Admin SDK to populate a custom claim via middleware
#     - See: https://developers.google.com/identity/openid-connect/openid-connect

services:
  carbon-panel:
    build:
      context: ../../
      dockerfile: docker/Dockerfile.carbon-panel
    #image: athNdev/carbon-panel:dev
    container_name: carbon-panel
    restart: unless-stopped
    network_mode: host
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - /tmp/carbon-panel:/app/data
    environment:
      - TZ=UTC

      #  ------------------------------------ AUTH CONFIG STARTS HERE FOR CARBON PANEL + GOOGLE ------------------------------------
      - CARBONPANEL_AUTH_LOCAL_ENABLED=true
      - CARBONPANEL_AUTH_OIDC_ENABLED=true

      # GOOGLE OIDC ISSUER - DO NOT CHANGE
      - CARBONPANEL_AUTH_OIDC_ISSUER_URI=https://accounts.google.com

      # PASTE YOUR GOOGLE OAUTH CLIENT ID HERE (from Google Cloud Console)
      - CARBONPANEL_AUTH_OIDC_CLIENT_ID=REPLACE_ME.apps.googleusercontent.com

      # PASTE YOUR GOOGLE OAUTH CLIENT SECRET HERE (from Google Cloud Console)
      - CARBONPANEL_AUTH_OIDC_CLIENT_SECRET=GOCSPX-REPLACE_ME

      # FOR LOCAL DEV: Google allows http://localhost redirects without HTTPS.
      # FOR PRODUCTION: Google requires HTTPS - change to your public domain (ie: https://mypanel.com/api/v1/auth/oidc/callback)
      # THIS MUST MATCH EXACTLY WHAT YOU ENTERED IN GOOGLE CLOUD CONSOLE UNDER "Authorized redirect URIs"
      - CARBONPANEL_AUTH_OIDC_REDIRECT_URL=http://localhost:8080/api/v1/auth/oidc/callback

      # Google does not provide a "groups" claim by default.
      # Leave empty to skip automatic role mapping - users get default roles and can be promoted manually.
      # If using Google Workspace, you can set this to "hd" and add a role mapping (see below).
      - CARBONPANEL_AUTH_OIDC_ROLE_CLAIM=

      # OPTIONAL: Map Google Workspace domain to a Carbon Panel role.
      # Uncomment and modify if using "hd" as ROLE_CLAIM above:
      # - CARBONPANEL_AUTH_OIDC_ROLE_MAPPING={"yourdomain.com":"admin"}

Key environment variables

Variable	Purpose
`CARBONPANEL_AUTH_OIDC_ENABLED`	Enables OIDC authentication
`CARBONPANEL_AUTH_OIDC_ISSUER_URI`	Always `https://accounts.google.com` — do not change
`CARBONPANEL_AUTH_OIDC_CLIENT_ID`	Your OAuth Client ID from Google Cloud Console
`CARBONPANEL_AUTH_OIDC_CLIENT_SECRET`	Your OAuth Client Secret from Google Cloud Console
`CARBONPANEL_AUTH_OIDC_REDIRECT_URL`	The callback URL — must match exactly what you entered in Google Cloud Console
`CARBONPANEL_AUTH_OIDC_ROLE_CLAIM`	Leave empty for Google — see Role mapping below

Role mapping

Google’s OIDC tokens include standard claims (sub, email, name, picture, hd) but not a groups claim. This means automatic group-to-role mapping isn’t available out of the box.

For most setups: leave CARBONPANEL_AUTH_OIDC_ROLE_CLAIM empty. Users get default roles on first login, and an admin can promote them in the Carbon Panel UI.

For Google Workspace organizations: you can use the hd (hosted domain) claim to map an entire domain to a role:

- CARBONPANEL_AUTH_OIDC_ROLE_CLAIM=hd
- CARBONPANEL_AUTH_OIDC_ROLE_MAPPING={"yourdomain.com":"admin"}

This assigns the admin role to everyone who logs in from yourdomain.com.

Default credentials

Service	URL	Login
Carbon Panel	http://localhost:8080	Log in via Google

Production notes

Use HTTPS: Google requires HTTPS redirect URIs for non-localhost deployments
Update the redirect URI: change localhost:8080 to your public domain in both the compose file and Google Cloud Console
Publish the OAuth consent screen: while in “Testing” status, only manually added test users can log in
Restrict by organization (optional): set the consent screen to Internal in Google Workspace to limit login to your org
Disable local auth (optional): set CARBONPANEL_AUTH_LOCAL_ENABLED=false if you want OIDC-only login