Authentication & Permissions¶
Authentication Methods¶
koala supports three authentication methods:
Local Accounts¶
Local accounts are stored in the MySQL database with hashed and salted passwords. These are the primary account type and support all permissions.
LDAP¶
LDAP authentication delegates user verification to an external directory server. Users authenticate against the LDAP server, but still require a local account with assigned permissions (see below).
Configuration: WEB_LDAP_ENABLE, WEB_LDAP_HOST, WEB_LDAP_PORT, WEB_LDAP_BASE_DN, WEB_LDAP_FILTER
OpenID Connect (SSO)¶
OpenID Connect provides enterprise single sign-on. Users authenticate through an OIDC provider (e.g., Keycloak, Okta, Google). Like LDAP, OIDC users require a local account with assigned permissions.
Configuration: WEB_SSO_ENABLED, WEB_SSO_ISSUER, WEB_SSO_CLIENT_ID, WEB_SSO_CLIENT_SECRET
Important: Local Account Requirement¶
Regardless of the authentication method, every user must have a local account in koala's database. Remote authentication (LDAP/OIDC) only verifies identity — it does not create accounts or assign permissions.
Functional/service accounts with api permission must be local accounts. They cannot use LDAP or OIDC authentication.
Permissions¶
Permissions control access to UI and API functions. They are assigned when creating or editing users via the web UI.
| Permission | UI Access | API Access |
|---|---|---|
admin |
Full access to all pages | All endpoints, including asset/AIP deletion |
monitor |
Dashboard view only | No API access |
api |
No UI access | All endpoints, including asset/AIP deletion |
api_restricted |
No UI access | All endpoints except asset/AIP deletion |
Session Management¶
- Sessions use Flask server-side sessions with a secret key (
WEB_SECRET_KEY) - Session lifetime is controlled by Flask's
PERMANENT_SESSION_LIFETIME - Logout is available via the web UI (
/logout) - API endpoints use HTTP Basic Auth (no session cookies)
Password Policy¶
- Passwords are hashed using Werkzeug's
generate_password_hash()with PBKDF2-SHA256 - Each password is salted with a unique random salt
- Passwords cannot be retrieved — only reset by an administrator
Permission Matrix¶
| Endpoint Category | admin | monitor | api | api_restricted |
|---|---|---|---|---|
| Dashboard | Yes | Yes | — | — |
| Ingest status query | Yes | Yes | — | — |
| User management | Yes | — | — | — |
| Schema management | Yes | — | — | — |
| Filetype management | Yes | — | — | — |
| Audit log | Yes | — | — | — |
| Asset retrieval | Yes | — | Yes | Yes |
| Asset deletion | Yes | — | Yes | No |
| AIP deletion | Yes | — | Yes | No |
| SBS upload/download | Yes | — | Yes | Yes |
| SBS delete | Yes | — | Yes | No |
| Health/stats | Yes | — | Yes | Yes |