Table of Contents

Introduction

Second Factor Only

...

authentication allows a SP to authenticate only the second factor of a user. SFO is suitable for situations where the application must perform the fist factor authentication of the user like that application gateway (e.g. Citrix Netscaler or F5 BIG-IP) or to the authentication or authorization gateway (e.g. Microsoft ADFS or Novell/NetIQ) of an institution. SFO has its own authentication endpoint at the SURFsecureID gateway.

Once a user is registered with a second factor in SURFsecureID both SFO authentication and the standard SURFsecureID authentication can be used.

Differences between 'standard' SURFsecureID and SFO authentication

The table below lists the differences between standard authentication and second factor (SFO) authentication that is offered by SURFsecureID gateway to a service provider.

Description	Standard authentication	SFO authenticaton
Authentication of the user's first factor by the SURFsecureID gateway	Always	Never
Authentication of second factor by the SURFsecureID gateway	Based on policy between IdP and SP	Always
User registration	Using SURFsecureID selfservice registration and vetting by an RA
Standard SURFconext features that can be used	Attributes, Authorization, persistent identifiers	None
The service provider specifies the identity of the user during authentication	Never	Always

With SFO the authentication via SURFconext

What is Second Factor Only Authentication?

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.

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 selfservice registration and vetting by an RA
Standard SURFconext features	Attributes, Authorization, persistent identifiers	None

During 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 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:

. During a standard authentication the identity of the user is detemind by SURFconext during the 1^st factor authentication. Because this step is omitted during SFO, the service provider must provide the identity of the user's to SURFsecureID during authentication instead.

Note that also with SFO the registration of users (i.e. linking second factors to user identities) 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 SURFsecureID Gateway. This request MUST:

use the urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect binding. The HTTP-Redirect binding is currently the only suppored binding for making standard or SFO request to SURFsecureID.
be signed using the
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 algorithm. Unsigned authentications requests or request that are signed using a different algorithm are not accepted. Note that the HTTP-Redirect binding binding does not use XML Signatures)signatures. The HTTP-Redirect binding specifies its own signature scheme. See Bindings for the OASIS Security Assertion Markup Language (SAML) V2.0, section 3.4.
include a RequestedAuthnContext with an AuthnContextClassRef with the URI for one of the defined authentication levels for the SURFsecureID environment that your are authenticating to.
include the SURFconext identifier of the user in the Subject element as a NameID (with Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified", see description of AuthnRequest in https://docs.oasis-open.must include the SURFconext identifier (see below) 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 than the standard authentication.

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.

line 2001).

SURFsecureID Implementation notes regarding `RequestedAuthnContext`

The SAML standard allows multiple AuthnContextClassRef elements to be specified in the RequestedAuthnContext. Currenly SURFsecureID will only look at the first AuthnContextClassRef element.
Specifying an AuthnContextClassRef other than on the of the defined authentication level for SFO will result in an error.
The SAML standard allows a Comparision attribute to be added to the the RequestedAuthnContext element. Currently SURFsecureID does not interpret the value of this attribute and behaves as if "minimum" was specified as value for the Comparison attribute, which is a deviation of the SAML standard which specifies "exact" as the default. "minimum" means that the authentication context in the authentication statement that is returned after a successfull authentication will either be the requested authentication context, or the the authentication context of a stronger (i.e. higher level) authentication. SURFsecureID currently always returns the authentication context corrsponding to the highst level at which the user could be authentictated.

Future SURFsecureID versions may support more complex processing of RequestedAuthnContext options and add new AuthnContextClassRef "families" do support different registration policies.

Example AuthnRequest

Below is an example SAML 2.0 SFO AuthnRequest request for the SURFsecureID production environment:

Code Block

language	xml
title	Example SFO AuthRequest to the SURFsecureID production environment
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://sa-gw.surfconext.nl/second-factor-only/single-sign-on"
    				AssertionConsumerServiceURL="https://application-gateway.some-organisation.example.org/consume-assertion"

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="_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://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/surfconext.nl/assurance/sfo-level2</saml:AuthnContextClassRef>
    </samlp:RequestedAuthnContext>    
</samlp:AuthnRequest>

Determining the SURFconext identifier of a user

The SURFconext identifier is build from identifiers that the IdP of the users 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:

...

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

Note that SFO uses a different SingleSignOn Location and a different AuthnConextClassRef identifiers than a standard authentication to SURFsecureID. See SURFsecureID Metadata for Service Providers for the diffenrent AuthnConextClassRef identifiers that are being used by SURfsecureID.

Determining the SURFconext identifier of a user

The SURFconext identifier of a user is built from the values if two different attributes that the identity provider (IdP) of the

...

user's institution sends to SURFconext during authentication. The two attributes that are used to create the SURFconext user identitfier are:

...

urn:mace:

...

terena.org:attribute-def:schacHomeOrganization:

...

the value of

...

this attribute

...

identifies the user

...

's institution.
urn:mace:dir:attribute-def:uid: the value of this attribute identifies the user withing the institution

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

SAML Response

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

Example Response:

{{urn:mace:terena.org:attribute-def:schacHomeOrganization}}:{{urn:mace:dir:attribute-def:uid}}
where:

urn:collab:person:
= fixed prefix.
{{urn:mace:terena.org:attribute-def:schacHomeOrganization}}= value of schacHomeOrganization attribute of the user; typically the same for all users of one institution and will be something like "institution.nl".
{{urn:mace:dir:attribute-def:uid}}= value of uid attribute of the user. Replace each "@" (at) character in the uid with an "_" (underscore) character.

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

Example: urn:collab:person:some-organisation.example.org:m1234567890

SAML Response

The result of a successful authentication is a SAML Response. Note that it does not contain an AttributeStatement and that the Assertion element is signed and that the Response element is not signed. Response signing is not currently supported by SURFsecureID, it may be added in future versions.

Code Block

language	xml
title	Example Response
collapse	true

 <samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol

Code Block

language	xml
title	Example Response
collapse	true

<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="_zQIibz9FKixdlgX8/E7bHqE29wfatcgbsPdVn0NN"
                >
    <saml:Issuer>https://gw.stepup.example.org/second-factory-only/metadata</saml:Issuer> xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
    <samlp:Status>
        <samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success" />
     ID="_ECAokbn0lm7lfVT7THQUl+dSbMrpeyAgiTv0+q16"
            </samlp:Status>
    <saml:Assertion xmlns:xsi Version="http://www.w3.org/2001/XMLSchema-instance"
2.0"
                    xmlns:xsIssueInstant="http://www.w3.org/2001/XMLSchema2016-03-10T15:09:25Z"
                    ID="_zQIibz9FKixdlgX8/E7bHqE29wfatcgbsPdVn0NNDestination="https://application-gateway.some-organisation.example.org/consume-assertion"
                    VersionInResponseTo="2.0_zQIibz9FKixdlgX8E7bHqE29wfatcgbsPdVn0NN">
    <saml:Issuer>https://sa-gw.surfconext.nl/second-factor-only/metadata</saml:Issuer>
    <samlp:Status>
            IssueInstant="2016-03-10T15:09:25Z"
   <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"
            >
        <saml:Issuer>httpsxmlns:xs="http://gwwww.stepup.examplew3.org/second-factory-only/metadata</saml:Issuer>
2001/XMLSchema"
             <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
       ID="_zQIibz9FKixdlgX8E7bHqE29wfatcgbsPdVn0NN"
              <ds:SignedInfo>
      Version="2.0"
          <ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />
          IssueInstant="2016-03-10T15:09:25Z"
                    >
        <ds:SignatureMethod Algorithm="http<saml:Issuer>https://wwwgw.w3stepup.example.org/2001/04/xmldsig-more#rsa-sha256" />
        second-factory-only/metadata</saml:Issuer>
        <ds:ReferenceSignature URI="#_1ROuxGVzJi5bbre6W4woNza82aK41HKjp6aKtw9r">
        xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
            <ds:Transforms>SignedInfo>
                        <ds:Transform Algorithm<ds:CanonicalizationMethod Algorithm="http://www.w3.org/20002001/0910/xmldsig#envelopedxml-exc-signaturec14n#" />
                        <ds:TransformSignatureMethod Algorithm="http://www.w3.org/2001/1004/xmlxmldsig-excmore#rsa-c14n#sha256" />
                    </ds:Transforms><ds:Reference URI="#_1ROuxGVzJi5bbre6W4woNza82aK41HKjp6aKtw9r">
                    <ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256" />
Transforms>
                        <ds:DigestValue>YR5JFfJc1JZIKm7Ao3kXtDupEfeMrhKpD9T1lF1z0Lg=</ds:DigestValue>Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature" />
                </ds:Reference>
            </ds:SignedInfo>
            <ds:SignatureValue>...</ds:SignatureValue><ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />
            <ds:KeyInfo>
                <ds:X509Data></ds:Transforms>
                    <ds:X509Certificate>...</ds:X509Certificate>
DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256" />
                    <ds:DigestValue>YR5JFfJc1JZIKm7Ao3kXtDupEfeMrhKpD9T1lF1z0Lg=</ds:X509Data>DigestValue>
                </ds:KeyInfo>Reference>
            </ds:Signature>SignedInfo>
            <saml:Subject><ds:SignatureValue>...</ds:SignatureValue>
            <saml:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">urn:collab:person:some-organisation.example.org:m1234567890</saml:NameID>
<ds:KeyInfo>
                <ds:X509Data>
             <saml:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">       <ds:X509Certificate>...</ds:X509Certificate>
                <saml:SubjectConfirmationData NotOnOrAfter="2016-03-10T15:14:25Z"</ds:X509Data>
            </ds:KeyInfo>
        </ds:Signature>
        <saml:Subject>
                  Recipient="https://application-gateway.<saml:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">urn:collab:person:some-organisation.example.org/consume-assertion":m1234567890</saml:NameID>
                  <saml:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
                            InResponseTo="_zQIibz9FKixdlgX8/E7bHqE29wfatcgbsPdVn0NN<saml:SubjectConfirmationData NotOnOrAfter="2016-03-10T15:14:25Z"
                                              />
    Recipient="https://application-gateway.some-organisation.example.org/consume-assertion"
        </saml:SubjectConfirmation>
        </saml:Subject>
        <saml:Conditions NotBefore="2016-03-10T15:09:25Z"
                         NotOnOrAfter="2016-03-10T15:14:25Z"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> Response>

Error handling

When the SA gateway is unable or unwilling to authenticate the user a SAML Response For specifiec scenario's, when the authenticated fails, the SURFsecureID gateway sends a SAMLResponse to the SP 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 with subcode urn:oasis:names:tc:SAML:2.0:status:AuthnFailed : The authentication =
Authentication was not successful. This specifically happens when the user cancels the authentication.
Statusurn:oasis:names:tc:SAML:2.0:status:Responder with subcode with subcode urn:oasis:names:tc:SAML:2.0:status:NoAuthnContext : =
The user could not be authenticated at the requested level

Example error response:

. The user does not have an activated (vetted) token at the requests level.
Other situations can also lead to an error response. Specifically:
- No RequestedAuthnContext or AuthnContextClassRef in the AuthnRequest
- An unsupported URI in the AuthnContextClassRef
- No Subject NameID in the AuthnRequest
- The service provider is not authorised to authenticate the user specified in the Subject NameID

A service provider SHOULD be able to handle the first two errors scenarios above (AuthnFailed and NoAuthnContext) in a user friendly manner. These error responses will occur during normal use: users can and do cancel the authentication process and users that do no not yet, or no longer have, a registered seond factor will try to authneticate to your service, and fail.

SURFsecureID does not currenly add a StatusMessage to an "error" response. We plan to add a StatusMessage in a future version of SURFsecureID that provides more context about the error to the operator of the service than can be conveyed using the standard statusCodes.

Example Error Response

Below is an example SAML "error" Response:

Code Block

language	xml
title	Example Error Response
collapse	true

<samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol

Code Block

language	xml
title	Example error response
collapse	true

<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:25Zxmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
                DestinationID="https://application-gateway.some-organisation.example.org/consume-assertionYaszKubip05bTwe7hIWOc5AsNxwmEliPJ88nUQ"
                InResponseToVersion="_zQIibz9FKixdlgX8/E7bHqE29wfatcgbsPdVn0NN">2.0"
                <saml:Issuer>https://gw.stepup.example.org/metadata</saml:IssuerIssueInstant="2015-05-12T12:17:38Z"
                >
    <samlp:Status>
Destination="https://your-sp.example.com/acs-location"
               <samlp:StatusCode ValueInResponseTo="urn:oasis:names:tc:SAML:2.0:status:Responder">
_6d93f735ccfb8d98454999b4016d515834211b0dde"
                >
  <samlp:StatusCode Value="urn:  <saml:Issuer>https://sa-gw.surfconext.nl/authentication/metadata</saml:Issuer>
    <samlp:Status>
        <samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:AuthnFailedRequester" />
        </samlp:StatusCode>
    </samlp:Status>
</samlp:Response>

...

<samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:NoAuthnContext" />
        </samlp:StatusCode>      
    </samlp:Status>
</samlp:Response>

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 SURFsecureID 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 SURFsecureID gateway as either SFO SP or a 'standard' SURFsecureID 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.

You can find the metadata of the SFO endpoints on SURFsecureID Metadata for Service Providers.

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 using being authenticated. When an the SURFsecureID gateway: a push notification (tqr) or an SMS will be sent to the user being authenticated. If 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 behavior of the SFO authentication it is possible to determine whether a username exists or not.

For the above two this 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.

Example

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

Page tree

Versions Compared

Old Version 11

New Version 34

Key

Introduction

Differences between 'standard' SURFsecureID and SFO authentication

What is Second Factor Only Authentication?

Implementation at the SP

SAML AuthRequest

SAML AuthRequest

SURFsecureID Implementation notes regarding `RequestedAuthnContext`

Example AuthnRequest

Determining the SURFconext identifier of a user

Determining the SURFconext identifier of a user

SAML Response

SAML Response

Error handling

Example Error Response

Level: authentication strength

Implementation

Always do a first factor authentication before starting a SFO authentication

Example

Page tree

Page History

Versions Compared

Old Version 11

New Version 34

Key

Introduction

Differences between 'standard' SURFsecureID and SFO authentication

What is Second Factor Only Authentication?

Implementation at the SP

SAML AuthRequest

SAML AuthRequest

SURFsecureID Implementation notes regarding RequestedAuthnContext

Example AuthnRequest

Determining the SURFconext identifier of a user

Determining the SURFconext identifier of a user

SAML Response

SAML Response

Error handling

Example Error Response

Level: authentication strength

Implementation

Always do a first factor authentication before starting a SFO authentication

Example

SURFsecureID Implementation notes regarding `RequestedAuthnContext`