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
- In the Entra admin center: Identity → Applications → App registrations → New registration.
- Name
Kontris, account type Single tenant. - Redirect URI: platform Web,
https://contracthub.example.com/auth/callback. - 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
- API permissions: The delegated permissions
openid,profileandemailare enough. Click Grant admin consent. - 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=trueKontris checks every night whether accounts were disabled or deleted in Entra. The app registration needs the application permissionUser.Read.Allfor 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