WoodenDollars / Docs
OverviewAPI ReferenceSSO Setup

SSO Setup

WoodenDollars supports single sign-on via OpenID Connect (OIDC) for Google Workspace and Microsoft Entra ID. Once configured, users sign in through their identity provider — no separate WoodenDollars password required.

How it works

1

Configure in WoodenDollars

Enter your identity provider's Client ID, Client Secret, and Issuer URL in Admin → SSO.

2

Users sign in via IdP

On the login page, users enter their company's short name and click "Sign in with Google/Microsoft".

3

Automatic provisioning

First-time users are automatically created. Existing users by email are linked. Roles can be assigned via group mappings.

Callback URL

When registering WoodenDollars with your identity provider, use the following redirect / callback URL format. Replace app.yourdomain.com with your actual WoodenDollars application URL.

https://app.yourdomain.com/api/v1/auth/sso/google/callback

Prerequisites

  • · A Google Workspace account (any edition)
  • · Super Administrator or delegated admin access to your Google Workspace domain
  • · Access to Google Cloud Console with permission to create OAuth 2.0 credentials

Step 1 — Create OAuth 2.0 credentials

  1. 1 Go to Google Cloud Console → select or create a project → APIs & Services → Credentials.
  2. 2 Click Create Credentials → OAuth client ID. If prompted, configure the OAuth consent screen first. Set the user type to Internal (recommended for Workspace) so only your organisation's users can sign in.
  3. 3 Application type: Web application. Set a name (e.g. "WoodenDollars").
  4. 4
    Under Authorised redirect URIs, add:
    https://app.yourdomain.com/api/v1/auth/sso/google/callback
  5. 5 Click Create. Copy the Client ID and Client Secret — you'll need both in the next step.

Step 2 — Configure in WoodenDollars

  1. 1 In WoodenDollars, go to Admin → SSO → Google and toggle Google SSO on.
  2. 2 Enter the Client ID and Client Secret from Step 1.
  3. 3
    Set the Issuer URL to:
    https://accounts.google.com
  4. 4 Click Save, then Test Connection to verify the OIDC discovery endpoint is reachable.
Done. Your team can now sign in via Google at /login/your-short-name.

Step 3 — Group-based role mapping (optional)

Map Google Workspace groups to WoodenDollars roles so users are automatically assigned the correct role when they sign in. This requires a service account with domain-wide delegation because Google's OIDC token does not include group membership — WoodenDollars uses the Admin Directory API to look up groups on your behalf.

3a — Enable the Admin SDK API

  1. 1 In Google Cloud Console → APIs & Services → Library, search for Admin SDK API and enable it.

3b — Create a service account

  1. 1 In Google Cloud Console → IAM & Admin → Service Accounts → Create service account. Give it a name (e.g. "WoodenDollars SSO"). You do not need to assign any IAM roles to this account.
  2. 2 Open the service account → Keys → Add key → Create new key → JSON. Save the downloaded .json file — you will paste its contents into WoodenDollars shortly.

3c — Grant domain-wide delegation

  1. 1 In the service account details page, click Edit → Show advanced settings and note the Unique ID (client_id) — it's a long number like 112233445566778899.
  2. 2 Go to Google Admin Console (admin.google.com) → Security → Access and data control → API controls → Manage domain-wide delegation → Add new.
  3. 3
    Enter the service account's numeric Client ID and add the following OAuth scope:
    https://www.googleapis.com/auth/admin.directory.group.readonly

3d — Enter credentials in WoodenDollars

  1. 1 In Admin → SSO → Google:
Service Account EmailThe client_email value from the JSON key file (e.g. woodendollars-sso@my-project.iam.gserviceaccount.com)
Service Account KeyThe full contents of the downloaded JSON key file
Admin EmailA Google Workspace admin account email used for impersonation (e.g. admin@yourdomain.com)

3e — Add role mappings

  1. 1 Go to Admin → SSO → Role Mappings → Add mapping.
  2. 2
    For the Group identifier, use any of the following from Google Admin Console:
    • The group's ID from the Admin URL — e.g. 04kpvwfh0g3f5x5 (visible in admin.google.com/ac/groups/<id>)
    • The group's email address — e.g. finance@yourdomain.com
    • The group's display name — e.g. Finance
  3. 3 Select the WoodenDollars role to assign and a priority (lower number wins when a user belongs to multiple mapped groups).
Role sync: By default, roles are only applied on the user's first login (JIT provision). Enable Sync roles on every login in the SSO config to re-evaluate group membership on each sign-in.

Troubleshooting

Users see "SSO not configured for this tenant"

SSO has not been enabled for this provider in Admin → SSO. Toggle the provider on and save.

Redirect URI mismatch error from the identity provider

The redirect URI registered with your IdP must exactly match https://app.yourdomain.com/api/v1/auth/sso/{provider}/callback. Ensure there is no trailing slash, and that the /api/ prefix is present — the URL routes through the WoodenDollars frontend proxy.

Group mappings are not being applied

Check the following:

  • Google: Service account credentials and Admin Email are configured. The Admin SDK API is enabled. Domain-wide delegation is set up with the correct scope and service account Client ID.
  • Microsoft: The groups optional claim is added to the ID token in Token configuration. Admin consent has been granted for GroupMember.Read.All.
  • The group identifier in the role mapping exactly matches the group ID, email, or name from your IdP.
  • If the user was already provisioned, enable Sync roles on every login — otherwise roles are only applied on first sign-in.
"OIDC discovery failed" when testing connection

The Issuer URL is incorrect or unreachable from the WoodenDollars server. For Google use https://accounts.google.com. For Microsoft use https://login.microsoftonline.com/{tenant-id}/v2.0 with your actual Directory (tenant) ID substituted.

Need help? Contact support@woodendollars.com