OPSecurity

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

Security-related properties in conf/oidc.properties:

Name / Default

Type

Description

Name / Default

Type

Description

idp.signing.oidc.rs.key

JWK file pathname

JWK RSA signing keypair

idp.signing.oidc.es.key

JWK file pathname

JWK EC signing keypair

idp.signing.oidc.rsa.enc.key

JWK file pathname

JWK RSA decryption keypair

idp.oidc.signing.config

shibboleth.oidc.SigningConfiguration

Bean ID

Allows override of default signing configuration

idp.oidc.encryption.config

shibboleth.oidc.EncryptionConfiguration

Bean ID

Allows override of default encryption configuration

idp.oidc.decryption.config

shibboleth.oidc.DecryptionConfiguration

Bean ID

Allows override of default decryption configuration

idp.oidc.validation.config

shibboleth.oidc.SignatureValidationConfiguration

Bean ID

Allows override of default signature validation configuration

Beans defined in conf/oidc-credentials.xml or internally for use in conf/relying-party.xml:

Name / Type

Description

Name / Type

Description

shibboleth.JWKCredential

BasicJWKCredentialFactoryBean

Spring factory bean for easy definition of JWK-formatted credentials

shibboleth.oidc.DefaultRSSigningCredential

Credential

Default RSA signing keypair used with OIDC

shibboleth.oidc.DefaultESSigningCredential

Credential

Default EC signing keypair used with OIDC

shibboleth.oidc.DefaultRSAEncryptionCredential

Credential

Default RSA decryption keypair used with OIDC

shibboleth.oidc.SigningCredentials

List<Credential>

List of signing keys available for use with OIDC

shibboleth.oidc.EncryptionCredentials

List<Credential>

List of encryption keys available for use in decryption with OIDC

shibboleth.oidc.SigningCredentialsToPublish

List<Credential>

List of signing keys to publish to RPs with OIDC

shibboleth.oidc.EncryptionCredentialsToPublish

List<Credential>

List of encryption keys to publish to RPs with OIDC

shibboleth.oidc.DefaultSecurityConfiguration

JSONSecurityConfiguration

Default security configuration used by all OIDC profile beans

shibboleth.oidc.SigningConfiguration

BasicSignatureSigningConfiguration

Default signing behavior for OIDC profiles, auto-wires default algorithms and signing keys

shibboleth.oidc.SignatureValidationConfiguration

BasicSignatureValidationConfiguration

Default signature validation behavior for validating JWTs

shibboleth.oidc.EncryptionConfiguration

BasicEncryptionConfiguration

Default encryption behavior for OIDC profiles, auto-wires default algorithms

shibboleth.oidc.DecryptionConfiguration

BasicDecryptionConfiguration

Default decryption behavior for OIDC profiles

Â