OPReleaseNotes

3.2.1 (July 7, 2022)

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)

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 https://shibboleth.atlassian.net/wiki/spaces/IDPPLUGINS/pages/3001352203 for more information and examples.

Protocol Message Logging

OIDC/OAuth request and response messages are now logged via the PROTOCOL_MESSAGES.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 https://shibboleth.atlassian.net/browse/JOIDC-91 , 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 https://shibboleth.atlassian.net/wiki/spaces/IDPPLUGINS/pages/1376879077:

  • 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 https://shibboleth.atlassian.net/wiki/spaces/IDPPLUGINS/pages/2930409507 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 https://shibboleth.atlassian.net/wiki/spaces/IDPPLUGINS/pages/2930606124 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 https://shibboleth.atlassian.net/wiki/spaces/IDPPLUGINS/pages/2954756145 for more information. Related to this topic, also see https://shibboleth.atlassian.net/wiki/spaces/IDP4/pages/2958163969 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 https://shibboleth.atlassian.net/browse/JOIDC-52 , 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 https://shibboleth.atlassian.net/wiki/spaces/IDPPLUGINS/pages/2769420329/OIDC+legacy+token+in+compatibilities .

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 https://shibboleth.atlassian.net/wiki/spaces/IDPPLUGINS/pages/1376878984