SAML Configuration Reference
=============================

Site SAML
---------

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
^^^^^^^^^^^^^^^

.. list-table::
   :header-rows: 1
   :widths: 25 10 10 55

   * - Field
     - Type
     - Required
     - Description
   * - ``assertion-path``
     - Text
     - Yes
     - Path where IdP posts SAML Response. Usually ``/saml/response``
   * - ``enable-time-validation``
     - Bool
     - Yes
     - Validate assertion timestamps. Set ``false`` for testing only
   * - ``identity-provider-endpoint``
     - Text
     - Yes
     - IdP SSO URL. AuthnRequest sent here
   * - ``identity-provider-issuer``
     - Text
     - Yes
     - Expected ``Issuer`` value in SAML Response. Must match exactly
   * - ``login-destination``
     - Text
     - Yes
     - Internal site URL (e.g., ``https://internal.company.com``). Users redirected here after login
   * - ``logout-destination``
     - Text
     - Yes
     - External site URL (e.g., ``https://public.company.com``). Users redirected here after logout
   * - ``external-certificate``
     - FilePath?
     - No
     - Custom IdP certificate path. Default: ``config/saml-public-key.crt``
   * - ``extra-link``
     - Object?
     - No
     - Optional link shown on SAML login page (for applicant portals)

Extra Link (optional)
^^^^^^^^^^^^^^^^^^^^^

.. code:: json

   {
     "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

CMS SAML
--------

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
^^^^^^^^^^^^^^^

.. list-table::
   :header-rows: 1
   :widths: 20 10 10 15 45

   * - Field
     - Type
     - Required
     - Default
     - Description
   * - ``enable-time-validation``
     - Bool
     - Yes
     - \-
     - Validate assertion timestamps
   * - ``identity-provider-endpoint``
     - Text
     - Yes
     - \-
     - IdP SSO URL for CMS login
   * - ``identity-provider-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-name-identifier``
     - Text
     - No
     - ``...claims/givenname``
     - SAML attribute for first name
   * - ``last-name-identifier``
     - Text
     - No
     - ``...claims/surname``
     - SAML attribute for last name
   * - ``user-identifier``
     - Text
     - No
     - ``...claims/emailaddress``
     - SAML attribute for email (user lookup key)
   * - ``role-identifier``
     - Text
     - No
     - ``...claims/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:

.. list-table::
   :header-rows: 1
   :widths: 30 70

   * - 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/2005/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 redirected to the
login page if no match.

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

--------------

Configuration Differences: Site vs CMS
---------------------------------------

.. list-table::
   :header-rows: 1
   :widths: 20 40 40

   * - Aspect
     - Site SAML
     - CMS SAML
   * - Storage
     - ``loginMethod[]``
     - ``samlCMS``
   * - Certificate
     - ``config/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 signing certificate
     - Yes
     - No