7.0.0-migration-guide.md

Migration Guide from 6.x to 7.0.0

Dependencies

• replace any spring-addons starter with com.c4-soft.springaddons:spring-addons-starter-oidc
• replace any spring-addons test starter with com.c4-soft.springaddons:spring-addons-starter-oidc-test
• depending or your needs, add a dependency to
  • org.springframework.boot:spring-boot-starter-oauth2-resource-server for a REST API secured with access tokens
  • org.springframework.boot:spring-boot-starter-oauth2-client when configuring spring-cloud-gateway as BFF or exposing server-side rendered templates with frameworks like Thymeleaf
  • both of above when exposing publicly both a REST API secured with access tokens and other resources secured with sessions

Java Sources

Main Code

• rename SpringAddonsSecurityProperties to SpringAddonsOidcProperties. Also, if using nested properties, rename
  • getIssuers() to getOps()
  • getLocation() to getIss()
• replace SpringAddonsOAuth2ClientProperties with SpringAddonsOidcProperties::getClient (only SpringAddonsOidcProperties can be autowired)
• organize imports

Tests

• replace @AutoConfigureAddonsSecurity with @AutoConfigureAddonsMinimalSecurity
• replace @AutoConfigureAddonsWebSecurity with one of:
  • @AutoConfigureAddonsWebmvcSecurity
  • @AutoConfigureAddonsWefluxSecurity

Application Properties

This is probably the most tedious part of the migration. Hopefully, your IDE auto-completion and syntax highliting should help you there.

Common Configuration

• rename com.c4-soft.springaddons.security to com.c4-soft.springaddons.oidc
• rename issuers to ops which stands for OpenID Providers (com.c4-soft.springaddons.security.issuers becomes com.c4-soft.springaddons.oidc.ops)
• rename OpenID Providers location to iss: if set, the is used to add an "issuer" (tokens iss claim) validator to JWT decoder (com.c4-soft.springaddons.security.issuers[].location becomes com.c4-soft.springaddons.oidc.ops[].iss)
• renameaudience to aud: if set, the is used to add an "audience" (tokens aud claim) validator to JWT decoder (com.c4-soft.springaddons.security.issuers[].aud becomes com.c4-soft.springaddons.oidc.ops[].aud)

CORS configuration has also improved for both clients and resource servers: allowed-origin-patterns is used instead of allowed-origins. This is a requirement for using allow-credentials and is also more flexible: you can define ant patterns like https://*.my-domain.pf.

• rename allowed-origins to allowed-origin-patterns
• add allow-credentials and max-age if it makes sens (this are added configuration options)

Resource Servers

Resource server Security(Web)FilterChain can now be completely disabled with com.c4-soft.springaddons.security.resourceserver.enabled=false

Resource server specific properties are grouped in a new resourceserver subset:

• move cors down 1 level into resourceserver (com.c4-soft.springaddons.security.cors becomes com.c4-soft.springaddons.oidc.resourceserver.cors)
• move permit-all down one level to resourceserver (com.c4-soft.springaddons.security.permit-all becomes com.c4-soft.springaddons.oidc.resourceserver.permit-all)

Clients

• rename allowed-origins to allowed-origin-patterns (com.c4-soft.springaddons.security.client.cors.allowed-origins becomes com.c4-soft.springaddons.security.client.cors.allowed-origin-patterns)
• oauth2-logout is now a map indexed by client registraion ID instead of being an array. Use client-registration-id as key for each entry for the remaining properties. For instance:

          oauth2-logout:
            - client-registration-id: cognito-confidential-user
              uri: https://spring-addons.auth.us-west-2.amazoncognito.com/logout
              client-id-request-param: client_id
              post-logout-uri-request-param: logout_uri
            - client-registration-id: auth0-confidential-user
              uri: ${auth0-issuer}v2/logout
              client-id-request-param: client_id
              post-logout-uri-request-param: returnTo

becomes

          oauth2-logout:
            cognito-confidential-user:
              uri: https://spring-addons.auth.us-west-2.amazoncognito.com/logout
              client-id-request-param: client_id
              post-logout-uri-request-param: logout_uri
            auth0-confidential-user:
              uri: ${auth0-issuer}v2/logout
              client-id-request-param: client_id
              post-logout-uri-request-param: returnTo

where cognito and auth0 are the values of spring.security.oauth2.client.registration.cognito-confidential-user.provider and spring.security.oauth2.client.registration.auth0-confidential-user.provider