mailcow-dockerized/data/web/admin/system.php
Lorenzo Moscati 2597618718
[Web] Add SCIM 2.0 provider for IdP user provisioning
Implements a SCIM 2.0 (RFC 7643/7644) server endpoint so any Identity
Provider — Keycloak, Entra ID, Okta, or any LDAP/OIDC IdP — can push
user lifecycle events to mailcow in real time, independently of whichever
login protocol is configured.

## Protocol support

- Full Users CRUD: POST, GET, PUT, PATCH (RFC 7644 §3.5.2), DELETE
- SCIM DELETE is a soft-deactivate (active=0); mail data is never removed
- Filtering: filter=userName eq "..." on list endpoint
- Pagination: startIndex / count
- Discovery: ServiceProviderConfig, Schemas, ResourceTypes
- Groups: out of scope

## Authentication & token management

Bearer tokens are generated in the admin UI (System > Configuration >
Access > SCIM). The raw token is shown once at creation and never stored;
only its SHA-256 hash is kept. Each token supports:
- Optional domain restriction (limits which mailboxes the token can manage)
- Optional mailbox template (applied on user creation)
- Optional IP allow-list / skip-IP-check flag
- Active/inactive toggle

## Database schema

Two new tables added via the existing init_db migration mechanism:
- scim_tokens: stores token metadata and hashed credentials
- scim_maps: maps IdP externalId values to mailcow usernames per token
The mailbox.authsource ENUM is extended with 'scim'.

## Authsource & login design

SCIM is a provisioning protocol, not an authentication protocol.
mailbox.authsource='scim' records who manages the user; login is
handled by the globally configured IAM provider:

- Keycloak / Generic-OIDC: SCIM users pass through the existing
  verify-sso OIDC flow (identity_provider 'verify-sso' case).
- LDAP: SCIM users authenticate via ldap_mbox_login(), with full
  TFA support, matching the behaviour of authsource='ldap' users.
- No IAM configured: SCIM users cannot log in; the admin UI shows
  a warning on the SCIM configuration tab.

Attempting a password login as a SCIM user when an OIDC provider is
configured returns a clear error directing the user to their IdP.

## Claiming pre-existing users

A SCIM POST for a user who already has authsource='scim' (e.g. set
manually by the admin to prepare a migration) is treated as a claim:
attributes are updated, scim_maps is upserted, and 200 is returned.
A SCIM POST for a user managed by a different authsource returns 409
with an actionable message explaining how to transfer ownership.

## Admin UI

- New SCIM tab under System > Configuration > Access (alongside
  Identity Provider settings)
- Token table with active toggle and delete; one-time raw token modal
- Mailbox edit form gains a SCIM authsource option, shown only when
  SCIM tokens exist (or the mailbox is already set to SCIM)
- Contextual warning when no external IdP is configured for login
2026-08-01 11:44:24 +02:00

137 lines
4.9 KiB
PHP

<?php
require_once $_SERVER['DOCUMENT_ROOT'] . '/inc/prerequisites.inc.php';
require_once $_SERVER['DOCUMENT_ROOT'] . '/inc/triggers.admin.inc.php';
protect_route(['admin']);
require_once $_SERVER['DOCUMENT_ROOT'] . '/inc/header.inc.php';
$_SESSION['return_to'] = $_SERVER['REQUEST_URI'];
$tfa_data = get_tfa();
$fido2_data = fido2(array("action" => "get_friendly_names"));
$js_minifier->add('/web/js/site/admin.js');
$js_minifier->add('/web/js/presets/rspamd.js');
$js_minifier->add('/web/js/site/pwgen.js');
// all domains
$domains = mailbox('get', 'domains');
$all_domains = array_merge($domains, mailbox('get', 'alias_domains'));
// mailboxes
$mailboxes = [];
foreach ($all_domains as $domain) {
foreach (mailbox('get', 'mailboxes', $domain) as $mailbox) {
$mailboxes[] = $mailbox;
}
}
$mailboxes = array_filter($mailboxes);
// DKIM domains
$dkim_domains = [];
$dkim_domains_with_keys = [];
foreach($domains as $domain) {
$dkim_domains[$domain] = ['dkim' => null, 'alias_domains' => []];
if (!empty($dkim = dkim('details', $domain))) {
$dkim_domains_with_keys[] = $domain;
if ($GLOBALS['SHOW_DKIM_PRIV_KEYS'] !== true) {
$dkim['privkey'] = base64_encode('Please set $SHOW_DKIM_PRIV_KEYS to true to show DKIM private keys.');
}
$dkim_domains[$domain]['dkim'] = $dkim;
}
// get alias domains
foreach (mailbox('get', 'alias_domains', $domain) as $alias_domain) {
$dkim_domains[$domain]['alias_domains'][$alias_domain] = ['dkim' => null];
if (!empty($dkim = dkim('details', $alias_domain))) {
$dkim_domains_with_keys[] = $alias_domain;
if ($GLOBALS['SHOW_DKIM_PRIV_KEYS'] !== true) {
$dkim['privkey'] = base64_encode('Please set $SHOW_DKIM_PRIV_KEYS to true to show DKIM private keys.');
}
$dkim_domains[$domain]['alias_domains'][$alias_domain]['dkim'] = $dkim;
}
}
}
$dkim_blind_domains = [];
foreach(dkim('blind') as $blind) {
$dkim_blind_domains[$blind] = ['dkim' => null];
if (!empty($dkim = dkim('details', $blind))) {
$dkim_domains_with_keys[] = $blind;
if ($GLOBALS['SHOW_DKIM_PRIV_KEYS'] !== true) {
$dkim['privkey'] = base64_encode('Please set $SHOW_DKIM_PRIV_KEYS to true to show DKIM private keys.');
}
$dkim_blind_domains[$blind]['dkim'] = $dkim;
}
}
// rsettings
$rsettings = array_map(function ($rsetting){
$rsetting['details'] = rsettings('details', $rsetting['id']);
return $rsetting;
}, rsettings('get'));
// rspamd regex maps
$rspamd_regex_maps = [];
foreach ($RSPAMD_MAPS['regex'] as $rspamd_regex_desc => $rspamd_regex_map) {
$rspamd_regex_maps[$rspamd_regex_desc] = [
'map' => $rspamd_regex_map,
'data' => file_get_contents('/rspamd_custom_maps/' . $rspamd_regex_map)
];
}
// cors settings
$cors_settings = cors('get');
$cors_settings['allowed_origins'] = str_replace(", ", "\n", $cors_settings['allowed_origins']);
$cors_settings['allowed_methods'] = explode(", ", $cors_settings['allowed_methods']);
$f2b_data = fail2ban('get');
// mbox templates
$mbox_templates = mailbox('get', 'mailbox_templates');
// SCIM
require_once $_SERVER['DOCUMENT_ROOT'] . '/inc/functions.scim.inc.php';
$scim_tokens = scim_token('get_all');
$scim_new_token = $_SESSION['scim_new_token'] ?? null;
$scim_base_url = 'https://' . getenv('MAILCOW_HOSTNAME') . '/scim/v2/';
unset($_SESSION['scim_new_token']);
$template = 'admin.twig';
$template_data = [
'tfa_data' => $tfa_data,
'tfa_id' => @$_SESSION['tfa_id'],
'fido2_cid' => @$_SESSION['fido2_cid'],
'fido2_data' => $fido2_data,
'api' => [
'ro' => admin_api('ro', 'get'),
'rw' => admin_api('rw', 'get'),
],
'dkim_domains' => $dkim_domains,
'dkim_domains_with_keys' => $dkim_domains_with_keys,
'dkim_blind_domains' => $dkim_blind_domains,
'domains' => $domains,
'all_domains' => $all_domains,
'mailboxes' => $mailboxes,
'f2b_data' => $f2b_data,
'f2b_banlist_url' => getBaseUrl() . "/f2b-banlist?id=" . $f2b_data['banlist_id'],
'q_data' => quarantine('settings'),
'qn_data' => quota_notification('get'),
'pw_reset_data' => reset_password('get_notification'),
'rsettings_map' => file_get_contents('http://nginx:8081/settings.php'),
'rsettings' => $rsettings,
'rspamd_regex_maps' => $rspamd_regex_maps,
'logo_specs' => customize('get', 'main_logo_specs'),
'logo_dark_specs' => customize('get', 'main_logo_dark_specs'),
'ip_check' => customize('get', 'ip_check'),
'custom_login' => customize('get', 'custom_login'),
'password_complexity' => password_complexity('get'),
'show_rspamd_global_filters' => @$_SESSION['show_rspamd_global_filters'],
'cors_settings' => $cors_settings,
'is_https' => isset($_SERVER['HTTPS']) && $_SERVER['HTTPS'] === 'on',
'iam_settings' => $iam_settings,
'mbox_templates' => $mbox_templates,
'scim_tokens' => $scim_tokens,
'scim_new_token' => $scim_new_token,
'scim_base_url' => $scim_base_url,
'lang_admin' => json_encode($lang['admin']),
'lang_datatables' => json_encode($lang['datatables'])
];
require_once $_SERVER['DOCUMENT_ROOT'] . '/inc/footer.inc.php';