Page Comparison

File(s): conf/admin/general-admin.xml (V4,0), conf/admin/admin.properties (V4.1+) conf/admin/unlock-keys.xml, views/admin/unlock-keys.vm
Format: Native Spring, Velocity, Properties (V4.1+)

Overview

The "attended restart" feature renders the IdP unusable if it restarts without human intervention. Most systems obviously focus on the opposite of that characteristic. The reason behind this feature is key protection. There aren't a lot of cost-effective, simple solutions to protecting private and secret keys (there are complex ones, expensive ones, and complex, expensive ones, of course). The concept behind this feature is that it allows keys to be encrypted on disk, but without the password stored anywhere with the key and entered manually when the service is restarted.

...

This feature is a bit unusual so it's not just a "turn on setting" sort of thing, but something you have to make a few adjustments to the configuration to use. There are two parts to using this:

• Adjust the private and secret key settings to defer availability.

• Enable the unlock-keys webflow to get them installed after startup.

There are two significant risk points, the private key(s) used to sign messages and the secret key(s) used to support client-side session storage. Not every system uses the latter, but client-side storage is the default, so it's typically a factor. There are also private key(s) used to decrypt XML, but the impact of those keys is much less significant, and they don't get much use. Nevertheless, the feature supports unlocking private keys regardless of purpose so if you wanted to leave the decryption keys locked, that's certainly possible.

...

The secret key component, if it's in use, is normally configured in idp.properties, or in later versions, a separate credentials/secrets.properties file. The change needed here is simply to eliminate the passwords that unlock the keystore and key entry, normally these properties:

...

idp.properties

idp.sealer.storePassword = password
idp.sealer.keyPassword = password

...

If the flow believes that it's done this successfully, it records that fact so that if it runs again it simply skips these steps. If it detects a failure, it leaves any remaining work undone and redisplays the form, and the log should usually indicate what didn't work. This is not meant as a fancy GUI for remote use without access to the server and the logs.

Added to conf/admin/general-admin.xml

<bean parent="shibboleth.OneTimeAdminFlow"
	c:id="http://shibboleth.net/ns/profiles/unlock-keys"
    p:loggingId="UnlockKeys"
	p:authenticated="true"
	p:policyName="AccessByAdminUser" />

The last couple of settings are deployment-specific. This example presumes that the rule for accessing the flow is that the user must login first, and that a map entry will be defined in conf/access-control.xml keyed under "AccessByAdminUser" that defines which usernames can access the flow. The access control features are described under AccessControlConfiguration.

There's total flexibility on this, it's up to you to define the rules. You can even set bean properties that typically are used in relying-party.xml like defaultAuthenticationMethods to control what kind of authentication has to be done (e.g. requiring MFA). Authentication in general won't rely on the keys being unlocked here, so there won't usually be any circular dependency there.

To get this working, the module must be enabled (as mentioned above) and some Spring beans defined to describe to the flow what it needs to unlock.

Controlling Access to the Flow

There are properties in conf/admin/admin.properties that will control the use of authentication and the access control rule applied to the flow. These are deployment-specific, but the defaults assume that the rule for accessing the flow is that the user must login first but grants no access.

The idp.unlock.accessPolicy property can be set to "AccessByAdminUser" and a map entry defined in conf/access-control.xml keyed under "AccessByAdminUser" that defines which usernames can access the flow. These access control features are described under AccessControlConfiguration.

You can even set bean properties that typically are used in relying-party.xml like defaultAuthenticationMethods to control what kind of authentication has to be done (e.g. requiring MFA). Authentication in general won't rely on the keys being unlocked here, so there won't usually be any circular dependency there.

If you want to customize this flow via XML or wish to apply settings not supported by properties, you can override the flow descriptor by creating your own bean (see the Flow Descriptor example in the Reference below. With this in place, you can add other properties to the bean (such as defaultAuthenticationMethods) to adjust behavior.

...

In addition to populating it with any "credential" beans whose private keys will be left out, this is where you define the information the flow needs so it knows what to do, using these beans:

• shibboleth.unlock-keys.KeyStrategies

• shibboleth.unlock-keys.Credentials

• shibboleth.unlock-keys.PrivateKeys

All of these beans are ordered collections.

...

The template also illustrates a useful idea of embedding a SSO push link that can be used at the end to verify that the unlocked IdP works correctly (though you'd have to look at the log to know for certain the secret key is working).

Reference

<util:list id="shibboleth.AvailableAdminFlows">
 
    <bean parent="shibboleth.OneTimeAdminFlow"
        c:id="http://shibboleth.net/ns/profiles/unlock-keys"
        p:loggingId="%{idp.unlock-keys.logging:UnlockKeys}"
        p:policyName="%{idp.unlock-keys.accessPolicy:AccessDenied}"
        p:nonBrowserSupported="%{idp.unlock-keys.nonBrowserSupported:false}"
        p:authenticated="%{idp.unlock-keys.authenticated:true}"
        p:resolveAttributes="%{idp.unlock-keys.resolveAttributes:false}" />
 
</util:list>

Example

In a typical example, the following assumes you want to unlock both the system-supplied secret keystore and the default signing key:

...

Example conf/admin/unlock-keys.xml

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
    xmlns:context="http://www.springframework.org/schema/context"
    xmlns:util="http://www.springframework.org/schema/util" xmlns:p="http://www.springframework.org/schema/p"
    xmlns:c="http://www.springframework.org/schema/c" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
                        http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context.xsd
                        http://www.springframework.org/schema/util http://www.springframework.org/schema/util/spring-util.xsd"

    default-init-method="initialize"
    default-destroy-method="destroy">
    
    <!-- Attended restart unlock beans. -->

    <!-- Enumerate the system key strategy beans to unlock, typically just one. -->
    
    <util:list id="shibboleth.unlock-keys.KeyStrategies">
        <ref bean="shibboleth.DataSealerKeyStrategy" />
    </util:list>
    
    <!-- Enumerate credential bean refs and private key resources. -->
    
    <util:list id="shibboleth.unlock-keys.Credentials">
        <ref bean="shibboleth.DefaultSigningCredential" />
    </util:list>
    
    <util:list id="shibboleth.unlock-keys.PrivateKeys">
		<bean class="org.springframework.core.io.FileSystemResource"
            c:_0="%{idp.signing.key}"/>
    </util:list>

    <bean id="shibboleth.DefaultSigningCredential"
        class="net.shibboleth.idp.profile.spring.factory.BasicX509CredentialFactoryBean"
        p:certificateResource="%{idp.signing.cert}"
        p:entityId="%{idp.entityID}" />
    
</beans>

...