Stepup in Engineblock

OpenConext Stepup integrates with Engineblock. This means that any SP connected to Engineblock can be protected with a second factor.

How does it work

You need a working installation of OpenConext Stepup. For the SP in principle nothing changes. All the handling is done by Engineblock.

In Manage one configures that for a given SP, or an IdP/SP-combination, Stepup is required (for details see below). Additionally one can use OpenConext-PDP to require Stepup based on specific user attributes.

After the authnrequest authentication first proceeds normally via the IdP. On return to engine there's the checks for the mandatory attributes, scope and PDP. Then, but before consent, it is checked whether stepup is required for this SP. If so, the user will be sent to the Stepup Gateway to present his or her second factor. If this succeeds or fails, the user is sent back to Engineblock.

If it succeeded, the user (possibly after giving consent) is sent on on the SP. For the SP there's no difference compared to the no-stepup-scenario, except that in the assertion the AuthnContextClassRef is set to which Level of Assurance has been used.

If engine receives a message from Stepup Gateway that logging in failed, engine will present an error message to the user and logging in is stopped.

Configuration of Engineblock

This document presumes you have set up working installations of both Engineblock and Stepup. Engineblock will call the "SFO" endpoint of Stepup Gateway.

In your ansible environment:

• Add your Stepup Gateway's public key in files/certs/stepup_gateway.pem.
• Configure the following in your environment's group vars. The values should make sense if you look at the configuration of your Stepup installation.

engine_stepup_gateway_sfo_entity_id: "https://gateway.yourdomain/second-factor-only/metadata"
engine_stepup_gateway_sfo_sso_location: "https://gateway.yourdomain/second-factor-only/single-sign-on"
engine_stepup_gateway_sfo_public_key_file: "/etc/openconext/stepup_gateway.pem"

engine_stepup_gateway_loa2: "http://yourdomain/assurance/sfo-level2"
engine_stepup_gateway_loa3: "http://yourdomain/assurance/sfo-level3"

engine_stepup_authn_context_class_ref_blacklist_regex: "#http://yourdomain/assurance/loa[1-3]#"

The blacklist_regex option is to block any regular IdP from sending authncontextclassrefs that we want to expose to SP's. So the regular expression should match your loa strings.

Configuration in Stepup

Stepup needs to know about Engineblock. Put the following in your configuration and push it tomanagement/configuration:

        {
          "entity_id": "https://engine.vm.openconext.org/authentication/stepup/metadata",
          "public_key": "Engine's public key",
          "acs": [
            "https://engine.vm.openconext.org/authentication/stepup/consume-assertion"
          ],
          "loa": {
            "__default__": "http://stepup.example.com/assurance/loa1"
          },
          "assertion_encryption_enabled": true,
          "second_factor_only": true,
          "second_factor_only_nameid_patterns": [
            "urn:collab:person:"
          ],
          "blacklisted_encryption_algorithms": []
        },

Configuration in Manage and PDP

Stepup for a complete SP can be configured in Manage by setting the option coin:stepup:requireloa. Choose the desired minimum LOA. That's all. It can be disabled again by removing the option from the SP.

It is also possible to only require stepup for specific IdP's that login to a given SP. This happens in Manage under the IdP in the tab "Stepup". Choose an SP and set the minimum LoA.

When using the Policy Decision Engine (>=3.0), you can create rules of the type "Stepup" in the PDP interface. Here you can decide that a specific LoA is required based on the user's attributes (including their IP address). The SP must have the flag coin:policy_decision_required set for the PDP to be invoked. These rules can be combined with classic PDP Admit/Deny rules.

Any of these places to configure stepup a LoA requirement can ensue. Engineblock will pick the highest of all required LoA's for this IdP/SP/user combinations and require the user to present a token at this level.

There's also the option coin:stepup:allow_no_token. This is only for the specific use case where you'd want a user to present a second factor token if they have registered one, but be able to continue to the SP if they don't. The SP will be informed via authncontextclassref that the user has authenticated at loa1 in the latter case. This can be dangerous to use because it only requires a username and password to remove a token registration for a user. Hence this is only intended for very specific scenarios.