Page Comparison

Current File(s): conf/authn/external-authn-config.xml, conf/authn/authn.properties(V4.1+)
Format: Properties, Native Spring, Properties (V4.1+)

Overview

...

Enabling Module (V4.1+)

For V4.1+, configuring and using this feature requires that you first enable the "idp.authn.External" module if it isn't already enabled. Systems upgraded from older releases generally come pre-enabled due to the prior state of the configuration tree.

(Windows)
C:\opt\shibboleth-idp> bin\module.bat -t idp.authn.External || bin\module.bat -e idp.authn.External
 
(Other)
$ bin/module.sh -t idp.authn.External || bin/module.sh -e idp.authn.External

General Configuration

You may also dynamically derive the path to use, typically so that it can vary based on aspects of the request, by defining a bean named shibboleth.authn.External.externalAuthnPathStrategy of type Function<ProfileRequestContext,String>.

The shibboleth.authn.External.ClassifiedMessageMap is a map of exception/error messages to classified error conditions. You can make use of this map either by modifying it to understand the error or exception messages returned by your external code, or by using the map as is and passing back the literal tokens in the map from your external code via the exception or error message interface.

API

The ExternalAuthentication class makes up the interface between the external code and the IdP. The general flow is:

1. Call ExternalAuthentication.startExternalAuthentication(HttpServletRequest), saving off the result as a key.

2. Do work as necessary (reading request details from the attributes below). Any redirects must preserve the key value returned in step 1 because it must be used to complete the login later.

3. Set request attributes to communicate the result of the login back.

4. Call ExternalAuthentication.finishExternalAuthentication(String, HttpServletRequest, HttpServletResponse). The first parameter is the key returned in step 1.

Example JSP implementations are below.

...

...

...

General Configuration

Most of the usual options are available via authn/authn.properties, and some more advanced cases will require creating new bean definitions in conf/global.xml.

The idp.authn.External.externalAuthnPath property defines the flow redirection path to the resource that's used to perform the external login, by default a context-relative location. It can be modified if needed, but must be a resource with access to the container session. Modify as needed to match the location of your external interface (see the documentation on flow redirects).

You may also dynamically derive the path to use, typically so that it can vary based on aspects of the request, by defining a bean named shibboleth.authn.External.externalAuthnPathStrategy of type Function<ProfileRequestContext,String>.

The shibboleth.authn.External.ClassifiedMessageMap is a map of exception/error messages to classified error conditions. You can make use of this map either by modifying it to understand the error or exception messages returned by your external code.

API

The ExternalAuthentication class makes up the interface between the external code and the IdP. The general flow is:

1. Call ExternalAuthentication.startExternalAuthentication(HttpServletRequest), saving off the result as a key.

2. Do work as necessary (reading request details from the attributes below). Any redirects must preserve the key value returned in step 1 because it must be used to complete the login later.

3. Set request attributes to communicate the result of the login back.

4. Call ExternalAuthentication.finishExternalAuthentication(String, HttpServletRequest, HttpServletResponse). The first parameter is the key returned in step 1.

Example JSP implementations are below.

<%@ page pageEncoding="UTF-8" %>
<%@ page import="net.shibboleth.idp.authn.ExternalAuthentication" %>
<%@ page import="net.shibboleth.idp.authn.ExternalAuthenticationException" %>

<%
try {
    final String key = ExternalAuthentication.startExternalAuthentication(request);
    final String username = request.getRemoteUser();
    if (username != null) {
        request.setAttribute(ExternalAuthentication.PRINCIPAL_NAME_KEY, username);
    }
    ExternalAuthentication.finishExternalAuthentication(key, request, response);
     
} catch (final ExternalAuthenticationException e) {
    throw new ServletException("Error processing external authentication request", e);
}
%>

<%@ page pageEncoding="UTF-8" %>
<%@ page import="net.shibboleth.idp.authn.*" %>
<%@ page import="net.shibboleth.idp.attribute.*"%>
<%@ page import="net.shibboleth.idp.authn.principal.ExternalAuthentication*" %>
<%@ page import="netjava.shibboleth.idp.authn.ExternalAuthenticationException" %>util.*"%>

<%
try {
    final String key = ExternalAuthentication.startExternalAuthentication(request);

   final StringHashSet<Principal> username principals=new request.getRemoteUserHashSet<Principal>();

   if principals.add(username != null) {new UsernamePrincipal("bbarker"));

    //<DataConnector xsi:type="Subject" exportAttributes="mail  request.setAttribute(ExternalAuthentication.PRINCIPAL_NAME_KEY, username);eduPersonNickname" id="myId" />
    }
    ExternalAuthentication.finishExternalAuthentication(key, request, response);
     
} catch (final ExternalAuthenticationException e) {
    throw new ServletException("Error processing external authentication request", e);
}
%>

<%@ page pageEncoding="UTF-8" %>
<%@ page import="net.shibboleth.idp.authn.*" %>
<%@ page import="net.shibboleth.idp.attribute.*"%>
<%@ page import="net.shibboleth.idp.authn.principal.*"%>
<%@ page import="java.util.*"%>

<%
try {
    final String key = ExternalAuthentication.startExternalAuthentication(request);

    HashSet<Principal> principals=new HashSet<Principal>();

    principals.add(new UsernamePrincipal("bbarker"));

    //<DataConnector xsi:type="Subject" exportAttributes="mail eduPersonNickname" id="myId" />
    //<AttributeDefinition ... <InputDataConnector ref="myId" ...
    IdPAttribute attr=new IdPAttribute("eduPersonNickname");
    attr.setValues(Collections.singleton(new StringAttributeValue("Bob Barker")));
    principals.add(new IdPAttributePrincipal(attr));

    attr=new IdPAttribute("mail");
    attr.setValues(Collections.singleton(new StringAttributeValue("bbarker@example.org")));
    principals.add(new IdPAttributePrincipal(attr));

    request.setAttribute(ExternalAuthentication.SUBJECT_KEY,new Subject(false, principals, Collections.EMPTY_SET, Collections.EMPTY_SET));

    ExternalAuthentication.finishExternalAuthentication(key, request, response);

} catch (final ExternalAuthenticationException e) {
    throw new ServletException("Error processing external authentication request", e);
}
%>

Inputs

On first access to the external resource, the request attributes below will be set.

...

Name

...

Type

...

Function

...

opensamlProfileRequestContext

...

ProfileRequestContext

...

Access to full request context tree

...

forceAuthn

...

Boolean

...

Whether the requester asked for re-authentication

...

isPassive

...

Boolean

...

Whether the requested asked for passive authentication

...

relyingParty

...

String

...

Name of the relying party requesting authentication

...

extended

...

Boolean

...

Whether this login flow has been invoked as an extension of another login flow

Outputs

...

Name

...

Type

...

Function

...

principalName          

...

String

...

Name of authenticated subject to use as the login result

...

principal

...

Principal

...

Java Principal object to use as the login result

...

subject

...

Subject

...

Java Subject object to use as the login result

...

authnError

...

String

...

Error message to return in place of a successful login

...

authnException

...

Exception

...

Explicit exception object to return in place of a successful login

...

authnInstant

...

Instant

...

Exact time of authentication to report back

...

authnAuthorities

...

Collection<String>

...

Ordered collection of URIs identifying upstream/proxied authenticating "authorities" used to authenticate the subject

...

attributes

...

Collection<IdPAttribute>

...

Collection of IdPAttribute objects to associate with the authenticated subject

...

doNotCache

...

Boolean

...

If true, prevents the result from being saved for future use for SSO

...

previousResult

...

Boolean

...

If true, the "new" AuthenticationResult is created with the "previousResult" flag set to true (mainly impacts auditing)

Only one "result" or error attribute should be set by the external code. Setting more than one has unspecified behavior. In most cases, the simple principalName should be returned on success, but you can return the more complex objects to pass back additional information such as public or private credentials or custom principal data.

Any IdPAttribute objects supplied will be processed by the AttributeFilter service as "inbound" data. If at least one value in the "authnAuthorities" attribute is supplied, it is set as the "issuer" of the attributes for the purposes of the filter evaluation.

Note that returning a Subject is often paired with setting the shibboleth.authn.External.addDefaultPrincipals bean (V4.0) or idp.authn.External.addDefaultPrincipals property (V4.1+) to false, to dynamically establish Principal(s) representing the authentication method used without having them overwritten.

For example, your External flow's supportedPrincipals property might be defined to include both password and multi-factor authentication Principals (meaning it supports both methods), but you can return the specific method used at runtime in the Subject. For SAML 2.0, this is typically done (programmatically) by using the net.shibboleth.idp.saml.authn.principal.AuthnContextClassRefPrincipal class with the appropriate value from the standard or a deployment. Other classes in that package address SAML 1.1 and unusual SAML 2.0 use cases. For the built-in constants defined by the standard, there are Java constants available via org.opensaml.saml.saml2.core.AuthnContext.

Reference

The beans defined, or expected to be defined, in authn/external-authn-config.xml follow:

//<AttributeDefinition ... <InputDataConnector ref="myId" ...
    IdPAttribute attr=new IdPAttribute("eduPersonNickname");
    attr.setValues(Collections.singleton(new StringAttributeValue("Bob Barker")));
    principals.add(new IdPAttributePrincipal(attr));

    attr=new IdPAttribute("mail");
    attr.setValues(Collections.singleton(new StringAttributeValue("bbarker@example.org")));
    principals.add(new IdPAttributePrincipal(attr));

    request.setAttribute(ExternalAuthentication.SUBJECT_KEY,new Subject(false, principals, Collections.EMPTY_SET, Collections.EMPTY_SET));

    ExternalAuthentication.finishExternalAuthentication(key, request, response);

} catch (final ExternalAuthenticationException e) {
    throw new ServletException("Error processing external authentication request", e);
}
%>

Inputs

On first access to the external resource, the request attributes below will be set.

Outputs

Only one "result" or error attribute should be set by the external code. Setting more than one has unspecified behavior. In most cases, a simple principalName should be returned on success, but you can return the more complex objects to pass back additional information such as public or private credentials or custom principal data.

Any IdPAttribute objects supplied will be processed by the AttributeFilter service as "inbound" data. If at least one value in the "authnAuthorities" attribute is supplied, it is set as the "issuer" of the attributes for the purposes of the filter evaluation.

Note that returning a Subject is often paired with setting the idp.authn.External.addDefaultPrincipals property to false, to dynamically establish Principal(s) representing the authentication method used without having them overwritten.

For example, your External flow's supportedPrincipals property might be defined to include both password and multi-factor authentication Principals (meaning it supports both methods), but you can return the specific method used at runtime in the Subject. For SAML 2.0, this is typically done (programmatically) by using the net.shibboleth.idp.saml.authn.principal.AuthnContextClassRefPrincipal class with the appropriate value from the standard or a deployment. Other classes in that package address SAML 1.1 and unusual SAML 2.0 use cases. For the built-in constants defined by the standard, there are Java constants available via org.opensaml.saml.saml2.core.AuthnContext.

Reference

<list>
    <bean parent="shibboleth.SAML2AuthnContextClassRef"
        c:classRef="urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport" />
    <bean parent="shibboleth.SAML2AuthnContextClassRef"
        c:classRef="urn:oasis:names:tc:SAML:2.0:ac:classes:Password" />
    <bean parent="shibboleth.SAML1AuthenticationMethod"
        c:method="urn:oasis:names:tc:SAML:1.0:am:password" />
</list>

idp.authn.External.supportedPrincipals = \
    saml2/urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport, \
    saml2/urn:oasis:names:tc:SAML:2.0:ac:classes:Password, \
    saml1/urn:oasis:names:tc:SAML:1.0:am:password

<util:list id="shibboleth.AvailableAuthenticationFlows">
 
    <bean p:id="authn/External" parent="shibboleth.AuthenticationFlow"
            p:order="%{idp.authn.External.order:1000}"
            p:nonBrowserSupported="%{idp.authn.External.nonBrowserSupported:false}"
            p:passiveAuthenticationSupported="%{idp.authn.External.passiveAuthenticationSupported:false}"
            p:forcedAuthenticationSupported="%{idp.authn.External.forcedAuthenticationSupported:false}"
            p:proxyRestrictionsEnforced="%{idp.authn.External.proxyRestrictionsEnforced:%{idp.authn.enforceProxyRestrictions:true}}"
            p:proxyScopingEnforced="%{idp.authn.External.proxyScopingEnforced:false}"
            p:discoveryRequired="%{idp.authn.External.discoveryRequired:false}"
            p:lifetime="%{idp.authn.External.lifetime:%{idp.authn.defaultLifetime:PT1H}}"
            p:inactivityTimeout="%{idp.authn.External.inactivityTimeout:%{idp.authn.defaultTimeout:PT30M}}"
            p:reuseCondition-ref="#{'%{idp.authn.External.reuseCondition:shibboleth.Conditions.TRUE}'.trim()}"
            p:activationCondition-ref="#{'%{idp.authn.External.activationCondition:shibboleth.Conditions.TRUE}'.trim()}"
            p:subjectDecorator-ref="#{getObject('%{idp.authn.External.subjectDecorator:}'.trim())}">
        <property name="supportedPrincipalsByString">
            <bean parent="shibboleth.CommaDelimStringArray"
                c:_0="#{'%{idp.authn.External.supportedPrincipals:}'.trim()}" />
        </property>
    </bean>
 
</util:list>

Notes

Note that upgraded systems will have alternate, legacy approaches to configuring this feature, as noted above.