Truke KF supports two ways to manage user authentication: built-in users stored in the same database as the KF data, and Single Sign-On via an external identity provider using OpenID Connect (OIDC).
The default configuration stores user credentials in the KF database. No extra setup is required — this is the sql mode, and it is active when no `[oidc]` section is present in kf.ini.
Each user has three fields: a username (typically an email address), a password, and an ACL label string. ACL labels control what items the user can see and edit — see access control for details.
Users can be added, changed, or removed through the administration interface at `/admin/users`.
OIDC delegates authentication to an external identity provider (IdP) such as Google, Microsoft Entra (Azure AD), or a self-hosted Keycloak or Dex instance. Users log in through the IdP — KF never sees their password. The IdP issues a signed token that KF verifies; if the signature is valid the user is granted access.
OIDC and built-in users coexist. The login page shows both a password form and a Single Sign-On button; users can use whichever method applies to them.
Add an `[oidc]` section to kf.ini:
[oidc] provider=https://accounts.google.com client_id=123456789-abc.apps.googleusercontent.com client_secret=GOCSPX-… redirect_url=https://yourapp.example.com/oidc/callback default_acl=staff
| Key | Required | Description |
|---|---|---|
provider | yes | OIDC discovery base URL — KF appends `/.well-known/openid-configuration` to find all endpoints automatically |
client_id | yes | Client ID issued by the IdP |
client_secret | yes | Client secret issued by the IdP |
redirect_url | yes | Must exactly match the callback URL registered at the IdP: https://yourapp.example.com/oidc/callback |
default_acl | no | ACL label(s) assigned to new users on their first login (default: staff) |
When provider is absent or empty, OIDC is disabled.
When a user logs in via OIDC for the first time, KF checks whether their email address exists in the user database. If not, a record is created automatically with an empty password and the default_acl value. On subsequent logins the existing record is used — the ACL can be changed manually in `/admin/users` at any time.
To pre-provision a user before their first login, add them through `/admin/users` and leave the password empty.
1. Go to Google Cloud Console → APIs & Services → Credentials.
2. Create an OAuth 2.0 Client ID of type Web application.
3. Add https://yourapp.example.com/oidc/callback to Authorised redirect URIs.
4. Copy the client ID and secret into kf.ini.
provider=https://accounts.google.com
1. Register an application in Azure Active Directory → App registrations.
2. Add https://yourapp.example.com/oidc/callback as a redirect URI (type: Web).
3. Create a client secret under Certificates & secrets.
4. Note your tenant ID (Directory ID).
provider=https://login.microsoftonline.com//v2.0
1. Create a client in your realm with Client authentication enabled.
2. Set the valid redirect URI to https://yourapp.example.com/oidc/callback.
3. Copy client ID and secret.
provider=https://keycloak.example.com/realms/
Dex is a lightweight self-hosted OIDC provider that federates identities from LDAP, Active Directory, GitHub, Google, Microsoft, and SAML 2.0 IdPs. It is a good choice for on-premises deployments or when connecting KF to a legacy SAML identity provider.
1. Install Dex
# Binary curl -Lo dex https://github.com/dexidp/dex/releases/latest/download/dex_linux_amd64 chmod +x dex # Docker docker pull ghcr.io/dexidp/dex:latest
2. Write config.yaml
issuer: https://dex.example.com/dex
storage:
type: sqlite3
config:
file: /var/dex/dex.db
web:
http: 0.0.0.0:5556
oauth2:
responseTypes: [code]
skipApprovalScreen: true
staticClients:
- id: kfserver
secret: change-me-to-a-long-random-string
name: Truke KF
redirectURIs:
- https://yourapp.example.com/oidc/callback
connectors:
- type: ldap
id: ldap
name: Active Directory
config:
host: ldap.example.com:636
bindDN: cn=service-account,dc=example,dc=com
bindPW: secret
userSearch:
baseDN: ou=users,dc=example,dc=com
filter: "(objectClass=person)"
username: sAMAccountName
emailAttr: mail
nameAttr: displayName
Replace the connectors block with the upstream source that fits your environment. Dex also supports GitHub, SAML 2.0 (ADFS, Shibboleth), and others.
3. Start Dex and verify
./dex serve config.yaml curl https://dex.example.com/dex/.well-known/openid-configuration
4. Configure kfserver
The provider value must match the issuer string in config.yaml exactly.
[oidc] provider=https://dex.example.com/dex client_id=kfserver client_secret=change-me-to-a-long-random-string redirect_url=https://yourapp.example.com/oidc/callback