SAML Introduction

We support 2 saml integrations. One for logging into a internal site and one for logging into HamiltonCMS.

SAML integration internal site

Needs

IdP Issuer
IdP Endpoint
Maybe external certificate for signing response

Requirements Saml Response

Encrypted Assertion
Signed SamlResponse

Send to IdP

(Maybe) Signing Certificate
SP Issuer
/saml/response endpoint

Field Reference

Field	Type	Required	Description
`asser tion-path`	Text	Yes	Path where IdP posts SAML Response. Usually `/saml/response`
`en able-time-v alidation`	Bool	Yes	Validate assertion timestamps. Set `false` for testing only
`identi ty-provider -endpoint`	Text	Yes	IdP SSO URL. AuthnRequest sent here
`iden tity-provid er-issuer`	Text	Yes	Expected `Issuer` value in SAML Response. Must match exactly
`login-de stination`	Text	Yes	Internal site URL (e.g., `https://i nternal.company.com`). Users redirected here after login
`logout-de stination`	Text	Yes	External site URL (e.g., `https:/ /public.company.com`). Users redirected here after logout
`` external-ce rtificate``	FilePath?	No	Custom IdP certificate path. Default: `confi g/saml-public-key.crt`
`e xtra-link`	Object?	No	Optional link shown on SAML login page (for applicant portals)

Extra Link (optional)

{
  "extra-link": {
    "label": "Applicant Portal",
    "url": "https://www.example.com/kandidaten-portaal"
  }
}

Domain Matching

The login-destination and logout-destination determine internal/external routing:

Request to login-destination domain → treated as internal site
Request to logout-destination domain → treated as external site
/saml/auth uses this to enforce access control

SAML integration CMS

Needs From IdP

IdP Issuer
IdP Endpoint

Requirements Saml Response

Encrypted Assertion
Signed SamlResponse (by our certificate)

Send to IdP

Signing Certificate
SP Issuer
/saml/cms/login endpoint

Configuration possibilities

Field Reference

Field	Type	Required	Default	Description
`` enable-t ime-vali dation``	Bool	Yes		Validate assertion timestamps
`iden tity-pro vider-en dpoint`	Text	Yes		IdP SSO URL for CMS login
`id entity-p rovider- issuer`	Text	Yes		Expected issuer in SAML Response
`` issuer``	Text	Yes		SP issuer (this application’s identifier sent to IdP) (FQDN of external site)
` first-n ame-iden tifier`	Text	No	` …claims/ givenname`	SAML attribute for first name
`last-n ame-iden tifier`	Text	No	`...claim s/surname`	SAML attribute for last name
`u ser-iden tifier`	Text	No	`.. .claims/ema iladdress`	SAML attribute for email (user lookup key)
`r ole-iden tifier`	Text	No	`...cla ims/Group`	SAML attribute containing user roles
` roles`	[Text]	No	Achmea defaults	Allowed role values. User denied if no match

Attribute Identifiers

Default URIs for Azure AD / ADFS:

Attribute	Default URI
First name	`http://schemas.xmlsoap.org/ws /2005/05/identity/claims/givenname`
Last name	`http://schemas.xmlsoap.org/ ws/2005/05/identity/claims/surname`
Email	`http://schemas.xmlsoap.org/ws/20 05/05/identity/claims/emailaddress`
Role/Group	`http: //schemas.xmlsoap.org/claims/Group`

Override these if your IdP uses different attribute names.

Role-Based Access

CMS access requires the user’s role (from role-identifier attribute) to match one of the values in roles array. User is rejected with 403 if no match.

There is no distinction within the SAML integration to specifiy different roles for the CMS. Either it is a match and you can login or not.

Configuration Differences: Site vs CMS

Aspect	Site SAML	CMS SAML
Storage	`loginMethod[]`	`samlCMS`
Certificate	`confi g/saml-private-key.pem`	`config/saml- cms-private-key.pem`
User provisioning	Creates with internal groups	Creates with CMS groups
Role validation	No	Yes (required)
Attribute mapping	Project-specific hardcoded (Saml.Util)	Configurable via settings
Multiple configs	Yes (array)	No (single)
Configurable singing certificate	Yes	No