OPReleaseNotes

4.2.0 (October 23, 2024)

This is a feature release accompanying a new version of the OIDC commons library along with some general improvements and bug fixes. It is compatible with Shibboleth IdP 5.0 or later.

This release addresses security advisory (https://shibboleth.net/community/advisories/secadv_20241023.txt) related to a pair of race conditions in the authorization/authentication request processing.

Getting issues...

Request object handling

In addition to the OIDC-specified request object handling, the plugin now also supports OAuth2 JWT-secured authorization requests (JAR). This logic is applied to the non-OIDC authorization requests to the authorization-endpoint and to all pushed authorization requests (see PAR below).

PAR endpoint

The plugin now supports OAuth2 Pushed Authorization Requests (PAR): a method for clients to push the payload of an OAuth 2.0 authorization request to AS/OP via a direct (API) request. The server provides them with a request URI that is used as a reference to the data in a subsequent call to the authorization endpoint. We provide two methods for the request URI generation: the default method encrypts the state inside the value. The other method exploits a configurable storage service: this way the values remain shorter as the URI value only contains a reference to the storage record.

The full profile documentation is available at OPPushedAuthorization .

DPoP access tokens

In addition to the bearer tokens, the plugin now supports OAuth2 demonstrating proof of possession (DPoP) specification. As described in the RFC: “DPoP can be used to sender-constrain access tokens regardless of the client authentication method employed, but DPoP itself is not used for client authentication. DPoP can also be used to sender-constrain refresh tokens issued to public clients (those without authentication credentials associated with the client_id).”.

The DPoP tokens are now automatically issued to the clients that use valid DPoP proof JWTs in the token request. Several profile configuration options are available for enforcing and customizing the default logic.

Custom request/response message handling

The plugin now offers additional hooks for customizing the request message parsing and the creation of the successful and error response objects. The OPMessageHandling page describes the current features. Similarly to the SAML profiles, the new messageHandler profile configuration option is now available for OAuth2/OIDC profiles too.

It should be noted that the position of the call to outbound interceptor flows was changed to occur right after the creation of the response message: the logic is now compliant with the one used in the SAML profiles. Previously wired outbound interceptor flows should thus be verified to be interoperable.

New configuration properties

  • idp.oauth2.par.StorageService: the storage service to be used for storing pushed authorization requests (defaults to in-memory)

  • idp.oauth2.par.serializationStrategies: a bean containing a map of serialization strategies for the pushed authorization requests (defaults to shibboleth.oidc.DefaultPushedAuthorizationRequestUriSerializationStrategies)

  • idp.oauth2.par.requestUriType: the pushed authorization request URI value type (default to empty, referring to the method encrypting the state inside the opaque value)

  • idp.oauth2.par.requestUriLifetime: the pushed authorization request URI lifetime (defaults to 1 minute)

  • idp.oauth2.dpop.replayCacheLifetime: the replay cache record lifetime if the DPoP proof doesn’t contain expiration time (defaults to 5 minutes)

  • idp.oauth2.dpop.maxReplayCacheLifetime: upper bound of the DPoP proof lifetime in the replay cache (defaults to 5 minutes)

  • idp.oauth2.dpop.proofAlgorithms: the algorithms advertised to be compatible for DPoP proofs, defaults to RS256,RS384,RS512,PS256,PS384,PS512,ES256,ES384,ES512

  • idp.oauth2.par.useOnlyRequestObject: the bean for condition to use only values from request objects within PAR-endpoint (defaults to JAR-logic, i.e. if request object is specified, the values are only fetched from there)

  • idp.oauth2.authorize.useOnlyRequestObject: the bean for condition to use only values from request objects within authorisation-endpoint

  • idp.oidc.strictScopeValidation: a flag to use strict scope validation, i.e. a request for unallowed scope leads to an error (defaults to false)

  • idp.oidc.requestParser.*: request-message specific custom parsers as described in OPMessageHandling.

New configuration beans

  • shibboleth.oidc.MetadataPolicyRedirectUriValidator: Abstract bean can be used for wiring metadata policy -based custom validators

  • shibboleth.oauth2.par.AllowedScopeStrategy: Allowed scope lookup strategy for PAR

  • shibboleth.oidc.par.SignedRequestObjectClaimsValidation: Chain of validators for request object in the PAR endpoint

  • shibboleth.oidc.DefaultOAuth2ProtectedApiMappedErrors: New error-mapping bean to be used with the OAuth2 protected endpoints, see OPMessageHandling | Error handling

4.1.0 (April 11, 2024)

This is a feature release accompanying a new version of the OIDC commons library along with some general improvements and minor bug fixes. It is compatible with Shibboleth IdP 5.0 or later.

Getting issues...

General Note

There is a bug in the Nimbus library we use for much of the functionality in the OP that impacts the way we set and manage cookies within the IdP. This bug manifests in a fairly complex way and was exposed by a fix in V5.1.3 that causes the behaviour to be worse there than before, but there are limitations even on older versions. For versions older than 4.2.0, the following should be taken into account if you run without HTML Local Storage enabled for tracking client sessions:

V5.1.3+

On the latest version, the use of OpenID authorizaton responses that are issued via HTTP Redirect (the most common way) does not allow the IdP’s session cookie(s) to be set at all in affected cases. It is possible to work around this issue to an extent, but we cannot promise that the use of SAML won’t be impacted in certain cases. If you want to attempt this, you need to set idp.cookie.bufferingCondition = shibboleth.Conditions.FALSE in your properties.

The caveat is that you cannot attach a SameSite attribute to your cookies regardless. That’s simply a consequence of the bug, and there is no workaround.

V5.1.2 and Older

In earlier versions, cookies work in general but SameSite will not be added to the cookies if configured to do so. That issue applied to both SAML and OpenID, and was the reason for the change in V5.1.3 that exposed the Nimbus bug.

OIDC Logout

The OP plugin now includes the new OPLogout profile. The new OIDC.Logout profile implements the RP-initiated logout and logout propagation via both front- and back-channel. The profile documentation has a section for slight modifications needed for two logout templates if non-default versions prior to IdP 5.1 are used.

Acknowledgement to DAASI: their OIDC back-channel logout propagation plugin was used as a basis for this implementation.

Refresh token extensions

We have refactored the refresh token encoding and decoding code and it’s now fully customisable. This advanced feature is provided via two new properties idp.oauth2.refreshToken.serializationStrategies and idp.oauth2.refreshToken.deserializers: those can be used for injecting any custom beans to encode and decode refresh token values, and thus provide support for for new refresh token types. We demonstrate this new functionality by supporting a new JWT refresh token type.

Policies for dynamic registration and unregistered clients

The https://shibboleth.atlassian.net/wiki/x/AoC_rw used in dynamic client registration and for unregistered clients can now be extended with custom operators. A new metadata policy operator bean provides flexible means for validating incoming requests via a fully customisable set of beans. See OPMetadataPolicies | Custom operators 4.1 for details.

Metadata-driven claim naming

The RP-specific claim names can now be configured in the metadata-driven fashion. See OPAttributeResolution | SAML metadata driven claim name for more details.

Identifier configuration

The identifier generation configuration has been harmonised: a new configuration property (idp.oidc.xmlSafeIdentifiers) can be used to control whether to generate XML ID safe identifiers, which was previously always the case. If the property is set to false (default is true), the identifiers (such as JWT token IDs) won’t contain the _-prefix anymore and the OP can, for instance, create UUIDv4 compatible identifiers if desired.

Message logging improvements

The request and response messages containing JSON structures are now pretty-printed on TRACE level. Also the JWT token payloads produced by the OP plugin are pretty-printed to the protocol message logs on that level.

New configuration properties

  • idp.oauth2.refreshToken.type: a format of refresh token. Supported values are “JWT” or nothing/empty/null, implying opaque tokens.

  • idp.oauth2.refreshToken.serializationStrategies: a custom bean reference containing the map of refresh token serialisation strategies, key refers to the refresh token type.

  • idp.oauth2.refreshToken.deserializers: a custom bean reference containing the list of refresh token deserialisers.

  • idp.oauth2.responseModes: a comma-separated list of allowed response modes. Empty by default which refers to no restrictions.

  • idp.oidc.xmlSafeIdentifiers: a flag to signal if XML ID safe identifiers should be used when generating identifiers.

  • idp.oidc.logout.encryptionOptional: a flag to automatically disable back-channel logout token encryption if the relying party does not possess a suitable key.

  • idp.oidc.logout.preferFrontChannel: a flag to prefer front-channel logout propagation if both front and back -channel URIs are defined in the RP metadata

  • idp.oidc.logout.frontChannelSuccess: a flag to consider front-channel logout propagation success in the propagation UI (defaults to false).

  • idp.oidc.logout.revokeTokens: a flag to revoke the access and refresh tokens related to the session (defaults to true). Note that the OAUTH2.Revocation profile must be enabled for the RP.

  • idp.oidc.logout.requireIdTokenHint: a flag to require the use of id_token_hint parameter in the RP-initiated logout request.

  • idp.oidc.logout.logoutHintMatchingStrategy: a custom bean reference to bi-predicate for matching the logout_hint parameter with an SPSession.

New configuration beans

  • shibboleth.oidc.RevokeConsentPredicate: A predicate to signal if prior consent should be revoked.

  • shibboleth.oidc.UnregisteredClientPolicyValidator: A validator bean used for validating the configured policy for unregistered clients.

  • shibboleth.oidc.UnregisteredClientPolicyEnforcer: An enforcer bean used for enforcing policy for unregistered clients.

  • shibboleth.oidc.dynreg.ClientIDGenerationStrategy: An identifier generation strategy used for generating client IDs in dynamic client registration.

  • shibboleth.oidc.dynreg.ClientSecretGenerationStrategy: An identifier generation strategy used for generating client secrets in dynamic client registration.

  • shibboleth.oidc.dynreg.MetadataPolicyValidator: A validator bean used for validating the configured metadata policy in dynamic client registration.

  • shibboleth.oidc.dynreg.MetadataPolicyEnforcer: An enforcer bean used for enforcing metadata policy in dynamic client registration.

4.0.0 (September 14, 2023)

This is a feature release accompanying a new version of the OIDC commons library along with some general improvements and minor bug fixes. It is the first release that requires Shibboleth IdP 5.0.0 or later. Previous versions of the plugin are not compatible with IdP 5.

Getting issues...

Policies for unregistered clients

In addition to the request validation against client metadata (JSON or SAML), the plugin now supports validation against a policy for unregistered clients. A policy is used for validating the incoming client ID, scope, redirection URI, and response type parameters or their subsets, depending on the endpoint where the validation is done. If the request is compliant with the policy, the unverified profile configuration is applied. The validation against policy is only performed with the unverified profile configurations (see shibboleth.UnverifiedRelyingParty in RelyingPartyConfiguration ). The verified profile configurations (shibboleth.DefaultRelyingParty and shibboleth.RelyingPartyOverrides) still require the registered client metadata in the same way as before.

Elimination of the custom response header filter

The previously existing method for configuring custom HTTP headers for the plugin’s endpoint has now been removed. Now the plugin automatically extends the IdP’s known set of URL prefixes to apply its response headers to by adding the /profile/oidc/ and /profile/oauth2/ prefixes to the built-in set.

See OPCustomFilterRegistration .

New configuration properties

  • idp.oidc.DefaultUnregisteredPolicyFile - it defaults to %{idp.home}/conf/oidc-unregistered-client-policy.json. An example file is included in the distribution.

Removed configuration properties

  • idp.oidc.ResponseHeaderFilter: It was related to the now removed custom response header filter

  • idp.oidc.refreshToken.defaultLifetime: already deprecated in version 3.3.0, use idp.oidc.refreshToken.defaultTimeout instead

New configuration beans

  • shibboleth.oidc.Conditions.MetadataValueEquals: a utility bean to be used for instance with activation conditions to match if a specific metadata claim contains a specific value

  • shibboleth.oidc.PlainRequestObjectClaimsValidation: If defined, it will be used for the validation of unsigned request objects

  • shibboleth.oidc.SignedRequestObjectClaimsValidation: If defined, it will be used for the validation of signed request objects

3.4.0 (May 15, 2023)

Getting issues...

This is a feature release accompanying new version of the OIDC commons library along with some general improvements and minor bug fixes. It is the first release designed to co-exist with the new OIDC RP authentication plugin.

This release addresses security advisory (https://shibboleth.net/community/advisories/secadv_20230512.txt) related to a pair of race conditions in the client authentication and dynamic registration features.

This release requires Shibboleth IdP 4.3.0 or later and the OIDCConfig plugin. Please note that the version 1.0.1 was released on May 16, 2023 to fix issues (see first and second) related to default OIDC.SSO and OAUTH2.Token configurations.

Security Configuration

The old security configuration mechanism has been replaced with the new security configuration style, designed to be compatible with the new OIDC RP authentication plugin. Any custom security configuration dating to previous versions will require modifications, but this is expected to have been rare.

The underlying Java class for the shibboleth.oidc.DefaultSecurityConfiguration parent bean has changed, and thus any custom beans extending that need to be adapted. The previous class is no longer compatible with the plugin.

The new class bean has the following properties:

  • jwtSignatureSigningConfiguration (related property idp.oidc.signing.config, NOTE, any previously configured bean needs to be adapted)

  • jwtEncryptionConfiguration (related property idp.oidc.encryption.config, NOTE, any previously configured bean needs to be adapted)

  • jwtDecryptionConfiguration (related new property idp.oidc.decryption.config)

  • jwtSignatureValidationConfiguration (related new property idp.oidc.validation.config)

The following configuration parameters (and related properties) are no longer supported:

New Supported Algorithms

The set of supported algorithms has been extended to include:

  • PS256, PS384 and PS512 signature algorithms

  • RSA-OAEP-384 and RSA-OAEP-512 encryption algorithms

  • ECDH-ES+A128KW, ECDH-ES+A192KW and ECDH-ES+A256KW encryption algorithms

Refresh Tokens

The OPToken profile now contains new profile configuration options to control the expiration of both single and chains of refresh tokens. We also deprecated the previously existing option and property related to the expiration of a single token.

NOTE: The default lifetime for the chain (refreshTokenChainLifetime -option and idp.oidc.refreshToken.defaultChainLifetime -property) is 2 hours. This new option may need to be adjusted to keep any longer-lived refresh tokens valid.

Refresh tokens can now be issued for OAuth2 (non-OIDC) clients via the authorization code grant, if the necessary profile configuration option is set. The OIDC clients still need to use offline_access scope, as before.

A new profile configuration option (issueIdTokenViaRefreshToken) now exists for controlling ID token issuance when the refresh token grant is used and defaults to true.

Request Objects

The OPAuthorization profile now contains new profile configuration options to control the use of request objects.

JWT-based Client Authentication Improvement

The audience validation for JWTs used in client authentication has been modified. The token, introspection and revocation endpoints now accept the OP issuer value, the requested endpoint URL and the token endpoint URL values as an audience. In the older versions, only the requested endpoint URL was accepted.

The validation key handling has also been improved: if the header of an incoming JWT contains a key reference (the kid claim), it must now match to a trusted key.

3.3.0 (November 29, 2022)

Getting issues...

This is a feature release that adds support for OAuth2 (non-OIDC) authorization requests along with some general improvements and minor bug fixes.

The OIDC.SSO profile can now be configured to also accept plain OAuth2 authorization requests. Before this release, the RPs were required to use OIDC authentication requests. It remains the default behaviour, but it can be configured via idp.oauth2.requireAuthenticationRequestPredicate property.

3.2.1 (July 7, 2022)

Getting issues...

This is a patch release, primarily addressing a bug related to the use of revocation endpoint with JWT access tokens. The patch is very important for deployments that have enabled the use of JWT access tokens with revocation and have the revocation method set to “TOKEN” (another new feature introduced in V3.2.0).

3.2.0 (June 30, 2022)

Getting issues...