diff --git a/.fernignore b/.fernignore index 819c62a7..da1783c7 100644 --- a/.fernignore +++ b/.fernignore @@ -6,7 +6,7 @@ README.md # Examples and Migration Guide from auth0-real EXAMPLES.md v3_MIGRATION_GUIDE.md -MIGRATION_GUIDE.md +v4_MIGRATION_GUIDE.md LICENSE CHANGELOG.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 0c058de9..b549e4f9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -143,7 +143,7 @@ ManagementApi client = ManagementApi ``` **Note**: The Authentication API remains supported, with deprecated APIs removed. -A complete migration guide is available at [MIGRATION_GUIDE](MIGRATION_GUIDE.md). +A complete migration guide is available at [MIGRATION_GUIDE](v3_MIGRATION_GUIDE). ## [3.0.0-beta.0](https://github.com/auth0/auth0-java/tree/3.0.0-beta.0) (2025-12-18) [Full Changelog](https://github.com/auth0/auth0-java/compare/2.27.0...3.0.0-beta.0) @@ -157,7 +157,7 @@ A complete migration guide is available at [MIGRATION_GUIDE](MIGRATION_GUIDE.md) - Nullability annotations to POJO classes - Fully compatible **Authentication API client** — no breaking changes -- [Migration guide](MIGRATION_GUIDE) available for upgrading from v2.x +- [Migration guide](v3_MIGRATION_GUIDE) available for upgrading from v2.x ## [2.27.0](https://github.com/auth0/auth0-java/tree/2.27.0) (2025-12-18) diff --git a/README.md b/README.md index 8f24453e..5b217127 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,8 @@ ## Documentation - [Reference](./reference.md) - code samples for Management APIs. - [Examples](./EXAMPLES.md) - code samples for common auth0-java scenarios. -- [Migration Guide](./MIGRATION_GUIDE.md) - guidance for updating your application to use version 3 of auth0-java. +- [v4 Migration Guide](./v4_MIGRATION_GUIDE.md) - guidance for updating your application from version 3 to version 4 of auth0-java. +- [v3 Migration Guide](./v3_MIGRATION_GUIDE.md) - guidance for updating your application from version 2 to version 3 of auth0-java. - [Docs site](https://www.auth0.com/docs) - explore our docs site and learn more about Auth0. ## Getting Started diff --git a/MIGRATION_GUIDE.md b/v3_MIGRATION_GUIDE.md similarity index 100% rename from MIGRATION_GUIDE.md rename to v3_MIGRATION_GUIDE.md diff --git a/v4_MIGRATION_GUIDE.md b/v4_MIGRATION_GUIDE.md new file mode 100644 index 00000000..084b0a78 --- /dev/null +++ b/v4_MIGRATION_GUIDE.md @@ -0,0 +1,165 @@ +# Migrating from v3 to v4 + +`v4` is a compatible evolution of `v3`. The Authentication API is unchanged, and the Management API keeps the same client structure, builder patterns, and pagination introduced in `v3`. The breaking changes are narrow: a few generated Management API types where field types were tightened or split for type-safety, and the removal of the Federated Connections Tokensets API. + +- [Overview](#overview) +- [Breaking changes](#breaking-changes) + - [1. Role pagination fields are now non-optional primitives](#1-role-pagination-fields-are-now-non-optional-primitives) + - [2. Connection attribute `identifier` is split by attribute type](#2-connection-attribute-identifier-is-split-by-attribute-type) + - [3. Phone provider protection backoff strategy enum value changed](#3-phone-provider-protection-backoff-strategy-enum-value-changed) + - [4. Federated Connections Tokensets API removed](#4-federated-connections-tokensets-api-removed) +- [Other changes](#other-changes) + - [Per-request retry configuration](#per-request-retry-configuration) + - [Query parameter serialization](#query-parameter-serialization) +- [Migration steps](#migration-steps) + +## Overview + +Most `v3` code compiles and runs unchanged on `v4`. You only need to act if your code touches one of the following: + +| Area | What changed | Impact | +|------|--------------|--------| +| `ListRolesOffsetPaginatedResponseContent` | `start` / `limit` / `total` changed from `Optional` to primitive `double`, and are now required builder stages | Callers reading these getters or constructing the type | +| Connection attributes | The shared `ConnectionAttributeIdentifier` type is removed and replaced by dedicated `EmailAttributeIdentifier`, `PhoneAttributeIdentifier`, and `UsernameAttributeIdentifier` types | Callers reading/setting `identifier` on `EmailAttribute`, `PhoneAttribute`, `UsernameAttribute` | +| `PhoneProviderProtectionBackoffStrategyEnum` | `NONE` (`"none"`) removed, replaced by `DEFAULT` (`"default"`) | Callers referencing the `NONE` constant or visitor | +| Federated Connections Tokensets | `client.users().federatedConnectionsTokensets()` and its types removed | Callers of that API | + +Everything else in `v4` is additive or internal. + +## Breaking changes + +### 1. Role pagination fields are now non-optional primitives + +In `ListRolesOffsetPaginatedResponseContent`, the `start`, `limit`, and `total` fields change from `Optional` to primitive `double`, and the builder now requires them as mandatory, staged arguments. + +**v3:** +```java +private final Optional start; +public Optional getStart() { ... } +``` + +**v4:** +```java +private final double start; +public double getStart() { ... } +``` + +If you read these getters, drop the `Optional` handling: + +```java +// v3 +double start = response.getStart().orElse(0d); + +// v4 +double start = response.getStart(); +``` + +If you construct the type, the builder is now staged and requires `start`, `limit`, and `total` in order: + +```java +// v4 +ListRolesOffsetPaginatedResponseContent content = ListRolesOffsetPaginatedResponseContent.builder() + .start(0) + .limit(50) + .total(200) + .roles(roles) + .build(); +``` + +### 2. Connection attribute `identifier` is split by attribute type + +The shared `ConnectionAttributeIdentifier` type is removed and replaced with dedicated types per attribute. The `identifier` field on `EmailAttribute`, `PhoneAttribute`, and `UsernameAttribute` now uses the matching type, so their `getIdentifier()` and builder `identifier(...)` signatures change. + +| Attribute | v3 identifier type | v4 identifier type | +|-----------|--------------------|--------------------| +| `EmailAttribute` | `ConnectionAttributeIdentifier` | `EmailAttributeIdentifier` | +| `PhoneAttribute` | `ConnectionAttributeIdentifier` | `PhoneAttributeIdentifier` | +| `UsernameAttribute` | `ConnectionAttributeIdentifier` | `UsernameAttributeIdentifier` | + +**v3:** +```java +public Optional getIdentifier() { ... } +``` + +**v4 (`EmailAttribute`):** +```java +public Optional getIdentifier() { ... } +``` + +Update your imports and any variables holding the identifier. The new types expose `active` (`Optional`); `EmailAttributeIdentifier` and `PhoneAttributeIdentifier` additionally expose a `defaultMethod` (`DefaultMethodEmailIdentifierEnum` / `DefaultMethodPhoneNumberIdentifierEnum`). + +```java +// v4 +EmailAttribute email = EmailAttribute.builder() + .identifier(EmailAttributeIdentifier.builder() + .active(true) + .build()) + .build(); +``` + +### 3. Phone provider protection backoff strategy enum value changed + +`PhoneProviderProtectionBackoffStrategyEnum.NONE` (`"none"`, `visitNone()`) is removed and replaced by `PhoneProviderProtectionBackoffStrategyEnum.DEFAULT` (`"default"`, `visitDefault()`). + +**v3:** +```java +PhoneProviderProtectionBackoffStrategyEnum strategy = PhoneProviderProtectionBackoffStrategyEnum.NONE; +``` + +**v4:** +```java +PhoneProviderProtectionBackoffStrategyEnum strategy = PhoneProviderProtectionBackoffStrategyEnum.DEFAULT; +``` + +If you implement the visitor interface, rename `visitNone()` to `visitDefault()`. + +### 4. Federated Connections Tokensets API removed + +The Federated Connections Tokensets API is removed. The following are no longer available: + +- Client accessor: `client.users().federatedConnectionsTokensets()` (and its async/raw variants) +- Types: `FederatedConnectionTokenSet`, `ConnectionFederatedConnectionsAccessTokens` + +**v3:** +```java +List tokensets = + client.users().federatedConnectionsTokensets().list("user_id"); + +client.users().federatedConnectionsTokensets().delete("user_id", "tokenset_id"); +``` + +**v4:** + +No replacement is generated in the SDK. Remove these calls; if you still need this functionality, call the corresponding Management API endpoint directly. + +## Other changes + +These are backward-compatible but worth noting. + +### Per-request retry configuration + +Requests now honor a per-request `maxRetries` value via `RequestOptions`, alongside the existing `timeout`: + +```java +GetUserResponseContent user = client.users().get( + "user_id", + GetUserRequestParameters.builder().build(), + RequestOptions.builder() + .timeout(10) + .maxRetries(2) + .build() +); +``` + +### Query parameter serialization + +List/query parameter types (e.g. `ListUsersRequestParameters`, `ListClientsRequestParameters`, `ListLogsRequestParameters`, `ListConnectionsQueryParameters`) now serialize their optional/nullable query parameters through a nullable-nonempty filter instead of being marked `@JsonIgnore`. Builder usage is unchanged; this only affects how parameters are emitted on the wire. + +## Migration steps + +1. Update the dependency to the `v4` release. +2. Replace any `ConnectionAttributeIdentifier` imports/usages with the matching `EmailAttributeIdentifier`, `PhoneAttributeIdentifier`, or `UsernameAttributeIdentifier`. +3. Remove `Optional` handling around `ListRolesOffsetPaginatedResponseContent#getStart/getLimit/getTotal`, and update any builder usage to the staged `start` → `limit` → `total` form. +4. Replace `PhoneProviderProtectionBackoffStrategyEnum.NONE` with `DEFAULT` (and `visitNone()` with `visitDefault()` in any visitor implementations). +5. Remove any usage of `client.users().federatedConnectionsTokensets()` and the `FederatedConnectionTokenSet` / `ConnectionFederatedConnectionsAccessTokens` types. +6. Run `mvn verify` (or your build) and fix any remaining compilation errors surfaced by the above.