Migration Guide 3.1

Table of Contents

• Automatic update tool
• OIDC
  • Session cookie is encrypted by default
  • ID token audience is verified by default
• SmallRye GraphQL
• Mockito

Automatic update tool

Quarkus 3.0 introduced an update tool that can help you update your projects to new versions of Quarkus.

We recommend you to use this tool for all upgrades, even minor ones.

It doesn’t handle everything but it should handle most of the tedious work.

This update tool can be used for both Quarkus applications and Quarkus extensions, be they Maven or Gradle projects using Java or Kotlin.

If you are using the Quarkus CLI - which is recommended - upgrade it to the latest first and then run:

quarkus update --stream=3.1

If you are not using the CLI and using Maven, use the Quarkus Maven plugin to update your projects:

./mvnw io.quarkus.platform:quarkus-maven-plugin:3.1.0.Final:update -N -Dstream=3.1

If you are not using the CLI and using Gradle, use the Quarkus Gradle plugin to do so:

./gradlew -PquarkusPluginVersion=3.1.0.Final quarkusUpdate --stream=3.1

For more information, consult the dedicated guide.

OIDC

Session cookie is encrypted by default

OIDC session cookie which is created after an OIDC authorization code flow has completed, will now be encrypted by default. Users are not expected to notice it in most cases.

However, only if either mTLS or private_key_jwt (OIDC client private key is used to sign a JWT token) authentication methods are used between Quarkus and OpenId Connect Provider, then an in-memory encryption key will be generated, which might cause some pods in the application dealing with a very large number of requests failing to decrypt the session cookie, because a given pod trying to decrypt it might not be the one which encrypted it.

In such cases one can register an encryption secret which should be 32 characters long, for example:

quarkus.oidc.token-state-manager.encryption-secret=eUk1p7UB3nFiXZGUXi0uph1Y9p34YhBU

Also note that an encrypted session cookie might exceed a 4096 bytes limit which will cause some browsers ignoring it. Try one of the following in such cases:

• Set quarkus.oidc.token-state-manager.split-tokens=true to have the ID, access and refresh tokens stored in separate cookies

• Set quarkus.oidc.token-state-manager.strategy=id-refresh-tokens if you do not need to use the access token as a source of roles or to request UserInfo or propagate it to the downstream services

• Register a custom quarkus.oidc.TokenStateManager CDI bean with the alternative priority set to 1. For example, custom quarkus.oidc.TokenStateManager can store all the tokens in a database and return a short DB pointer which Quarkus will use as a session cookie value.

If application users access the Quarkus application from within the trusted network, the session cookie encryption can be disabled:

quarkus.oidc.token-state-manager.encryption-required=false

ID token audience is verified by default

ID token aud (audience) claim will now be verified by default - it is expected to be equal to the configured quarkus.oidc.client-id property value as required by the OIDC specification.

You can override an expected ID token audience value with a quarkus.oidc.token.audience configuration property. You can set quarkus.oidc.token.audience to any - but do it only if you are dealing with a non-compliant OIDC provider which does not set an ID token aud claim.

SmallRye GraphQL

The SmallRye GraphQL extension has replaced its OpenTracing integration with OpenTelemetry integration. When using OpenTracing, the extension will no longer produce any spans for GraphQL operations. The quarkus.smallrye-graphql.tracing.enabled configuration property was removed, and spans will automatically be produced by the SmallRye GraphQL extension when the OpenTelemetry extension is present.

Mockito

The mockito-inline artifact is gone and, in most cases, you can just drop it from your pom.xml (and make sure you still have Mockito around).