Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

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.

Localtabgroup

Localtab-live
titleV4.0

To get this working, the flow has to be defined and enabled in conf/admin/general-admin.xml, and some Spring beans defined to describe to the flow what it needs to unlock.

Enable the Flow

The following is added to (or uncommented in) the shibboleth.AvailableAdminFlows list bean:

Code Block
languagexml
titleAdded 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.

Localtab-live
activetrue
titleV4.1+

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.

Configuring the Flow

The system reserves the file conf/admin/unlock-keys.xml for defining the beans necessary for the flow to run.

...

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

FDXML

Localtabgroup

Localtab-live
activetrue
titleBeans

NameTypeDescription

shibboleth.unlock-keys.KeyStrategies

Collection<DataSealerKeyStrategy>Enumerates the key strategy beans used to supply secret key(s) to the IdP that should be unlocked by the flow

shibboleth.unlock-keys.Credentials

Collection<MutableCredential>Enumerates the public key credentials that need to have an unlocked private key injected from the shibboleth.unlock-keys.PrivateKeys bean

shibboleth.unlock-keys.PrivateKeys

Collection<Resource>Enumerates the resources containing private keys to unlock and inject into the credentials from the shibboleth.unlock-keys.Credentials bean
                                                                  

Localtab-live
titleProperties (V4.1+)

The general properties configuring this flow via admin/admin.properties are:

NameDefaultDescription
idp.unlock-keys.loggingUnlockKeysAudit log identifier for flow
idp.unlock-keys.accessPolicyAccessDeniedName of access control policy for request authorization
idp.unlock-keys.authenticatedtrueWhether authentication should be performed prior to access control evaluation
idp.unlock-keys.nonBrowserSupportedfalseWhether the flow should allow for non-browser clients during authentication
idp.unlock-keys.resolveAttributesfalseWhether attributes should be resolved prior to access control evaluation

Localtab

id
-live
titleFlow Descriptor XML (V4.1+)

To replace the internally defined flow descriptor bean, the following XML is required:

Code Block
languagexml
<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>

In older versions and upgraded systems, this list is defined in conf/admin/general-admin.xml. In V4.1+, no default version of the list is provided and it may simply be placed in conf/global.xml if needed.

Example

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

...