Knowledge base / Setup

Sign-in via Microsoft Entra ID

App registration, roles and the matching settings in Kontris.

Kontris signs users in via OpenID Connect and reads their role from the app roles of the registration. You need the role Application Administrator in Entra.

https://contracthub.example.com stands for your APP_BASE_URL below.

1. Register the app

  1. In the Entra admin center: Identity → Applications → App registrations → New registration.
  2. Name Kontris, account type Single tenant.
  3. Redirect URI: platform Web, https://contracthub.example.com/auth/callback.
  4. Note the Application (client) ID and the Directory (tenant) ID from the overview page.

2. Secret or certificate

Secret: Certificates & secrets → New client secret. Copy the Value right away; it is shown only once. Note the expiry date.

Certificate (recommended): The private key stays on your server; only the certificate goes to Entra.

sudo mkdir -p /opt/contracthub/oidc && cd /opt/contracthub/oidc
sudo openssl req -x509 -newkey rsa:3072 -nodes -days 730 \
  -subj "/CN=Kontris" -keyout client.key -out client.crt
sudo chown 1000:1000 client.key && sudo chmod 400 client.key

Upload client.crt under Certificates & secrets → Certificates and mount the folder in compose.yaml:

    volumes:
      - ./oidc:/oidc:ro

3. Create the app roles

Under App roles → Create app role, three times, each for Users/Groups:

Display name Value Meaning
Kontris Admin ContractHub.Admin Full access
Kontris Auditor ContractHub.Auditor Read access to everything, including the audit log
Kontris User ContractHub.User Access according to folder permissions

The values must be written exactly like this. If someone has several roles, the highest one applies.

4. Permissions and claims

  1. API permissions: The delegated permissions openid, profile and email are enough. Click Grant admin consent.
  2. Token configuration → Add optional claim → ID → email.

Kontris does not need group claims.

5. Assign users

Under Enterprise applications → Kontris → Users and groups assign one of the three roles to users or groups. Anyone without a role is rejected at sign-in.

6. Configure Kontris

In contracthub.env:

OIDC_ENABLED=true
OIDC_PROVIDER=entra
OIDC_TENANT_ID=<Directory (tenant) ID>
OIDC_CLIENT_ID=<Application (client) ID>

# either a secret …
OIDC_CLIENT_SECRET=<Value>
# … or a certificate
# OIDC_CLIENT_CERT_FILE=/oidc/client.crt
# OIDC_CLIENT_KEY_FILE=/oidc/client.key

Then restart:

docker compose up -d --force-recreate contracthub

The sign-in page now shows Sign in with Microsoft. Local accounts remain as a second way as long as LOCAL_AUTH_ENABLED=true is set.

Good to know

  • Existing local users are taken over by email address at their first sign-in via Entra (OIDC_LINK_LOCAL_USERS, on by default).
  • Groups from Entra: If you create further app roles, you can map them to a group in Kontris under Administration → Groups. Members are synchronized at every sign-in.
  • Disabled accounts: With ENTRA_ACCOUNT_CHECK_ENABLED=true Kontris checks every night whether accounts were disabled or deleted in Entra. The app registration needs the application permission User.Read.All for this.
  • Emergency access: For the case that Entra is unreachable there is an emergency account (BREAK_GLASS_*). Every use is recorded in the audit log.

As of 2026-11-15 · Stuck? Write to us