What changed

Every content update is versioned. Select a version to compare it with the one before.

Version 12 → 13

Update

New module on operating SSO in production: audiences, per-application signing certificates, token lifetimes and profile claims, session lifetime, sign-out and revocation, Kerberos sign-in, agreements and the application catalog. The federation lesson now covers routing conflicts.

4 lessons updated

Content update. Enrolled learners were notified.

SAML 2.0 applications

In outbound SAML, **Monosign is the identity provider (IdP)** and the application is the **service provider (SP)**. The configuration lives on an application key of type `SAML`: Applications → application → `Keys` → key card `Configure` → tab `SAML Settings`. The key card also gives you the sign-on URL, metadata and certificate to hand to the SP. ::diagram saml-sp-initiated Key settings: - **`Metadata Import`**: paste XML or a URL, review `Preview changes` and `Apply to Configuration`. It fills the entity ID, ACS endpoints, NameID format, logout URL and SP certificates. It needs a saved key, and Monosign does not re-check application metadata in the background. - **ACS URLs**: `Additional Assertion Consumer Urls` is the list of allowed endpoints. `ACS Validation Mode` is `Off (Legacy)`, `Warn Only` or `Enforce`. A key created in the console starts at `Enforce`, but a key saved before v2026.07 behaves as `Warn Only` and will post to any requested URL. Only `Enforce` refuses. Matching is exact, so a trailing slash makes a different URL. - **`Name Id` and `NameId Format`**: `Name Id` says which value is sent (default `UserName`, or a profile property or token). `NameId Format` is the format label the SP expects. If the value is empty for a user, sign-in stops with a `DATA_MISSING` audit. - **Bindings**: SP-initiated sign-in over HTTP-POST and HTTP-Redirect, and IdP-initiated sign-in, which uses the default ACS. Avoid HTTP-Artifact behind a load balancer: artifact resolution is held per node and fails with `Unknown artifact` on another one. - **`Signing Algorithm`**: `System Default (SHA 256)` or SHA-1. Use SHA-1 only if the SP cannot do better. - **`Signing Certificates`**: `Organization-Based` (shared, set under System → `Configurations`) or `Application-Based`. ::shot sso-saml-settings ### Limits to tell the customer - Monosign **does not encrypt** assertions or responses. `Don't Encrypt Entire Message` and `Don't Encrypt Assertion` are misleading labels: they remove a **signature**, so leave them off unless the SP demands it. - Logging out of one application does not send a SAML `LogoutRequest` to the user's other applications. > Tip: Choose a `Name Id` value that does not change for the life of the user. Email addresses change, and the format label alone does not protect you.

Claim mapping and inbound identity providers

### Claim mapping Each application should receive only the attributes it needs. The tabs are on the application key: - SAML: `Attribute Mapping`, `Group Mapping`, `Role Mapping`, `Permission Mapping`. - OIDC: `Claim Mapping`, `Profile Claim`, and group, role, permission and resource mapping tabs. The group, role and permission tabs are off by default. Each has an attribute name (default `Groups`), a filter and a format (default `{{Name}}`). Use the filter so an application gets its own groups, not the full membership list. On OIDC, a `Claim Mapping` row named after a claim Monosign issues itself, such as `email` or `sub`, **replaces** that claim. ::diagram sso-claim-mapping ::shot sso-providers-list ### Inbound federation Under Identity → `Providers`, Monosign can also *trust* external IdPs. `Add New` offers templates for providers such as Microsoft Entra ID, Okta, Google, Apple and GitHub, or a blank `SAML 2.0`, `OpenID Connect` or `WS-Federation` provider. - **Routing**: `Matches any user`, `Matches regex` or `Matches email domain` sends a user to the provider. Do not use `Matches user attribute`: it never routes. A direct visit to the sign-in page, with no login request behind it, is not routed either. When two active providers match the same domain, the list shows `Routing Conflicts Detected` and only the first match is used: give each domain one provider, and confirm the result under `Routing Overview` with `Test Routing`. - **`Access rules`**: evaluated before any account lookup. The first match wins, and the default is `Allow`. - **`Account link policy`**: `Auto (match by email)` is the default. `Manual (link only by source key)` rejects email matches and so prevents takeover through an email claim, but accounts must be linked beforehand. - **Just-in-time provisioning**: off by default. `Enable Just-in-Time provisioning` creates the user on first sign-in with mapped fields and `Default groups`. - **Profile refresh**: groups from the IdP are added on each login but never removed, so do not rely on it to revoke access. - **Certificate rotation**: `Secondary certificate (rotation)` holds a second trusted certificate. With `Keep in sync from this metadata URL`, Monosign refreshes metadata hourly and places a second published certificate there. WS-Federation metadata is not refreshed automatically. ::diagram sso-inbound-federation > Known limitation, last verified on v2026.09: the inbound form shows `Require PKCE`, `Max clock skew (seconds)`, `Response verification`, `Sign authentication requests` and `Use persistent NameID format`, but these settings have no effect. Do not promise them to a customer.

Troubleshooting federation

Most federation failures fall into a few patterns. Work through them in order. ::diagram sso-federation-checks ### Outbound SAML and OIDC 1. **Did the user reach Monosign?** Reports → `Audit` and the application's `Audits` tab show sign-in events. The OIDC endpoints do not write audit rows of their own, so for an OIDC client also read the Account logs. 2. **ACS mismatch**: the log says `SAML ACS validation failed`. Compare `RequestedUrl` with the registered `Location` character by character, including trailing slashes. 3. **Assertion goes to an unexpected URL**: the key is at `Warn Only` or `Off (Legacy)`. Look for `SAML ACS validation warning`, then move the key to `Enforce`. 4. **Redirect or scope errors on OIDC**: check `Allowed Redirect URIs` and `Scope`. Also check the URL prefix against the key type. 5. **The user is unknown to the SP**: check `Name Id` and the attribute mapping. `Your Email seems empty…` with a `DATA_MISSING` audit means the property is empty for that user. 6. **The SP rejects the signature**: compare the certificate in `/saml/{idpId}/Metadata` with the SP's copy, and read both `Don't Encrypt` switches. If only one application fails after a rotation, its `Signing Certificates` type is probably `Application-Based`. 7. **Issuer mismatch**: `does not match the configured Entity Id` is a warning only. If you see it, keep looking for the real failure in the same request. `Enable Debug Mode` on a SAML key logs every request and response in full. Use it briefly and turn it off again. ### Inbound providers - **Users are not sent to the IdP**: `Routing Overview` → `Test Routing` with the address. Check for an inactive provider or `Routing Conflicts Detected`. - **`No matching user found for the federated identity`**: the policy is `Manual` with no link, or the email claim is not mapped. `Interactive test` shows the claims and the `Mapped profile preview` without signing anyone in. Anyone with provider edit rights can run it, and it prints raw claims. - **SAML fails after the IdP renewed its certificate**: check the `Certificate` column and the `Signing certificate` row of `Test connection`. - **Nobody was warned about expiry**: Monosign writes `IDENTITY_PROVIDER_CERTIFICATE_EXPIRING`, but an alert reaches people only if you bind a webhook or trigger to it. ::shot sso-provider-attribute-mapping

Audiences, signing certificates and token lifetimes

Once an application signs in, most follow-up questions are about a handful of key settings. All of them are on the application key: Applications → application → `Keys` → `Configure`. ::shot sso-application-keys ### SAML: who the assertion is for Every assertion names its intended recipient. Monosign takes that value from the key's `Audience` field. If the field is empty it uses `Entity Id`, and if that is empty too, the issuer of the incoming request. When a service provider answers with an audience error, the assertion was issued for another recipient: compare `Audience` and `Entity Id` on the key with the entity ID the SP expects. The NameID and the signing certificate play no part in that error. ::diagram sso-saml-audience-source ### SAML: one certificate for everyone, or one per application A key on `Organization-Based` signs with the shared organization certificate. When that certificate is rotated, every application on it moves at the same moment, so all their service providers have to be updated together. For a service provider that must rotate on its own schedule, open the tab `Signing Certificates` and use `Generate New Certificate` (or `Create to Application-Based Signing Certificate`), save the key and hand the SP the new metadata. From then on, a rotation of the organization certificate no longer touches that application, and its own certificate can be renewed separately. Certificates that arrive with an SP's metadata import are stored for reference. Monosign does not sign with them. ### OIDC: the audience belongs to the access token `Audience` and `Resource` on an OIDC key are written to the **access token** only, and again on every refresh. The ID token keeps the `client_id` as its `aud`, as OpenID Connect expects. An API that needs its own audience value should therefore validate access tokens, not ID tokens. ### OIDC: lifetimes, and what a disabled user can still do - The three lifetime fields are in **minutes**. Until v2026.07-hf02, a client using client credentials read them as seconds. A key tuned on such a build, for example `3600` for one hour, issues tokens that live 60 hours after an upgrade to v2026.09 or later. Review these keys during the upgrade and re-enter the value in minutes, here `60`. - A lifetime is applied when a token is issued. Tokens that were already issued keep their expiry. - Disabling a user does not recall an access token. The token stays valid until its `exp`, and the next refresh is refused with *The refresh token is no longer valid.* Keep `Access Token Lifetime` short for APIs where that window matters. ### OIDC: send only the profile data the client needs When `Profile Access Type` allows profile claims, the profile claim carries **every** profile property unless you narrow it. On the tab `Profile Claim`, select only the properties the client reads in `Included Properties`. This keeps personal data out of tokens, and keeps tokens small enough for proxies with header limits. `Included Properties` limits the token only. The userinfo endpoint still returns the full user model, so review which clients call it. > Tip: After any of these changes, decode a token or assertion issued **after** the change. An older one tells you nothing.