Current File(s): conf/authn/ipaddress-authn-config.xml, conf/authn/authn.properties (V4.1+)
Format: Native Spring, Properties (V4.1+)
Overview
The authn/IPAddress login flow applies the user agent's address to a mapping of address range(s) to username(s) as a form of pseudo-authentication. This isn't the same as authorizing access to something by address, because a real user identity is produced as a result.
This flow is implemented as a "fall-through" so that under normal error conditions (no address available, no valid mapping), it passes control back to select another flow to run, so it can easily be combined with other methods. Of course, as shipped, the IdP will communicate that the form of authentication done was not based on a password.
Enabling Module (V4.1+)
For V4.1+, configuring and using this feature requires that you first enable the "idp.authn.IPAddress" 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.IPAddress || bin\module.bat -e idp.authn.IPAddress
(Other)
$ bin/module.sh -t idp.authn.IPAddress || bin/module.sh -e idp.authn.IPAddress
General Configuration
Use conf/authn/ipaddress-authn-config.xml to configure this flow.
The shibboleth.authn.IPAddress.Mappings bean is the map between usernames and lists of CIDR address ranges. An IP CIDR Calculator may help in calculating the CIDR notation for an IP range. Note that en empty map, which is the default, essentially makes this flow non-operable in practice.
The following example maps only the IPv4 and IPv6 localhost addresses to the name "jdoe":
<util:map id="shibboleth.authn.IPAddress.Mappings">
<entry key="jdoe">
<list>
<value>127.0.0.1/32</value>
<value>::1/128</value>
</list>
</entry>
</util:map>
The shibboleth.authn.IPAddress.Transforms bean allows for address transformations before comparing them to the address ranges, essentially a kind of on-the-fly address translation. A transform is a Pair object containing a regular expression and a replacement expression.
Reference
Beans (V4.0)
The beans defined in authn/ipaddress-authn-config.xml follow:
Bean ID | Type | Default | Description |
|---|
shibboleth.authn.IPAddress.Mappings | Map<String,List<IPRange>> | Empty Map | The entry values are a list of CIDR address range strings to map to the username in the entry key |
shibboleth.authn.IPAddress.Transforms | List<Pair<String,String>> | | Pairs of regular expressions and replacement expressions to apply to the username |
shibboleth.authn.IPAddress.resultCachingPredicate | Predicate<ProfileRequestContext> | | An optional bean that can be defined to control whether to preserve the authentication result in an IdP session |
shibboleth.authn.IPAddress.addDefaultPrincipals
| Boolean | true | Whether to add the content of the supportedPrincipals property of the underlying flow descriptor to the resulting Subject |
Beans (V4.1+)
The beans defined in authn/ipaddress-authn-config.xml follow:
Bean ID | Type | Default | Description |
|---|
shibboleth.authn.IPAddress.Mappings | Map<String,List<IPRange>> | Empty Map | The entry values are a list of CIDR address range strings to map to the username in the entry key |
shibboleth.authn.IPAddress.Transforms | List<Pair<String,String>> | | Pairs of regular expressions and replacement expressions to apply to the username |
shibboleth.authn.IPAddress.resultCachingPredicate | Predicate<ProfileRequestContext> | | An optional bean that can be defined to control whether to preserve the authentication result in an IdP session |
Properties (V4.1+)
The general properties configuring this flow via authn/authn.properties are:
Name | Default | Description |
|---|
idp.authn.IPAddress.order | 1000 | Flow priority relative to other enabled login flows (lower is "higher" in priority) |
idp.authn.IPAddress.nonBrowserSupported | true | Whether the flow should handle non-browser request profiles (e.g., ECP) |
idp.authn.IPAddress.passiveAuthenticationSupported | true | Whether the flow allows for passive authentication |
idp.authn.IPAddress.forcedAuthenticationSupported | false | Whether the flow supports forced authentication |
idp.authn.IPAddress.proxyRestrictionsEnforced | %{idp.authn.enforceProxyRestrictions:true} | Whether the flow enforces upstream IdP-imposed restrictions on proxying |
idp.authn.IPAddress.proxyScopingEnforced | false | Whether the flow considers itself to be proxying, and therefore enforces SP-signaled restrictions on proxying |
idp.authn.IPAddress.discoveryRequired | false | Whether to invoke IdP-discovery prior to running flow |
idp.authn.IPAddress.lifetime | %{idp.authn.defaultLifetime:PT60S} | Lifetime of results produced by this flow |
idp.authn.IPAddress.inactivityTimeout | %{idp.authn.defaultTimeout:PT60S} | Inactivity timeout of results produced by this flow |
idp.authn.IPAddress.reuseCondition | shibboleth.Conditions.TRUE | Bean ID of Predicate<ProfileRequestContext> controlling result reuse for SSO |
idp.authn.IPAddress.activationCondition | shibboleth.Conditions.TRUE | Bean ID of Predicate<ProfileRequestContext> determining whether flow is usable for request |
idp.authn.IPAddress.subjectDecorator | | Bean ID of BiConsumer<ProfileRequestContext,Subject> for subject customization |
idp.authn.IPAddress.supportedPrincipals | (see below) | Comma-delimited list of protocol-specific Principal strings associated with flow |
idp.authn.IPAddress.addDefaultPrincipals | true | Whether to auto-attach the preceding set of Principal objects to each Subject produced by this flow |
As a non-password based flow, the supportedPrincipals property defaults to the following XML:
<list>
<bean parent="shibboleth.SAML2AuthnContextClassRef"
c:classRef="urn:oasis:names:tc:SAML:2.0:ac:classes:InternetProtocol" />
</list>
In property form, this is expressed as:
idp.authn.IPAddress.supportedPrincipals = \
saml2/urn:oasis:names:tc:SAML:2.0:ac:classes:InternetProtocol
SAML 1 does not define an AuthenticationMethod constant for this kind of authentication, so only a SAML 2 AuthnContextClassRef is applied. An "unspecified" method constant will be used with SAML 1 unless otherwise configured.
Flow Descriptor XML (V4.1+)
To replace the internally defined flow descriptor bean, the following XML is required:
<util:list id="shibboleth.AvailableAuthenticationFlows">
<bean p:id="authn/IPAddress" parent="shibboleth.AuthenticationFlow"
p:order="%{idp.authn.IPAddress.order:1000}"
p:nonBrowserSupported="%{idp.authn.IPAddress.nonBrowserSupported:true}"
p:passiveAuthenticationSupported="%{idp.authn.IPAddress.passiveAuthenticationSupported:true}"
p:forcedAuthenticationSupported="%{idp.authn.IPAddress.forcedAuthenticationSupported:false}"
p:proxyRestrictionsEnforced="%{idp.authn.IPAddress.proxyRestrictionsEnforced:%{idp.authn.enforceProxyRestrictions:true}}"
p:proxyScopingEnforced="%{idp.authn.IPAddress.proxyScopingEnforced:false}"
p:discoveryRequired="%{idp.authn.IPAddress.discoveryRequired:false}"
p:lifetime="%{idp.authn.IPAddress.lifetime:PT60S}"
p:inactivityTimeout="%{idp.authn.IPAddress.inactivityTimeout:PT60S}"
p:reuseCondition-ref="#{'%{idp.authn.IPAddress.reuseCondition:shibboleth.Conditions.TRUE}'.trim()}"
p:activationCondition-ref="#{'%{idp.authn.IPAddress.activationCondition:shibboleth.Conditions.TRUE}'.trim()}"
p:subjectDecorator-ref="#{getObject('%{idp.authn.IPAddress.subjectDecorator:}'.trim())}">
<property name="supportedPrincipalsByString">
<bean parent="shibboleth.CommaDelimStringArray"
c:_0="#{'%{idp.authn.IPAddress.supportedPrincipals:}'.trim()}" />
</property>
</bean>
</util:list>
In older versions and upgraded systems, this list is defined in conf/authn/general-authn.xml. In V4.1+, no default version of the list is provided and it may simply be placed in conf/global.xml if needed.