Sending user attributes during GSSP enrollment

Introduction

In this RFC we propose an enhancement of the GSSP protocol. The current GSSP protocool is described at https://github.com/OpenConext/Stepup-Gateway/blob/develop/docs/GSSP.md

We want to send additional information to a GSSP during enrollment. For the Azure-MFA GSSP knowning the email adress of the user, which is already known in Stepup, greatly enhances usability. For the Tiqr GSSP having the SP displayname available allows us to put the in the Push message to the user's smartphone.

SAML Extensions

During enrollment the Stepup-Gateway sends a SAML 2.0 AuthnRequest to the GSSP using the HTTP-Redirect binding. We propose to use the SAML Extensions element to send the additional information. See: SAML-CORE-2.0, page 39, line 1562. This ensures the information is integrity protected because the AuthnRequest is signed by the Stepup-Gateway.

According to the SAML specification the "SAML extension elements MUST be namespace-qualified in a non-SAML-defined namespace". Because we could not find a suitable schema to reuse for sending the email address, we define a new element with a new namespace for in the extensions. SURF has a URN registry at https://wiki.surfnet.nl/pages/viewpage.action?pageId=11207352. We propose to use "urn:mace:surf.nl:stepup:gssp-extensions" as a namespace for the extensions.

UserAttributes

We propose to add a new UserAttributes element. When present in the Extensions element, this element contains a list of one or more saml:Attribute elements for the GSSP. This allows the Stepup-Gateway to put selected SAML Attributes in the AuthnRequest.

Update 21-12-2020: Fix a typo in the extention's namespace identifier in the schema.

Although an XML Schema is not required for the urn:mace:surf.nl:stepup:gssp-extensions schema, it is useful to have one for documentation purposes:

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
    targetNamespace="urn:mace:surf.nl:stepup:gssp-extensions"
    xmlns:gssp="urn:mace:surf.nl:stepup:gssp-extensions"
    xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" 
    elementFormDefault="unqualified"
    attributeFormDefault="unqualified" 
    version="1.0">
    <xs:import namespace="urn:oasis:names:tc:SAML:2.0:assertion"
        schemaLocation="saml-schema-assertion-2.0.xsd"/>
    <xs:annotation>
        <xs:documentation>
            SAML Extension for use in the GSSP protocol: https://github.com/OpenConext/Stepup-Gateway/blob/develop/docs/GSSP.md
            Version 1.0:
            - Define UserAttributes element for use in AuthnRequest during GSSP enrollemnt 
        </xs:documentation>
    </xs:annotation>
    <xs:element name="UserAttributes" type="gssp:UserAttributesType"/>
    <xs:complexType name="UserAttributesType">
        <xs:sequence>
            <xs:element ref="saml:Attribute" minOccurs="1" maxOccurs="unbounded"/>
        </xs:sequence>
    </xs:complexType>
</xs:schema>

We should host this schema at a suitable location. We propose to use the Stepup-Gateway GitHub repo for this purpose.

Example AuthnRequest

Example of a GSSP enrollement AuthnRequest that sends the email address of user@example.com to the GSSP:

<?xml version="1.0" encoding="UTF-8"?>
<samlp:AuthnRequest xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
    xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
    ID="_92dbb2d48fa7962f3523ea301e85ec5dc52b2d09d9affc84e9b8163c843f" Version="2.0"
    IssueInstant="2017-04-18T07:46:45Z" Destination="https://tiqr.tld/saml/sso"
    AssertionConsumerServiceURL="https://gateway.tld/gssp/tiqr/consume-assertion"
    ProtocolBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST">
    <saml:Issuer>https://gateway.example.com/gssp/tiqr/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 Name="urn:mace:dir:attribute-def:mail"
                NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
                <saml:AttributeValue xsi:type="xs:string">user@example.com</saml:AttributeValue>
            </saml:Attribute>
        </gssp:UserAttributes>
    </samlp:Extensions>
    <samlp:Scoping ProxyCount="10">
        <samlp:RequesterID>https://selfservice.stepup.example.com/registration/gssf/tiqr/metadata</samlp:RequesterID>
    </samlp:Scoping>
</samlp:AuthnRequest>

Future extensions

When other information needs to be sent from the Stepup-Gateway to a GSSP (or the other way around) the urn:mace:surf.nl:stepup:gssp-extensions:gssp-extensions schema can be extended. For sending SP related information de mdui extension seems suitable.