OPSecurity
- Scott Cantor
- Rod Widdowson
Overview
The "basics" of configuring security are covered under the initial setup tab, with the generation of JWK keys to use and the import of conf/oidc-credentials.xml into conf/credentials.xml to auto-configure the new keys based on a set of properties.
The imported file configures the individual RSA and EC signing keys and an RSA decryption key in JWK format and creates a set of default beans that expose these keys to the rest of the system. The main feature of the XML file that would require editing is to support splitting the keys available to the OP from the keys actually published by the OP's discovery support. Much like in SAML, this allows keys to be rotated by publishing them ahead of use or supporting them ahead of publishing them, for signing and encryption respectively.
Note that while the JWK format includes certain required JSON fields such as a cryptographic algorithm to use with the credential, this is a broken design that Shibboleth ignores; the key is the key but the algorithm(s) used depend on other factors at runtime and there are usually multiple algorithms that can be used with a particular key.
Note that in most cases you MAY utilize the same keys for SAML and OIDC if you choose, and even mix and match the formats. The various list beans are what the underlying system runtime uses to identify keys, so it's possible to adjust those lists in the two XML files to rely on a single set of credential beans.
We don't particularly recommend this and default to separating them simply because the operational aspects of the two protocols are so different and the implications of a compromise so different that separating them is the safer course.
Configuration
The three properties (in conf/oidc.properties) that load the default keys and their default values are:
idp.signing.oidc.rs.key - %{idp.home}/credentials/idp-signing-rs.jwk
idp.signing.oidc.es.key -%{idp.home}/credentials/idp-signing-es.jwk
idp.signing.oidc.rsa.enc.key - %{idp.home}/credentials/idp-encryption-rsa.jwk
You will find these properties used in conf/oidc-credentials.xml along with additional beans that reference these credentials in the various lists and additional commented beans that allow the use/publish distinction. In most cases you won't need to touch this very much.
The truly essential beans are:
shibboleth.oidc.SigningCredentials
shibboleth.oidc.EncryptionCredentials
These are lists that enumerate the actual keys the system will try to use at runtime.
In turn, you MAY define lists:
shibboleth.oidc.EncryptionCredentialsToPublish
shibboleth.oidc.SigningCredentialsToPublish
These control what discovery requests to the OP will see.
Advanced Examples
At a very high level there's a lot of overlap between the way security behavior can be customized for OIDC and the original IdP documentation on SecurityConfiguration. However because the algorithms used are somewhat different, there are different underlying default beans used to control the behavior of the OIDC profile flows.
As an advanced example, the documentation and built-in defaults expect the EC key to be a 256-bit key that supports only a subset of possible signing algorithms. If you had a RP that required the ES512 algorith, a P-521 key would be needed, which you would need to generate and define in conf/oidc-credentials.xml:
conf/oidc-credentials.xml
<bean id="shibboleth.oidc.SpecialSigningCredential" parent="shibboleth.JWKCredential"
p:resource="%{idp.home}/credentials/my-idp-signing-ec521.jwk" />Then you would need to define a new configuration bean and apply it to a RP profile in conf/relying-party.xml:
conf/relying-party.xml
<bean id="SpecialSecurityConfig" parent="shibboleth.oidc.DefaultSecurityConfiguration">
<property name="signatureSigningConfiguration">
<bean parent="shibboleth.oidc.SigningConfiguration"
p:signingCredentials-ref="shibboleth.oidc.SpecialSigningCredential">
<property name="signatureAlgorithms">
<list>
<util:constant static-field="net.shibboleth.oidc.jwa.support.SignatureConstants.ALGO_ID_SIGNATURE_ES_512" />
</list>
</property>
</bean>
</property>
</bean>
<bean parent="RelyingPartyByName" c:relyingPartyIds="https://needy.rp.example.org">
<property name="profileConfigurations">
<list>
<bean parent="OIDC.SSO" p:securityConfiguration-ref="SpecialSecurityConfig" />
</list>
</property>
</bean>Reference
Â