SCIM provisioning from Entra ID and Okta, and single sign-on for the organisation

Progressiverobot

An organisation that keeps its people in an identity provider wants two things of its mail server: mailboxes that follow the directory, and a sign-in that goes through it. Since 6.3.4 hMailServer has both. SCIM 2.0 at /scim/v2 lets Microsoft Entra ID or Okta make, rename, suspend and remove accounts, with their aliases and distribution lists. Single sign-on, by OpenID Connect or SAML 2.0, opens the webmail at /portal and the Control Deck at /. The one thing to know first: they answer different questions and take different credentials. SCIM answers to an API key whose role holds provision and to nothing else. Single sign-on opens the two pages only: IMAP, POP3 and SMTP still take the account's password and its application passwords.

Passkeys and account recovery are covered in the topic on signing in.

How the pieces fit

Piece	Direction	What it does
LDAP directory authentication	This server asks the directory	Checks a password when somebody signs in
SCIM provisioning	The identity provider calls this server	Says what changed, as it changes
Single sign-on	The browser goes to the identity provider and back	Signs a person in to the webmail or the Control Deck
`oidc_auto_provision`, `saml_auto_provision`	In passing, at sign-in	Makes a mailbox for whoever arrives with a verified address, and never touches it again

SCIM is the deliberate version of auto-provisioning. The two work together: SCIM keeps the mailboxes, and single sign-on is how the people it made sign in to them.

Where the settings are. The single sign-on settings are the REST API's and the Control Deck's. There is no COM property and no Control Panel page for them, on Windows or on Linux.

SCIM: the key and the permission

A SCIM request is a request of the REST listener. RestApiPort has to be on and the listener reachable from the identity provider's service over TLS, with a certificate it trusts (RestApiCertificateFile, or the ACME certificate). A body is at most 64 KB, and the key's requests count against the listener's budget of 200 in ten seconds per credential, beyond which the answer is 429 with Retry-After.

The key's role must hold provision. The built-in serveradmin role holds it, so every key issued with "scope":"full" provisions; no other built-in role does, so a read-only key is answered 403. The way to issue a key that provisions and does nothing else is a custom role:

curl -u Administrator:your-admin-password -H "Content-Type: application/json" \
     -d '{"name":"entra-provisioning","description":"Microsoft Entra ID","permissions":"provision"}' \
     https://mail.example.com:8443/api/v1/roles

curl -u Administrator:your-admin-password -H "Content-Type: application/json" \
     -d '{"label":"Entra provisioning","role":"entra-provisioning"}' \
     https://mail.example.com:8443/api/v1/apikeys

The second request, POST /api/v1/apikeys, answers the hmapi_... token once, and that token is the identity provider's secret. provision is needed for SCIM's reads as well as its writes.

Both requests present the administrator password, which works while no second factor is enrolled on it. With one enrolled, sign in once at POST /api/v1/session with the code in X-hMailServer-OTP, and send both requests with the hmailsession cookie and X-Requested-With: hMailServer: since 6.3.4 a one-time code is taken once, so a second request carrying the same code within the same half minute is refused with 401.

Every other credential is refused. The administrator password, an account's password and a browser session are answered 401 on /scim/, in SCIM's shape, with WWW-Authenticate: Bearer.

A key confined to named domains ("domains":"example.com") provisions those domains and learns nothing about the rest: listings are filtered, an account elsewhere is the same 404 as one that is not there, and an address elsewhere is refused 400 invalidValue.

A key may not change or remove an account whose authority it does not take in, and is answered 403. A key whose role holds provision alone takes in no administrator at all: not a domain administrator, not a help desk, not an auditor. A full key confined to named domains takes in an administrator of those domains and nobody else. A full key issued for every domain takes in every account.

SCIM: the routes and the mapping

Route	What it does
`GET /scim/v2/ServiceProviderConfig`	What this server supports: patch, filter (200 at most), changePassword and etag; not bulk and not sort
`GET /scim/v2/Schemas`, `GET /scim/v2/ResourceTypes`	The User and Group schemas, listing only what this server keeps; the two resource types
`GET`, `POST /scim/v2/Users`	The accounts: listed and filtered, or one made
`GET`, `PUT`, `PATCH`, `DELETE /scim/v2/Users/{id}`	One account: read, replaced, changed, removed
`GET`, `POST /scim/v2/Groups`	The distribution lists: listed and filtered, or one made
`GET`, `PUT`, `PATCH`, `DELETE /scim/v2/Groups/{id}`	One list: read, replaced, changed, removed

Every answer under /scim/ is application/scim+json, the refusals included.

A User is an account.

SCIM	This server
`id`, `userName`	The account's address. The id is the address, so a rename changes the id.
`name.givenName`, `name.familyName`	The first and last names, sixty characters each
`displayName`	The two names composed. Written alone to an account that already has a name, it is accepted and not kept.
`active`	The account's switch. `false` suspends it and deletes nothing.
`emails`	The address, `type` `work` and `primary`, and every alias whose value is the address, `type` `other`
`password`	Write-only. Judged by the password policy, the reuse history and, when it is on, the breach check.
`externalId`	The identity provider's own id for the person, at most 255 characters (schema 6096)

meta.created and meta.lastModified are not answered, because the tables keep no such times. A Group is a distribution list: id and displayName are the list's address, and members are its members. The sharing groups at /api/v1/groups are folder-permission principals and are not SCIM groups.

Attributes the schemas have and this server does not keep, such as title, phoneNumbers and the enterprise extension's department and manager, are accepted and not kept. A misspelt attribute or path is refused by name.

SCIM: what each operation does

Making a user. POST /scim/v2/Users needs a userName at a domain this server hosts and the key reaches. A body with no password, which is what Entra sends, makes the account with thirty-two random bytes for one, which nobody is ever told. An address something already has is 409 uniqueness.

Filters. These and no others: userName eq, userName co, userName sw, externalId eq, emails.value eq and active eq. Any other filter is 400 invalidFilter. count is at most 200, and sortBy and sortOrder are ignored. Groups filter on displayName eq only.

Changing. PUT takes the body a POST takes, and an attribute it leaves out is left as it is. PATCH takes a PatchOp, with op in any case, as Entra capitalises it. If-Match is honoured on PUT, PATCH and DELETE; a version other than the current one is 412. A change is judged whole before anything is written.

Suspending. active false refuses every sign-in from the next attempt, refuses mail to the account, ends its browser sessions and drops its live IMAP, POP3 and SMTP connections. The mailbox, the aliases and the lists are untouched.

Renaming. A new userName renames the account through the mailbox move. It is refused 409 while the mailbox is in use. The id changes, the old id is 404 from then on, and the old address is kept as an alias until a later request that sends emails leaves it out.

Every alias of the account is part of emails, including one an administrator made. An identity provider that replaces emails removes the aliases it does not list. Where aliases are managed on this server and not in the directory, do not map emails beyond the work address.

Removing. DELETE /scim/v2/Users/{id} removes the account and its mailbox, every alias emails answered for it, and its row in every distribution list. It answers 204. Nothing of it can be put back but from a backup. Entra sends active false straight away and the DELETE thirty days after a user is soft-deleted, so the suspension is the safe first step.

Five diagnostics in the error log, HM7220 to HM7224, name what a SCIM write left behind when it failed part way. Every SCIM write is on the audit trail, each row naming key:<id>.

Setting up Microsoft Entra ID for SCIM

Issue the key as above and note the token.
In the Entra admin centre, Enterprise applications > New application > Create your own application > Integrate any other application you don't find in the gallery (Non-gallery).
Provisioning > Automatic. Tenant URL: https://<host>:<port>/scim/v2, where the port is RestApiPort. Secret token: the hmapi_... token. Test connection asks for a user that does not exist and expects an empty list, which is what this server answers.
Mappings > Provision Microsoft Entra ID Users: map userName from userPrincipalName where that is the mailbox address, or from mail where it is not. emails[type eq "work"].value must be the same address as userName. Keep active, name.givenName, name.familyName, displayName and externalId, and delete the mappings this server does not keep.
Mappings > Provision Microsoft Entra ID Groups, for mail-enabled groups that should be distribution lists: map displayName from mail, keep members, and delete the mapping of externalId.
Assign the users and groups, and switch Provisioning Status on.

Setting up Okta for SCIM

Issue the key as above.
Applications > Create App Integration > SAML 2.0 or SWA, then on General enable SCIM provisioning.
Provisioning > Integration: SCIM connector base URL https://<host>:<port>/scim/v2; Unique identifier field for users userName; Supported provisioning actions: Import New Users and Profile Updates, Push New Users, Push Profile Updates, Push Groups; Authentication Mode HTTP Header, and the token in Authorization.
Provisioning > To App: enable Create Users, Update User Attributes and Deactivate Users.
Push Groups sends a group under its Okta name as displayName, and here that is the list's address, so a push of Engineering is 400 invalidValue. Name each pushed group with the list's address, or leave Push Groups off.

Okta sends emails with the primary address alone, so an alias made on this server is removed by Okta's next update. Scim.md gives no steps for Google Workspace: at the time it was written, a custom application there could not be pointed at a SCIM endpoint.

Single sign-on with OpenID Connect

Register this server at the issuer as an authorization-code client with PKCE, with the redirect URI <oidc_redirect_base_url>/portal/oidc/callback.

Setting	What it is
`oidc_issuer`	For example `https://login.example.com`. The discovery document is read from `<issuer>/.well-known/openid-configuration` and cached for an hour. Empty offers no single sign-on at all.
`oidc_client_id`	The client id this server is registered under
`oidc_client_secret`	Its secret, stored protected and never emitted. Empty for a public client.
`oidc_scopes`	`openid email` by default
`oidc_redirect_base_url`	The address the webmail is reached at from outside. Empty falls back to `import_oauth_redirect_base_url`.
`oidc_auto_provision`	Whether a verified address with no mailbox here gets one. Off.
`oidc_administrators`	The addresses that open the Control Deck as the administrator. Empty means single sign-on reaches the webmail only.

The flow is GET /portal/oidc/start[?deck=1] to the issuer and GET /portal/oidc/callback back. The callback verifies the id_token: its signature against the issuer's published keys (RS256 and ES256 only), iss, aud, exp, iat and nbf with a minute of skew, and the nonce. It then takes email, and only when email_verified says the issuer verified it.

With oidc_issuer set, both sign-in pages draw a Sign in with button naming the issuer's host. What they draw is decided by GET /api/v1/signin-methods, which needs no credential and says nothing about who exists here. With SAML set up it answers saml: true and saml_label, and both pages draw a second button.

The callback does not make the session. It mints a one-use ticket, good for two minutes, and the page hands it to POST /api/v1/session, which is where every browser session is made. The ticket is bound to the browser by an hmsso cookie, and POST /api/v1/session refuses a ticket that arrives without it.

Mapping. The verified address is looked up as a mailbox. With auto-provisioning off, the default, a sign-in with no mailbox is refused. With it on, a mailbox is made, but only at a domain this server already has, and with a random password nobody is told. For the Control Deck, the address must be in oidc_administrators. An issuer that says somebody is an administrator is not obeyed.

Single sign-on with SAML 2.0

For identity providers that speak only SAML 2.0: ADFS above all, and an Entra ID or Okta application set up the SAML way. It ends in the same ticket, the same POST /api/v1/session and the same mapping rules.

Setting	What it is
`saml_idp_entity_id`	The identity provider's entity ID. Empty, the default, offers no SAML sign-in at all.
`saml_idp_sso_url`	Its sign-in URL for the HTTP-Redirect binding
`saml_idp_certificate`	Its signing certificate in PEM, or two while it rolls its key over. Write-only.
`saml_sp_entity_id`	This server's entity ID. Empty means `<base URL>/saml`.
`saml_email_attribute`	The attribute the address is read from when the NameID is not an email address
`saml_require_signed_assertion`	Whether the Assertion must carry its own signature. On by default.
`saml_auto_provision`, `saml_administrators`	As the OpenID Connect settings of the same names
`saml_button_label`	The words on the button: Sign in with SAML by default

The base URL is OpenID Connect's: oidc_redirect_base_url, falling back to import_oauth_redirect_base_url. From it follow the entity ID <base URL>/saml, the ACS URL <base URL>/portal/saml/acs and the metadata at <base URL>/saml/metadata.

Identity provider	What to enter there	What to copy back
Microsoft Entra ID	Identifier (Entity ID) `<base URL>/saml`; Reply URL `<base URL>/portal/saml/acs`; token encryption off	Login URL to `saml_idp_sso_url`; Microsoft Entra Identifier to `saml_idp_entity_id`; Certificate (Base64) to `saml_idp_certificate`
Okta	Single sign-on URL `<base URL>/portal/saml/acs`; Audience URI (SP Entity ID) `<base URL>/saml`; Name ID format EmailAddress; Assertion Encryption Unencrypted	Identity Provider Single Sign-On URL to `saml_idp_sso_url`; Identity Provider Issuer to `saml_idp_entity_id`; X.509 Certificate to `saml_idp_certificate`
ADFS	A claims-aware relying party trust, imported from `<base URL>/saml/metadata` or entered by hand; E-Mail-Addresses sent as E-Mail Address	`https://<adfs host>/adfs/ls/` as `saml_idp_sso_url`; the Federation Service Identifier as `saml_idp_entity_id`; the Token-signing certificate as `saml_idp_certificate`

The flow.

GET  /portal/saml/start[?deck=1]   to the identity provider, with an AuthnRequest,
                                   and the hmsaml cookie
POST /portal/saml/acs              back from it, with the Response
GET  /portal/saml/finish           on from the ACS, where the cookie is asked for
GET  /saml/metadata                this service provider, for the identity provider

The ACS takes a form of at most 256 KB; a larger body is answered 413. The signature is verified against the certificates an administrator stored and never a key the message carries. The signature method must be rsa-sha256 or ecdsa-sha256, and SHA-1 is refused. A Response is taken only when it answers a request this server issued, not yet answered, with the same RelayState. The checks refuse signature wrapping, a replayed Response or assertion, a Response nobody asked for and an encrypted assertion; comment injection in the NameID gains nothing, because the address read is the whole of what was signed.

A saml_idp_certificate that cannot be read stops every SAML sign-in. The settings refuse one, so it comes only from a database edited by hand; HM7320 in the error log then names the setting to paste again.

A SAML identity provider says nothing like email_verified. The attribute the address is read from must be one the directory controls, such as mail or the user principal name, and never one a person can set themselves. This server cannot check that.

What it does not do

SCIM: no bulk, no sorting and no POST .search (/Bulk, /Me and POST .search answer 501); no enterprise user extension; no groups but distribution lists; not a SCIM client. externalId is shown by nothing but SCIM and COM's Account.ExternalId, which is Windows-only.
Single sign-on, both kinds: no logout in either direction, so an account disabled at the identity provider keeps a session it already started until that session's own ceiling ends it. One OpenID Connect issuer and one SAML identity provider. Nothing is enforced at IMAP, POP3 and SMTP.
OpenID Connect: no claims mapping. The email claim and nothing else.
SAML: no encrypted assertions, no signed requests, no metadata fetch, no artifact binding and no sign-in started by the identity provider.

Where to read more

The operator documents: Scim.md, PasskeysAndSingleSignOn.md and Roles.md.
The wiki: The REST API and APIs Reference.
The public documentation: chapter 24, The REST API and chapter 36, The Control Deck and the webmail portal.
On this forum: passkeys, recovery and the rest of sign-in are in Signing in: passwords, second factor, passkeys, single sign-on; LDAP sign-in and directory synchronisation are in Active Directory and LDAP sign-in; The Control Deck; the 6.3.4 announcement; and the REST API guide.