An introduction to Protocol Agnostic Authenticators

Protocol agnostic authenticators are a new feature in PAS 5.1. They can perform user authentication as a function independent of the underlying protocol (like SAML, OIDC or even internal authentication for MyApps or SelfService), making it very flexible for the types of authentication your flows should allow. This means you can reuse the very same authenticators in different flows if you want to, and an overall separation of the concerns of different components. The older authenticators will still work without needing to change any configuration, but will not have access to the new functionality.

This means that the protocol specific functionality has been extracted into separate components, which means many new features are available without authenticator or pipe specific configuration. All you need to do now is finish one simple guide scenario for each protocol you want to support (OIDC/SAML). Some example of the perks that become available straight out of the box with no additional configuration are: 

  • SAML Logout / SLO
  • SAML SignMessage display (no need for SAMLAuthForSigning configuration)
  • SAML SSO (can be enabled/disabled with a setting at the IDP)
  • Full OIDC support according to conformance profiles 'basic', 'implicit', and 'hybrid'
  • All OIDC flows (code/implicit/hybrid)
  • OIDC Refresh tokens
  • OIDC Consent
  • All OIDC client authentication methods (client_secret_basic, client_secret_jwt, client_secret_body, private_key_jwt)
  • OIDC Session Management
  • OIDC Token lifetimes
  • OIDC SSO (can be enabled/disabled with a setting at the OP)
  • OIDC RP initiated logout
  • OIDC Backchannel logout
  • OIDC PKCE (enforced or optional)

To set up your authentication flows using protocol agnostic authenticators, simply use the configuration manager. There is a new "authenticator"-tab there which allows for simple guide scenarios for each new authenticator. To enable SAML or OIDC authentication, simply go to the Federation or OIDC tabs, and create a "SAML Identity Provider" or "OpenID Provider" scenario, where you are prompted to choose which authenticator you would like to use for your IDP or OP. 

To allow support for several authenticators at the same endpoint, you can point your IdP or OP to use a Dispatch or AuthSelector and further control the flows from there. SAML IDPs now have their own pipe that contains an AssertionProvider by default, but if an AssertionProvider has already been run in a previous pipe, it will not override the existing assertion (this is controlled by the default skip_if_expr on the IDP AssertionProvider). This means you can still customize your SAML Assertion depending on which Authenticator you end up using. For OIDC, your ID token will contain of the standard, unmodifiable properties of the protocol (iss, sub, iat, etc...) , as well as the claims the user has authorized. When you set up your OIDC OP, you can set up which scopes should contain what claims. 

Single sign on behavior can be turned on or off at the settings of your SAML IDP or OIDC OP. If turned on, requests will attempt to SSO if a valid session exists at the IDP/OP and the resulting authenticator is the same as the user has previously authenticated at. This means that you can control your flows such that SSO is turned on by default, but if you send a different RequestedAuthenticationContext (with a higher level of assurance for example) that directs the user to a different authenticator, they will have to authenticate again. 

Single sign on behavior also respects the boundaries of their original protocols, meaning SAML ForceAuthn="1" will result in disabled SSO for that login request. Same with OIDC prompt="login", prompt="consent", etc. Details about the new SSO behavior can be found in the document "Single-sign-on behavior in Protocol Agnostic Authenticators".

Modifying your existing IDP/OP/Internal configurations to use this new system is easy. To use the new authenticators as internal authenticators simply go to your module configuration (e.g. MyApps or SelfService). Modify the "auth_redirect_url" such that the pattern is "<your-base-url>/authentication/internal/<your-internal-endpoint-id>". So if the "base_url" is "/selfservice" the "auth_redirect_url" should be "/selfservice/authentication/internal/<your-internal-endpoint-id>". Additionally, you should go to the Avanced-tab in the configuration manager, and click on "Internal authentication endpoints". This is where you add internal authentication endpoints, see image for example. So you simply configure your endpoint id, what authenticator should be used, what the successURL should be (this should be your base_url in the module config). You can also add roles after successful authentication via the "addRoles" config parameter.

For SAML, you need to change your SSO / SLO URLs from the old scheme of <baseurl>/saml/authenticate/<authenticator-id>  to the new scheme: <baseurl>/authentication/saml/<idpid>/login for login, and <baseurl>/authentication/saml/<idpid>/logout for logout. Here you also need to add "authenticatorId" as a configuration property, and it should have the value of the id or alias of the authenticator you would like to use. SAML IDP Metadata is no longer available on the URL of the authenticator, but is now accessed at <baseurl>/authentication/saml/<idpid>/meta. It may however be easier to just create a new SAML IDP via the configuration manager and copy the settings you would like to keep.

For OIDC, the recommendation is to make a new OIDC OP via the configuration manager, but if you wish to manually change everything the steps are similar to the ones for SAML, meaning you need to add "authenticatorId" and modify the URLs accordingly. The new OIDC URLs are <baseurl>/authentication/oidc/<opid>/login, <baseurl>/authentication/oidc/<opid>/token, <baseurl>/authentication/oidc/<opid>/userinfo, <baseurl>/authentication/oidc/<opid>/check_session, <baseurl>/authentication/oidc/<opid>/logout for the authorization endpoint, token endpoint, userinfo endpoint, check session iframe endpoint, and logout endpoint accordingly.