Documentation contents

SSO with OIDC

Employees can use their company accounts in a browser or on macOS. The Windows and Linux apps require a Gadka password.

Gadka supports OpenID Connect (OIDC) with any compatible identity provider (IdP). Once you configure a provider in the server configuration file, a Sign in with … button appears on the login screen.

Before you begin

  • You need administrator access to the IdP.
  • You need root access to the Gadka server.
  • You need an existing workspace. See First startup.

SSO is available in the web app and the macOS app. The Windows and Linux apps do not yet support SSO. Users of those apps sign in with a password.

1. Register a web application with your IdP

  1. Create a web application as a confidential client with a secret.
  2. For the redirect URI, use Gadka's public URL followed by /v1/auth/oidc/callback.
https://gadka.example.com:6543/v1/auth/oidc/callback
  1. Allow the openid, email and profile scopes.
  2. Record the issuer URL, client ID and client secret.

2. Save the secret on the server

sudo install -o root -g gadka -m 0640 /dev/null /etc/gadka/oidc-client-secret
sudo nano /etc/gadka/oidc-client-secret

3. Add the provider to the configuration

Edit the auth section of /etc/gadka/gadka.yaml.

auth:
  oidc:
    providers:
      - id: firma-sso
        tenant_slug: firma
        display_name: Firmowe SSO
        issuer: https://sso.example.com/realms/firma
        client_id: gadka
        client_secret_file: /etc/gadka/oidc-client-secret
        auto_provision: false
        allowed_email_domains: [example.com]
FieldDescription
idUnique provider identifier used in URLs
tenant_slugWorkspace users sign in to through this provider
display_nameName displayed on the Sign in with … button
issuerIssuer URL, exactly as it appears in tokens
discovery_urlOptional URL for reaching the IdP from the server if it differs from the public URL
client_id, client_secret_fileClient ID from step 1 and path to the file containing its secret
auto_provisionSet to true to create a member account when a user first signs in
allowed_email_domainsEmail domains allowed for auto_provision

The required fields are id, tenant_slug, display_name, issuer and client_id.

4. Restart the server and test the connection

sudo systemctl restart gadka

Open the login screen and enter the domain and workspace. With the example configuration, Sign in with Firmowe SSO should appear below the fields.

How Gadka matches accounts

  • The IdP must include email and email_verified: true in the token. Users can sign in only with a verified email address.
  • The first time someone signs in through SSO, Gadka links an existing account to the IdP account by email address.
  • If there is no account and auto_provision is off, the user sees This account has no access to this workspace. Ask an administrator for an invitation.
  • An automatically created account gets the Member role and counts toward the license limit. Manage roles in Gadka. Gadka does not map roles or groups from the IdP.
  • If the IdP confirms multifactor authentication in the token (an amr claim containing mfa or otp), the session satisfies the requirement for a second factor for administrators.

Profile attributes from the IdP

You can populate profile fields from token claims.

        attributes: { title: job_title, department: department, phone: phone_number, timezone: zoneinfo }
        force_attributes: [department]

The supported fields are title, department, phone and timezone. Gadka saves their values each time someone signs in. If a user edits a field manually, Gadka keeps that value unless the field appears in force_attributes.