Preface

The document assumes reader is familiar with SAML2 and Haka identity federation.

Introduction

The goal of this document is to describe SAML2 proxy capable of elevating the user authentication. SAML2 proxy is a hub that acts as both SP and IdP. It relays both authentication requests and responses. Solely relaying these messages does not provide much value. The value comes from control. Proxy may intervene and also change the context of those messages. This includes (but is not limited to) for instance enriching the attributes of the assertion and elevating the level user is authenticated on.
The reasoning why elevation of user authentication is best (easiest) done by proxy is the way Haka is constructed. Haka is a mesh federation, having tens of IdPs. If a service required higher level of authentication than normally provided password method, it would have to have the change implemented in all the IdP's requiring its services. As we put a proxy between the SP and IdP, we are able to offer elevated authentication for all SPs requiring it, and this is without requiring any changes in the IdPs.
Elevated authentication is not the only use case for this model. Proxy can also be used for manipulating released attribute set. This may mean adding, removing or altering attribute values. The values may be related to virtual organization (VO), entitlement or anything that is not meaningful to maintain in home organization. Introducing a centrally managed proxy may actually alter how Haka is operated in the long run.
4. Additional Value5. Auth Resp3. Auth Resp2. Auth Req1.Auth ReqIdPProxySP

Description of Step Up Proxy

This chapter describes how proxy should behave. We are using elevated authentication as the example of added value here as that is our primary target.

Authentication Request Handling

As Proxy receives authentication request from SP it will have to check the requested authentication context class (i.e. authentication method). The list of authentication methods the proxy supports is deployment specific. At least one of those methods has a special meaning, referred from now on as StepUp method. There can be any number of different StepUp methods deployed on the proxy and it must be understood that StepUp method may actually be a list of methods (i.e. method for email verification, sms verification, token etc.) but for the sake of readability we will refer to it as StepUp method.
If Proxy does not support the requested method, error "status:NoAuthnContext" is returned to SP. Otherwise a new authentication request is formed. At this point, the requested method may be mapped to a new value. This enables proxy to connect two parties that understand requested methods differently. Mapped authentication context class of the original request is used in the new request. Note that at minimum there must be mapping of StepUp methods to nonexistent requested method. Further, the list of parameters that are copied from original request to the new request are:

  • NameIdPolicy
  • RequestedAuthContext (if not originally value StepUp)
  • ForceAuthn
  • IsPassive

Rest of the authentication request parameters of the original request are ignored. In essence, proxy reserves the authentication context class value of StepUp for it's own operation.

Authentication Request: Method Not Supported


Proxy receives an authentication request. The requested authentication method is not StepUp or any other supported by proxy. Authentication error response with value "status:NoAuthnContext" is returned.

Authentication Request: Method Supported

Proxy receives an authentication request. The requested authentication method is supported by proxy. New authentication request is formed (discovery is out of scope here) for IdP. If the original request did not contain any specific request for method or if the method was StepUp, the new request contains no requested method. Otherwise, an authentication context class of the original request (or it's mapping) is used also in the new request. Also NameIdPolicy, ForceAuthn and IsPassive values are copied to new request if they exist in original one.

Authentication Response Handling

If the proxy receives an authentication response indicating error, a new authentication error response is formed based on it, and sent to the SP. Proxy may try to re authenticate user instead of sending the error response.
If the proxy receives successful authentication response it will first check how it compares to the requested authentication method it in the original request. If the request contains requested method other than value reserved for StepUp and the response does not satisfy it (or mapping of the method if it exists), an authentication error response with value "status:NoAuthnContext" is sent to SP. If the original request contains requested method other than value reserved for StepUp and the value of response (or mapped value of it if it exists) is satisfactory a successful authentication response is formed using the authentication context class of the original response (or mapping of the method if it exists).
If the original request contains requested method value reserved for StepUp and IdP is already providing an authentication method equal or exceeding it's value we check if proxy is specifically configured to trust the IdP to provide that method. If IdP is trusted to use the method, authentication response is formed using the authentication context class of the original response. This whitelisting of IdPs providing StepUp method is needed to guarantee the client SP's that the authentication has been performed on required level. In all other cases we continue to StepUp phase.
StepUp phase may require a specific user attribute value. The value may be an email address or mobile phone number for instance depending on the StepUp method used. If that value is required and not present, proxy halts the execution and informs user of the matter (not if passive authentication is requested) after which authentication error response is formed. If the SteUp attribute value is present, a StepUp challenge is formed and sent by appropriate means (sms, email, totp) to the user. Proxy obtains a challenge response from the user. Challenge response may be obtained by presenting a web form to user or any other method suitable to step up method. If the response cannot be verified, proxy halts the execution and informs user of the matter (not if passive authentication is requested) after which authentication error response is formed. In case of successful response to the challenge, proxy forms an authentication response indicating success using authentication context class StepUp.

Authentication Response: Error Response

Proxy receives an authentication response indicating error. Proxy may at this point try to re authenticate user and form a new authentication request. This example diagram shows proxy deciding to send authentication error response to SP.

Authentication Response: Request not fulfilled

Original request by SP contains requested method other than StepUp. Authentication method (or it's mapping) by IdP does not satisfy the requested method. Authentication error response with value "status:NoAuthnContext" is sent to SP.

Authentication Response: No StepUp

As the original request contains requested method other than value reserved for StepUp and the method value of response (or mapped value of it if it exists) is satisfactory a successful authentication response is formed using the authentication method of the original response (or mapping of the method if it exists).

Authentication Response: StepUp attribute is missing

Original request (authentication method) by SP has the requested authentication method value matching StepUp and this is not satisfied by the authentication response of the IdP.
Proxy may require a specific user attribute to be present in order to perform the StepUp. The attribute may be email or mobile phone for instance. If the value for the attribute is not present proxy halts the execution and informs user of the matter unless IsPassive is set to "true". Finally, authentication error response is formed.

Authentication Response: StepUp response fails

Original request (authentication method) by SP has the requested authentication method value matching StepUp and this is not satisfied by the authentication response of the IdP. There is a StepUp attribute populated.


StepUp Proxy generates a challenge, passes it to challenge sender and obtains challenge response from the user. If the response to the challenge cannot be verified, proxy halts the execution and informs user of the matter.
Note! Generate Challenge and Verify Response actions are performed by own entity (like Send Challenge by Challenge Sender) and not by Proxy as in the picture. This is just to simplify picture.

Authentication Response: StepUp

Original request (authentication method) by SP has the requested authentication method value reserved for StepUp and it is not satisfied by the authentication response of the IdP. There is a StepUp attribute populated.

StepUp Proxy generates a challenge, passes it to challenge sender and obtains challenge response from the user. If the response to challenge can be verified, proxy sends an authentication response carrying StepUp authentication method to the SP.
Note! Generate Challenge and Verify Response actions are performed by own entity (like Send Challenge by Challenge Sender) and not by Proxy as in the picture. This is just to simplify picture.

Implementation Plan

In this chapter we describe a plan how to implement functionality described in chapter Description of Step Up Proxy.

Main Modules

StepUp Proxy consists of two open source main modules: Shibboleth SP V2 and Shibboleth IdP V3. From now on we refer to the modules as PSP (Proxy SP) and PIdP (Proxy IdP).
Responsibilities of the PIdP in the proxy are to handle incoming authentication requests, control the authentication relaying to the PSP, process authentication responses relayed back from PSP, provide possibility to aggregate more user attributes, perform the possible StepUp and finally to construct the authentication response to the requesting SP.
Responsibility of PSP is to process the responses from IdPs and to relay the authentication response information to the PIdP.

Bridge between PSP and PIdP, Proxy

Shibboleth SP V2 and Shibboleth IdP V3 do not work as a proxy without some effort. We bridge PIdP to PSP by using modules and conventions described in project https://github.com/Digipalvelutehdas/MPASS-proxy/tree/master/idp-authn-impl-shibsp.
In short, the idea in the bridge is to protect (shibbolize) the authentication webflow in PIdP with PSP and therefore have access to authentication parameters provided by PSP in the flow. The process starts as PIdP's authentication webflow triggers a new authentication sequence by directing the user to login handler of PSP. This will result in a standard SAML2 authentication sequence between PSP and its relying party IdP. The Authentication sequence is triggered in a way that once it is finished (successfully) the control comes back to the authentication webflow in PIdP. At this point PIdP may use the information provided, as would any shibbolized application. All this can be accomplished by using modules in idp-authn-impl-shibsp -project and defining an authentication flow using them.

Authentication request handling, configuring the bridge

We create authentication flow that utilizes the MPASS-proxy bridge implementation. Using standard Shibboleth IdP V3 conventions this flow lists the supported authentication methods. The list itself is out of scope this document. Now we have achieved the behavior described in sequence Authentication Request: Method Not Supported.
To make sequence Authentication Request: Method Supported work we still need to pass parameters from the original request to the new request. This is achieved in the flow by manipulating the redirect location to PSP login handler. This enables us to pass the desired values of NameIdPolicy, IsPassive and ForceAuth parameters. The original values of the originating request are accessible to the authentication flow and the passing of values may be achieved purely by flow configuration.
The flow needs still to handle the manipulation of RequestedAuthContext . This manipulation is implemented so that a matching RequestedAuthContext in the originating request is changed to one that is defined (can be also nonexistent). The manipulation method supports multiple mappings of RequestedAuthContext values. Without this step, the proxy loses it's StepUp characteristic and can be used as a vanilla proxy.

Authentication response handling, StepUp Flow

The MPASS-proxy bridge allows us to create basic vanilla Proxy. The user authentication is outsourced, the received assertion is handled in PSP, reprocessed again in PIdP as an authenticated user which includes not only populating the received attributes but a full set of reprocessing: attribute resolving, attribute filtering and finally creating a new assertion for the ultimate client SP.
To add StepUp flavor, we intervene to PIdP's reprocessing in the phase between attribute filtering and creating of new assertion. The intervention is done by creating a post authentication interceptor flow for StepUp. In practice this means that StepUp flow receives control in a phase where it is able to utilize the information sent by home organization IdP and attributes resolved (and filtered) by the PIdP itself.

StepUp flow actions

The StepUp flow is responsible of the sequences starting from Authentication Response: Request not fulfilled. The following actions are pseudo actions, the actual implementation may (and should) differ.

Action: Check Requested method (and other parameters)

Compare the authentication method of the IdP response to the original requested method of the SP.

  • If the performed authentication is satisfactory halt the execution of the StepUp flow and return control successfully to the calling flow. Otherwise,
  • if the original requested method was the value reserved for StepUp, continue StepUp flow by moving to Check StepUp Attribute-action. Otherwise,
  • halt the execution and show condolences to the user. Requested authentication method cannot be met.

Action: Check StepUp Attribute

Verify that the user has a StepUp attribute value present.

  • If there is no attribute name defined, move to Generate Challenge-action. Otherwise,
  • if there is attribute name defined but the user has no such attribute value, halt the execution and show condolences to the user. StepUp cannot be performed. Otherwise,
  • move to Generate Challenge-action.

Action: Generate Challenge

Call plugin implementation to generate a challenge. Input is the value of the resolved StepUp attribute value. Verify response.

  • If the result is failure, halt the execution and show condolences to the user. StepUp cannot be performed. Otherwise,
  • store the challenge and move to Send Challenge-action

Action: Send Challenge

Call plugin implementation to send the challenge. Input is the value of the Challenge and StepUp attribute value. Verify response.

  • If the result is failure, halt the execution and show condolences to the user. StepUp cannot be performed. Otherwise,
  • move to Verify Response-action.

Action: Verify Response

Present a webform for user to respond to challenge. Once the user has responded call plugin implementation to verify the response. Input is value of the Challenge, StepUp attribute value and user Response to the challenge.

  • If the result is failure, halt the execution and show condolences to the user. StepUp failed. Otherwise,
  • set the authentication method value of the authentication response to the value reserved for StepUp. Return control successfully to the calling flow.
  • No labels