OPReleaseNotes

4.2.0 (Not released yet)

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.

Getting issues...

PAR endpoint

 

DPoP access tokens

 

Custom request/response message handling

 

New configuration properties

 

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...

OIDC Logout

The OP plugin now includes the new https://shibboleth.atlassian.net/wiki/spaces/IDPPLUGINS/pages/3466559581 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 https://shibboleth.atlassian.net/wiki/spaces/IDPPLUGINS/pages/2948497410/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 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 ). 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 .

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 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:

  • requestObjectDecryptionConfiguration (property idp.oidc.rodecrypt.config is ignored)

    • use jwtDecryptionConfiguration with

  • requestObjectSignatureValidationConfiguration (property idp.oidc.rovalid.config is ignored)

    • use jwtSignatureValidationConfiguration with

  • tokenEndpointJwtSignatureValidationConfiguration (property idp.oidc.tevalid.config is ignored)

    • use jwtSignatureValidationConfiguration with , and

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 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 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...

This is a feature release that adds some new capabilities along with a bug fix regarding the use of SAML metadata for OIDC RPs.

JWT Access Tokens

As with the client_credentials grant since version 3.1, all access tokens can now be configured to use the JWT format. Both authorization and token endpoints now support the “resource” parameter extension from RFC8707 in order to influence a JWT access token’s audience.

Note that when combining the use of this feature with standard OIDC, access token encryption under a resource server’s key is generally impossible since the OP must be able to consume the token when presented by the RP. This has privacy implications when including custom claims about the subject in the token.

Token Revocation Enhancements

The revocation endpoint can now be configured to either revoke a single token at a time or the entite chain of tokens issued via a given code grant. Previously, it always revoked the full chain, which remains the default setting. In addition to the revocation method, the full chain revocation lifetime can now be configured on the revocation profile configuration.

The token profile configuration also now contains a flag fo enforce refresh token rotation; when enabled, the refresh token used for requesting new access and refresh tokens is revoked after a single use. If an already revoked refresh token is used, the full chain corresponding to that token is revoked. This aligns the behavior to suggested practice published in Internet Drafts.

Authorizing Requested Scopes

The set of allowed scope values an RP can request can now be fully customised, for instance depending on the authenticated subject's attributes. See for more information and examples.

Protocol Message Logging

OIDC/OAuth request and response messages are now logged via the PROTOCOL_MESSAGE.OAUTH2 category (a sub-category of the one used for SAML, which we will likely migrate to a subcategory in a future IdP release). At DEBUG level, it logs the contents of the Java message objects, without revealing the value of client secrets or HTTP Basic-Auth headers. At TRACE level, it logs the messages in raw form, including both HTTP headers and message body contents. The TRACE level matches the logging that was previously done by the decoder/encoder class loggers on DEBUG level.

ID Token and Token-encoded Claims Set Manipulation

The profile configurations now contain hooks for manipulating (i.e. modifying, adding or removing) claims in ID Tokens and in the claims sets that are encoded inside opaque authorization codes and access/refresh tokens. This is an advanced feature that is meant to be used with extra care: the deployer is responsible for keeping the claims sets syntactically correct and not violating specifications.

3.1.2 (May 17, 2022)

This is a patch release, addressing issues related to OIDC claim requests and JWT client authentication to introspection and revocation endpoints.

3.1.1 (April 21, 2022)

This is a patch release, primarily addressing , which prevented public clients from accessing token endpoint.

3.1.0 (April 15, 2022)

This is a significant feature release that adds a number of new capabilities along with various fixes. It is meant to be compatible with the V3.0 releases at a feature/configuration level, but there are few changes that may impact a very small number of deployers.

API Changes and Future Policy

Because of the relative immaturity of the code base, some classes are still moving around. Because we do not expect that most deployers should have a need to directly interact with these classes at a Java level, we have made some changes that contradict our usual API versioning policy; in particular the profile configuration classes were migrated out of an OP package and into the OIDCCommons library for reuse, and some advanced “context” classes used to store information during the handling of requests have been moved as well.

As a general statement to prevent confusion in the future, please treat anything in the OP itself as an implementation class, despite the presence of a separate API module. That is, any classes in packages under “net.shibboleth.idp.plugin.oidc.op” should be viewed as subject to change and not formally in the API, though we try and limit the changes in the idp-oidc-extension-api module.

Classes in the OIDCCommons API modules (the ones ending in -api) that are packaged under “net.shibboleth.oidc” will be maintained in accordance with our versioning policy, so when classes appear there, they should be in more stable form.

Client Registration Enhancements

A number of major enhancements have been made to :

  • Access tokens for use in controlling client registration, which can be issued via OP operations staff or directly to client application owners subject to policy.

  • Metadata policy statements that can limit what gets registered, including on a per-access token basis.

  • An endpoint to query and delete registrations.

Client Authentication Enhancements

OAuth/OIDC client authentication has been redesigned in this release to support the IdP’s login flow machinery, and a new (default) login flow called OAuth2Client has been created, modeled on the Password login flow built-in to the IdP. Because it is a separate flow and relies on separate configuration properties and beans, it supports operation in parallel with the standard Password flow while sharing much of its capabilities, as well as allowing for features that are applicable only to OAuth clients, such as client secret validation and use of signed JWT objects.

See for more information.

Client Credentials Grant

The Token endpoint has been enhanced to support additional, OAuth-specific use cases, starting with the “client_credentials” grant type that supports direct requests for access tokens by OAuth clients rather than via a browser. Support for this grant type includes the new option to issue access tokens in JWT format (including optional encryption) as well as the original opaque format.

As part of this new work, the configuration for the Token profile has been split off from the original OIDC.SSO profile bean and a second profile configuration added for TokenAudience to control the behavior of the system when issuing tokens intended for use with particular resource servers. For compatibility, the system will operate in the same fashion as before by default, supporting only the authorization_code and refresh_token grants in an OIDC-specific fashion. The new beans can be added to the RelyingPartyConfiguration as desired to enable and control the new features.

See for more information.

Please note that presently, the only “pure” OAuth use case supported is the “client_credentials” grant. Support for OAuth-only use of the code grant and JWT access tokens for “4 legged OAuth” use cases is a future development task.

Unverified Use of OAuth Features

The aforementioned “client_credentials” grant and the token introspection and revocation features have been enhanced and tested for use with authenticated clients lacking explicit client metadata, allowing enablement (if desired) via the “UnverifiedRelyingParty” configuration. Support for the OIDC profile does not yet support this, but should in the future.

Custom Filter Registration

A configurable Servlet Filter can now be registered without a need to edit the web.xml file. This is useful to support custom HTTP request or response handling. See for more information. Related to this topic, also see for information about a new IdP 4.2 feature.

3.0.4 (January 31, 2022)

1 issue

This is a patch release addressing security advisory related to (https://shibboleth.net/community/advisories/secadv_20220131.txt) unchecked use of the request_uri feature.

If you are supporting RPs that issue requests by reference to a hosted JWT object, you will need to add the exact URLs to those objects into the client’s metadata to validate the locations. This upgrade will block unregistered values. Note that we did not support dynamic client registration of those URLs and have no plans to do so given the complexity of validating them, but we may add a hook for supporting this if there is demand to do so in the future.

3.0.3 (January 3, 2022)

3 issues

This is a patch release, primarily addressing security advisory (https://shibboleth.net/community/advisories/secadv_20220103.txt) related to incomplete incoming JWT validation.

If you are relying on JWT client authentication, this fix may result in failure to validate any non-compliant tokens that do not contain the proper claims and meet other security requirements defined by the specifications.

3.0.2 (September 1, 2021)

3 issues

This is a patch release, primarily addressing , which prevented the use of authorization codes and access/refresh tokens produced by the earlier versions of the extension. Some incompatibilities still remain, they’re highlighted in .

3.0.1 (May 25, 2021)

6 issues

This is a patch release addressing some bugs and updating some of the exploited 3rd party libraries.

This version is a certified OpenID Provider.

3.0.0 (March 23, 2021)

22 issues

This is the first version which is compatible with the concept of plugins introduced by Shibboleth IdP V4.1. The older versions of the OIDC extensions are no longer supported.

For installation / upgrading, see