Table of Contents

Introduction

Second Factor Only (SFO) Authentication is an alternate SAML authentication endpoint that is offered by the SURFconext strong authentication (SA) gateway. The SFO endpoint allows a Service Provider ( SP ) to authenticate only the second factor of a user. This in contrast to a "standard" authentication at the SA gateway where authentication of the first factor, being the normal authentication of the user to the IdP of their home institution through SURFconext, is always performed in addition to (an optional) authentication of the user's second factor.

SFO Authentication was designed to facilitate the integration of SURFconext SA with the internal services of an institution (i.e. the institution offering services to their own users). Typical applications include:

Adding two factor authentication to an institution's application gateway (e.g. Citrix Netscaler or F5 BIG-IP)
Adding two factor authentication to an institution's authentication or authorization gateway (e.g. Microsoft ADFS, Novell/NetIQ)

Both SFO authentication and standard authentication use the 2nd factor of the user that is registered with SURFconext SA. This means that once a user is registered with SURFconext SA both services using standard and SFO authentication can be used.

The table below shows the differences between a SURFconext SA standard authentication and a SURFconext SA SFO Authentication.

With SFO you can add two factor authentication to your institutions application gateway (e.g. Citrix Netscaler or F5 BIG-IP) or to the authentication or authorization gateway (e.g. Microsoft ADFS or Novell/NetIQ). SFO has its own authentication endpoint at SURFconext.

Once a user is registered with a second factor both SFO authentication and SURFconext Strong Authentication can be used.

Differences between 'standard' SURFconext Strong Authentication and SFO authentication

Feature	Standard authentication	SFO authenticaton
Authentication of first factor	Always	Never
Authentication of second factor	Based on policy between IdP and SP
Feature	Standard authentication	SFO authenticaton
Authentication of the user's first factor	Always	Never
Authentication of the user's second factor	Based on policy between the IdP and SP	Always
User registration	Using SURFconext SA Strong Authentication selfservice registration and vetting by an RA
Standard SURFconext features	Attributes, Authorization, persistent identifiers	None

During With SFO Authentication the authentication via SURFconext is bypassed (see image below). This means that SURFconext functionality like attributes (functionality (e.g. attributes from the user's home IdP), persistent user identifiers or the definition of authorization rules and persistent user identifiers) is not available when using SFO authentication. For the self-service .

Note that also with SFO the registration of users and the vetting by RA the SURFconext SA self-service and RA web interfaces are used, with the first factor authentication provided by SURFconext.

Image Removed

Implementation at the SP

Second factor authentication (SFO) requires implementation / configuration at the service provider. The SFO authentication protocol is very similar to the SAML 2.0 protocol used by normal authentication to the SA gateway. The main difference is that the SP must send the identifier of the user to SA gateway in the SAML AuthnRequest. For this the Subject element in the SAML AuthnRequest must be used (see the description of the AuthnRequest element in the https://docs.oasis-open.org/security/saml/v2.0/saml-core-2.0-os.pdf, section 3.4.1, line 2017)

SAML AuthRequest

To start a SFO the SP must send a SAML 2.0 AuthnRequest to the SFO endpoint of the SA Gateway. This request:

must use the urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect binding
must be signed using the http://www.w3.org/2001/04/xmldsig-more#rsa-sha256 algorithm. (Note that the HTTP-Redirect binding does not use XML Signatures)
must include a RequestedAuthnContext with an AuthnContextClassRef with one of the defined levels.
must include the SURFconext identifier of the user in the Subject element of the AuthnRequest. (see the description of the AuthnRequest element in the https://docs.oasis-open.org/security/saml/v2.0/saml-core-2.0-os.pdf, section 3.4.1, line 2017) as a SAML NameID with Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified".

The SFO uses a different SingleSignOn Location and different AuthnConext identifiers as the standard authentication.

Example SAML AuthnRequest for SFO

See below for an example AuthnRequest. The signature is not visible in the XML as it will be encoded in HTTP GET parameters according to the specification of the HTTP-Redirect binding.

will be done by the institutions (IdP's): there is no work to be done for the SP.

Image Added

SAML AuthRequest

To start a SFO the SP must send a SAML 2.0 AuthnRequest to the SFO endpoint of the SURFconext Strong Authentication Gateway. This request must:

use the urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect binding
be signed using the http://www.w3.org/2001/04/xmldsig-more#rsa-sha256 algorithm (XML signatures cannot be used).
include a RequestedAuthnContext with an AuthnContextClassRef with one of the defined levels.
include the SURFconext identifier of the user in the Subject element as a NameID (Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified", see description of AuthnRequest in https://docs.oasis-open.org/security/saml/v2.0/saml-core-2.0-os.pdf, line 2001).

SFO uses different SingleSignOn Location and AuthnConext identifiers as compared with standard authentication.

Code Block

language	xml
title	Example AuthRequest
collapse	true

<samlp:AuthnRequest xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
                    xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
                    ID="_zQIibz9FKixdlgX8/E7bHqE29wfatcgbsPdVn0NN"
                    Version="2.0"
                    IssueInstant="2016-03-10T15:09:21Z"
                    Destination="https://gw.stepup.example.org/gssp/2nd-factor-only/single-sign-on"
                    AssertionConsumerServiceURL="https://

Code Block

language	xml
title	Example AuthnRequest
collapse	true

<samlp:AuthnRequest xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
    xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" ID="_zQIibz9FKixdlgX8E7bHqE29wfatcgbsPdVn0NN"
    Version="2.0" IssueInstant="2016-03-10T15:09:21Z"
    Destination="https://gw.stepup.example.org/gssp/2nd-factor-only/single-sign-on"
    AssertionConsumerServiceURL="https://application-gateway.some-organisation.example.org/consume-assertion"
                    ProtocolBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST">
 
    <saml:Issuer>https://application-gateway.some-organisation.example.org/metadata</saml:Issuer>
    <saml:Subject>
        <saml:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">urn:collab:person:some-organisation.example.org:m1234567890</saml:NameID>
    </saml:Subject>
    <samlp:RequestedAuthnContext>
        <saml:AuthnContextClassRef>http://stepup.example.org/verified-second-factor/level2</saml:AuthnContextClassRef>
    </samlp:RequestedAuthnContext>   
</samlp:AuthnRequest>

The signature is not visible in the XML: it will be encoded in HTTP GET parameters according to the specification of the HTTP-Redirect binding.

Determining the SURFconext identifier of a user

The SURFconext identifier is built from identifiers that the IdP of the users user sends to SURFconext during authentication. It has the following form: urn:collab:person:{{urn:mace:terena.org:attribute-def:schacHomeOrganization}}:{{urn:mace:dir:attribute-def:uid}}
where:

"urn:collab:person:" is a
= fixed prefix.
"{{urn:mace:terena.org:attribute-def:schacHomeOrganization}}" is the = value of the schacHomeOrganisation attribute of the user. This value is the ; same for all users of an institution and will typically be something like "institution.nl". The administrator of the identity provider (IdP) of the institution can tell you how this value is formed for users of the institution."
{{urn:mace:dir:attribute-def:uid}}" is the = value of the uid attribute attribute of the user. The administrator of the identity provider (IdP) of the institution can tell you how this value is formed for users of the institution.

For the value of last two items: ask the administrator of the IdP .

Example: Example SURFconext identifier (59 characters): urn:collab:person:some-organisation.example.org:m1234567890

SAML Response

The result of a successful authentication is a SAML SAML Response. The Response It does not contain an AttributeStatement as would a Response from a standard authentication.

...

an AttributeStatement.

Code Block

language	xml
title	Example Response
collapse	true

<samlp <samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
                xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
                ID="_ECAokbn0lm7lfVT7THQUl+dSbMrpeyAgiTv0+q16"
                Version="2.0"
                IssueInstant="2016-03-10T15:09:25Z"
                Destination="https://application-gateway.some-organisation.example.org/consume-assertion"
                InResponseTo="_zQIibz9FKixdlgX8E7bHqE29wfatcgbsPdVn0NN"
                >
    <saml:Issuer>https://gw.stepup.example.org/second-factory-only/metadata</saml:Issuer>
    <samlp:Status>
        <samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success" />
    </samlp:Status>
    <saml:Assertion xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                    xmlns:xs="http://www.w3.org/2001/XMLSchema"
                    ID="_zQIibz9FKixdlgX8E7bHqE29wfatcgbsPdVn0NN"
                    Version="2.0"
                    IssueInstant="2016-03-10T15:09:25Z"
                    >
        <saml:Issuer>https://gw.stepup.example.org/second-factory-only/metadata</saml:Issuer>
        <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
            <ds:SignedInfo>
                <ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />
                <ds:SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256" />
                <ds:Reference URI="#_1ROuxGVzJi5bbre6W4woNza82aK41HKjp6aKtw9r">
                    <ds:Transforms>
                        <ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature" />
                        <ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />
                    </ds:Transforms>
                    <ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256" />
                    <ds:DigestValue>YR5JFfJc1JZIKm7Ao3kXtDupEfeMrhKpD9T1lF1z0Lg=</ds:DigestValue>
                </ds:Reference>
            </ds:SignedInfo>
            <ds:SignatureValue>...</ds:SignatureValue>
            <ds:KeyInfo>
                <ds:X509Data>
                    <ds:X509Certificate>...</ds:X509Certificate>
                </ds:X509Data>
            </ds:KeyInfo>
        </ds:Signature>
        <saml:Subject>
            <saml:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">urn:collab:person:some-organisation.example.org:m1234567890</saml:NameID>
            <saml:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
                <saml:SubjectConfirmationData NotOnOrAfter="2016-03-10T15:14:25Z"
                                              Recipient="https://application-gateway.some-organisation.example.org/consume-assertion"
                                              InResponseTo="_zQIibz9FKixdlgX8E7bHqE29wfatcgbsPdVn0NN"
                                              />
            </saml:SubjectConfirmation>
        </saml:Subject>
        <saml:Conditions NotBefore="2016-03-10T15:09:25Z"
                         NotOnOrAfter="2016-03-10T15:14:25Z"
                         >
            <saml:AudienceRestriction>
                <saml:Audience>https://application-gateway.some-organisation.example.org/metadata</saml:Audience>
            </saml:AudienceRestriction>
        </saml:Conditions>
        <saml:AuthnStatement AuthnInstant="2016-03-10T15:09:25Z">
            <saml:AuthnContext>
                <saml:AuthnContextClassRef>http://stepup.example.org/verified-second-factor/level2</saml:AuthnContextClassRef>
            </saml:AuthnContext>
        </saml:AuthnStatement>
    </saml:Assertion>
</samlp:Response>

Error handling

When the SA gateway is unable or unwilling to authenticate the user a SAML Response with a non success status is sent. In some failure scenarios a non 20x HTTP status code may be returned.

SAML status codes are used to refer specific failure modes back to the SP:

Status urn:oasis:names:tc:SAML:2.0:status:Responder with subcode urn:oasis:names:tc:SAML:2.0:status:AuthnFailed: The authentication was not successful
Status urn:oasis:names:tc:SAML:2.0:status:Responder with subcode urn:oasis:names:tc:SAML:2.0:status:NoAuthnContext: The user could not be authenticated at the requested level

Example error response:

Code Block

language	xml
title	Example error response
collapse	true

<samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
:SubjectConfirmation>
        </saml:Subject>
        <saml:Conditions NotBefore="2016-03-10T15:09:25Z"
                         xmlns:samlNotOnOrAfter="urn:oasis:names:tc:SAML:2.0:assertion"2016-03-10T15:14:25Z"
                         >
            <saml:AudienceRestriction>
    ID="_ECAokbn0lm7lfVT7THQUl+dSbMrpeyAgiTv0+q16"
            <saml:Audience>https://application-gateway.some-organisation.example.org/metadata</saml:Audience>
           Version="2.0"
 </saml:AudienceRestriction>
        </saml:Conditions>
        <saml:AuthnStatement IssueInstantAuthnInstant="2016-03-10T15:09:25Z">
            <saml:AuthnContext>
      Destination="https          <saml:AuthnContextClassRef>http://application-gateway.some-organisationstepup.example.org/consume-assertion"verified-second-factor/level2</saml:AuthnContextClassRef>
            </saml:AuthnContext>
    InResponseTo="_zQIibz9FKixdlgX8/E7bHqE29wfatcgbsPdVn0NN">
    </saml:AuthnStatement>
            <saml:Issuer>https://gw.stepup.example.org/metadata</saml:Issuer
                >
    <samlp:Status>
        <samlp:StatusCode Value="</saml:Assertion>
</samlp:Response>

Error handling

When a user cannot be authenticated, the SURFconext Strong Authentication gateway sends a SAML Response to the SP with a non success status:

urn:oasis:names:tc:SAML:2.0:status:Responder with subcode urn:oasis:names:tc:SAML:2.0:status:AuthnFailed =
Authentication not successful
urn:oasis:names:tc:SAML:2.0:status:Responder

...

with subcode urn:oasis:names:tc:SAML:2.0:status:

...

NoAuthnContext =
The user could not be authenticated at the requested level

Level: authentication strength

See explanation at "Levels of Assurance".

Implementation

SFO must be implemented at the SP. The authentication protocol is similar to the one used by the Strong Authentication gateway. The main difference is that the SP must send the identifier of the user in the Subject element of the SAML AuthnRequest (see description of AuthnRequest, line 2017).

The SP will be registered at the SURFconext Strong Authentication gateway as either SFO SP or a 'standard' SURFconext Strong Authentication SP: this determines which endpoint he can access. If a SP implementation needs both, he can register an additional EnityID and use it to access the other endpoint.
There is a white-list of SURFconext identities allowing SFO authentication. The SP must indicate in advance the institutions from which he wants to authenticate users with SFO.

Always do a first factor authentication before starting a SFO authentication

Starting an SFO authentication will immediately start an authentication at the SURFconext Strong Authentication gateway: a push notification (tqr) or an SMS will be sent to the user being authenticated. If authentication is started for the wrong user, this will derange the targeted user and in case of SMS, incur a cost to the institution and possibly for the user.

By observing the behavior of the SFO authentication it is possible to determine whether a username exists.

For this reasons we advise to perform a first factor authentication before starting a SFO authentication.

Example

Implementation Considerations

Always do a first factor authentication before starting a SFO authentication

Starting an SFO authentication will immediately start an authentication at the SA gateway. For tiqr this means that a push notification is sent to the phone of the user being authenticated. For SMS authentication this means that an SMS message is sent to the mobile phone of the user being authenticated. When an authentication is started for the wrong user (deliberately or not) this will derange the targeted user and in case of SMS, incur a cost to the institution and possibly for the user.

By observing the behaviour of the SFO authentication it is possible to determine whether a username exists or not.

For the above two reasons we strongly advise implementers to always perform a first factor authentication before starting a SFO authentication. The second factor authentication process was not designed to be used as a single factor authentication mechanism.

Implementation Notes

A service provider must be registered at the SA gateway as either SFO SP or a standard SP. This registration determines which endpoint the SP is allowed to access. Should an SP implementation have the need to use both the SFO and the standard endpoint simultaneously, it can register an additional EnityID and use that to access the other endpoint.
A whitelist is applied to the SURFconext identities for which a SP may initiate a SFO authentication. A SP must indicate in advance to SURFconext support the institutions from which it wants to authenticate users using SFO.

...

Page tree

Versions Compared

Old Version 19

New Version 20

Key

Introduction

Differences between 'standard' SURFconext Strong Authentication and SFO authentication

Implementation at the SP

SAML AuthRequest

Example SAML AuthnRequest for SFO

SAML AuthRequest

Determining the SURFconext identifier of a user

SAML Response

Error handling

Error handling

Level: authentication strength

Implementation

Always do a first factor authentication before starting a SFO authentication

Example

Implementation Considerations

Always do a first factor authentication before starting a SFO authentication

Implementation Notes

An example code for using SFO with SimpleSAMLphp can be found at: https://github.com/SURFnet/Stepup-SFO-demo

Page tree

Page History

Versions Compared

Old Version 19

New Version 20

Key

Introduction

Differences between 'standard' SURFconext Strong Authentication and SFO authentication

Implementation at the SP

SAML AuthRequest

Example SAML AuthnRequest for SFO

SAML AuthRequest

Determining the SURFconext identifier of a user

SAML Response

Error handling

Error handling

Level: authentication strength

Implementation

Always do a first factor authentication before starting a SFO authentication

Example

Implementation Considerations

Always do a first factor authentication before starting a SFO authentication

Implementation Notes

An example code for using SFO with SimpleSAMLphp can be found at: https://github.com/SURFnet/Stepup-SFO-demo