Add user's email addres to the stepup callout

[pmeulen]

Add the user's email address to the stepup callout so that the Stepup-gateway can use it as an identifier in a fallback authentication method (to EntraID through Sepup-AzureMFA).

Make the name of the SAML attribute(s) in engine to add to the callout to stepup configurable in engine's parameters.yaml:

## SFO SETTINGS
stepup.callout_user_attributes: 
  - urn:mace:dir:attribute-def:mail

When the user has the a SAML attribute configured under callout_user_attributes, engine must add the SAML attribute as an extension to the stepup callout SAML AuthnRequest.

• It is not an error if the user does not have one or more of the attributes configured under callout_user_attributes.
• Attributes that the user does not have are not added to the extension
• If no attributes are configured under stepup.callout_user_attributes, or if this configuration does not exist, the extension must not be added.

We reuse the urn:mace:surf.nl:stepup:gssp-extensions SAML extension that is currently used between the Stepup-Gateway and the Stepup-AzureMFA GSSP during GSSP registration.

Example AuthnRequest of a stepup callout from engine to the gateway that uses the urn:mace:surf.nl:stepup:gssp-extensions UserAttributes extension to send the urn:mace:dir:attribute-def:mail attribute with value of j.doe@institution-a.example.org :

<samlp:AuthnRequest xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
                    xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
                    ID="_09010524d6c616787a5b8364aa20a3bfcfa4a38062ee88c8893720717e83"
                    Version="2.0"
                    IssueInstant="2025-04-28T08:56:10Z"
                    Destination="https://gateway.stepup.example.org/second-factor-only/single-sign-on"
                    AssertionConsumerServiceURL="https://engine.openconext.example.org/authentication/stepup/consume-assertion"
                    ProtocolBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST">
    <saml:Issuer>https://engine.openconext.example.org/authentication/stepup/metadata</saml:Issuer>
    <samlp:Extensions>
        <gssp:UserAttributes xmlns:gssp="urn:mace:surf.nl:stepup:gssp-extensions"
                             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                             xmlns:xs="http://www.w3.org/2001/XMLSchema">
            <saml:Attribute xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
                            NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"
                            Name="urn:mace:dir:attribute-def:mail">
                <saml:AttributeValue xsi:type="xs:string">j.doe@institution-a.example.org</saml:AttributeValue>
            </saml:Attribute>
        </gssp:UserAttributes>
    </samlp:Extensions>
    <saml:Subject>
        <saml:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">urn:collab:person:institution-a.example.org:u12345678</saml:NameID>
    </saml:Subject>
    <samlp:NameIDPolicy AllowCreate="true" />
    <samlp:RequestedAuthnContext Comparison="minimum">
        <saml:AuthnContextClassRef>http://stepup.example.org/assurance/sfo-level1.5</saml:AuthnContextClassRef>
    </samlp:RequestedAuthnContext>
    <samlp:Scoping ProxyCount="10">
        <samlp:RequesterID>https://institution-a.example.org/idp/metadata</samlp:RequesterID>
    </samlp:Scoping>
</samlp:AuthnRequest>

Note:

• The urn:mace:dir:attribute-def:mail SAML Attribute XML element was copied as it would appear in the SAML Response was copied in its entirety as a child of the gssp:UserAttributes XML element. The location of the extenstion is important to create valid XML, it must be between the Issuer and Subject.
• In the future we likely want to add another extension with the name of the service that the user is authenticating to.

TODO:

• Discuss: are we happy with reusing the urn:mace:surf.nl:stepup:gssp-extensions ? Do we want to create a new one for this? I've added an XSD of the extension to allow the XML to be validated: https://github.com/pmeulen/xml-tools/blob/master/schemas/surf-stepup-gssp-extensions-1.0.xsd

[pmeulen]

If you have time for some boyscouting you can pickup: #1827

[pablothedude]

@pmeulen do you mind if I add a feature toggle feature_stepup_send_user_attributes to make it easier to test and easier to have some initial dev config?

[pmeulen]

Adding an explicit feature toggle is fine. My idea was to use the presence of the callout_user_attributes key for this. But an explict toggle like feature_stepup_send_user_attributes might be clearer.

[baszoetekouw]

@pablothedude
@mrvanes has recently refactored the callout mechanism in #1819 after you reviewed his PR
It moght be useful to merge that first (if you approve of the current changes) in order to avoid messy rebases lateron