From 930570654b4a80276a070bea77c0863eac919fa7 Mon Sep 17 00:00:00 2001 From: tanya732 Date: Tue, 3 Mar 2026 15:27:09 +0530 Subject: [PATCH 1/2] Patch: Fixed Readme links and added Examples --- .github/workflows/claude-code-review.yml | 11 - EXAMPLES.md | 335 +++++++++++++++++++++++ README.md | 39 +-- 3 files changed, 357 insertions(+), 28 deletions(-) delete mode 100644 .github/workflows/claude-code-review.yml create mode 100644 EXAMPLES.md diff --git a/.github/workflows/claude-code-review.yml b/.github/workflows/claude-code-review.yml deleted file mode 100644 index 95ca681e3..000000000 --- a/.github/workflows/claude-code-review.yml +++ /dev/null @@ -1,11 +0,0 @@ -name: Claude Code PR Review - -on: - issue_comment: - types: [ created ] - pull_request_review_comment: - types: [ created ] - -jobs: - claude-review: - uses: auth0/auth0-ai-pr-analyzer-gh-action/.github/workflows/claude-code-review.yml@main diff --git a/EXAMPLES.md b/EXAMPLES.md new file mode 100644 index 000000000..3f7b8b1f2 --- /dev/null +++ b/EXAMPLES.md @@ -0,0 +1,335 @@ +# Examples using auth0-java + +- [Error handling](#error-handling) +- [HTTP Client configuration](#http-client-configuration) +- [Management API usage](#management-api-usage) +- [Verifying an ID token](#verifying-an-id-token) +- [Organizations](#organizations) +- [Asynchronous operations](#asynchronous-operations) + +## Error handling + +### Management API errors + +The Management API uses a unified `ManagementApiException` class, which provides access to the HTTP status code, response body, headers, and message of the error response. + +```java +import com.auth0.client.mgmt.core.ManagementApiException; + +try { + GetUserResponseContent user = client.users().get("user_id"); +} catch (ManagementApiException e) { + int statusCode = e.statusCode(); + Object body = e.body(); + Map> headers = e.headers(); + String message = e.getMessage(); +} +``` + +### Authentication API errors + +The Authentication API uses `APIException` for error handling. + +```java +import com.auth0.exception.APIException; + +try { + TokenHolder holder = authAPI.requestToken("https://{YOUR_DOMAIN}/api/v2/").execute().getBody(); +} catch (APIException e) { + int statusCode = e.getStatusCode(); + String description = e.getDescription(); + String error = e.getError(); +} +``` + +## HTTP Client configuration + +### Authentication API + +The Authentication API client uses the OkHttp networking library to make HTTP requests. +The client can be configured by building a `DefaultHttpClient` and providing it to the API client. + +```java +Auth0HttpClient httpClient = DefaultHttpClient.newBuilder() + // configure as needed + .build(); + +AuthAPI auth = AuthAPI.newBuilder("{YOUR_DOMAIN}", "{YOUR_CLIENT_ID}", "{YOUR_CLIENT_SECRET}") + .withHttpClient(httpClient) + .build(); +``` + +If the `DefaultHttpClient` does not support your required networking client configuration, you may choose to implement +your own client by implementing the `Auth0HttpClient` interface and providing it to the API client. This is an advanced +use case and should be used only when necessary. + +### Management API + +The Management API client uses `ManagementApi` as the main entry point. +You can configure a custom `OkHttpClient` via the builder: + +```java +import com.auth0.client.mgmt.ManagementApi; + +OkHttpClient okHttpClient = new OkHttpClient.Builder() + // configure as needed + .build(); + +ManagementApi client = ManagementApi.builder() + .domain("{YOUR_DOMAIN}") + .token("{YOUR_API_TOKEN}") + .httpClient(okHttpClient) + .build(); +``` + +## Management API usage + +### Creating a client with a static token + +```java +import com.auth0.client.mgmt.ManagementApi; + +ManagementApi client = ManagementApi.builder() + .domain("{YOUR_DOMAIN}") + .token("{YOUR_API_TOKEN}") + .build(); +``` + +### Creating a client with client credentials (recommended) + +When using client credentials, the SDK automatically fetches and caches access tokens, refreshing them before expiry. + +```java +import com.auth0.client.mgmt.ManagementApi; + +ManagementApi client = ManagementApi.builder() + .domain("{YOUR_DOMAIN}") + .clientCredentials("{YOUR_CLIENT_ID}", "{YOUR_CLIENT_SECRET}") + .build(); +``` + +You can also specify a custom audience: + +```java +ManagementApi client = ManagementApi.builder() + .domain("{YOUR_DOMAIN}") + .clientCredentials("{YOUR_CLIENT_ID}", "{YOUR_CLIENT_SECRET}") + .audience("{YOUR_AUDIENCE}") + .build(); +``` + +### Creating a client with advanced options + +```java +ManagementApi client = ManagementApi.builder() + .domain("{YOUR_DOMAIN}") + .clientCredentials("{YOUR_CLIENT_ID}", "{YOUR_CLIENT_SECRET}") + .timeout(30) // timeout in seconds (default: 60) + .maxRetries(3) // max retries (default: 2) + .addHeader("X-Custom-Header", "value") + .build(); +``` + +### Accessing resources + +The Management API is organized into resource clients: + +```java +// Get a user +GetUserResponseContent user = client.users().get("user_id"); + +// Get a role +GetRoleResponseContent role = client.roles().get("role_id"); + +// Create a user +CreateUserResponseContent newUser = client.users().create( + CreateUserRequestContent.builder() + .email("user@example.com") + .connection("Username-Password-Authentication") + .password("securePassword123!") + .build() +); + +// Update a user +UpdateUserResponseContent updatedUser = client.users().update( + "user_id", + UpdateUserRequestContent.builder() + .name("Updated Name") + .build() +); + +// Delete a user +client.users().delete("user_id"); +``` + +### Pagination + +List operations return a `SyncPagingIterable` that supports automatic pagination: + +```java +import com.auth0.client.mgmt.core.SyncPagingIterable; +import com.auth0.client.mgmt.types.ListUsersRequestParameters; +import com.auth0.client.mgmt.types.UserResponseSchema; + +SyncPagingIterable users = client.users().list( + ListUsersRequestParameters.builder() + .perPage(50) + .build() +); + +// Iterate through all pages automatically +for (UserResponseSchema user : users) { + System.out.println(user.getEmail()); +} + +// Or access pages manually +List pageItems = users.getItems(); +while (users.hasNext()) { + pageItems = users.nextPage().getItems(); +} +``` + +### Accessing raw HTTP responses + +Use `withRawResponse()` to access HTTP response metadata: + +```java +import com.auth0.client.mgmt.core.ManagementApiHttpResponse; + +ManagementApiHttpResponse response = client.users() + .withRawResponse() + .get("user_id"); + +GetUserResponseContent user = response.body(); +Map> headers = response.headers(); +``` + +### Nested sub-resources + +Some resources have nested sub-clients: + +```java +// List a user's roles +SyncPagingIterable roles = client.users().roles().list("user_id"); + +// List a user's permissions +SyncPagingIterable permissions = client.users().permissions().list("user_id"); + +// List organization members +SyncPagingIterable members = client.organizations().members().list("org_id"); +``` + +## Verifying an ID token + +This library also provides the ability to validate an OIDC-compliant ID Token, according to the [OIDC Specification](https://openid.net/specs/openid-connect-core-1_0-final.html#IDTokenValidation). + +### Verifying an ID Token signed with the RS256 signing algorithm + +To verify an ID Token that is signed using the RS256 signing algorithm, you will need to provide an implementation of +`PublicKeyProvider` that will return the public key used to verify the token's signature. The example below demonstrates how to use the `JwkProvider` from the [jwks-rsa-java](https://github.com/auth0/jwks-rsa-java) library: + +```java +JwkProvider provider = new JwkProviderBuilder("https://your-domain.auth0.com").build(); +SignatureVerifier signatureVerifier = SignatureVerifier.forRS256(new PublicKeyProvider() { + @Override + public RSAPublicKey getPublicKeyById(String keyId) throws PublicKeyProviderException { + try { + return (RSAPublicKey) provider.get(keyId).getPublicKey(); + } catch (JwkException jwke) { + throw new PublicKeyProviderException("Error obtaining public key", jwke); + } + } +} + +IdTokenVerifier idTokenVerifier = IdTokenVerifier.init("https://your-domain.auth0.com/","your-client-id", signatureVerifier).build(); + +try { + idTokenVerifier.verify("token", "expected-nonce"); +} catch(IdTokenValidationException idtve) { + // Handle invalid token exception +} +``` + +### Verifying an ID Token signed with the HS256 signing algorithm + +To verify an ID Token that is signed using the HS256 signing algorithm: + +```java +SignatureVerifier signatureVerifier = SignatureVerifier.forHS256("your-client-secret"); +IdTokenVerifier idTokenVerifier = IdTokenVerifier.init("https://your-domain.auth0.com/","your-client-id", signatureVerifier).build(); + +try { + idTokenVerifier.verify("token", "expected-nonce"); +} catch(IdTokenValidationException idtve) { + // Handle invalid token exception +} +``` + +## Organizations + +[Organizations](https://auth0.com/docs/organizations) is a set of features that provide better support for developers who build and maintain SaaS and Business-to-Business (B2B) applications. + +Note that Organizations is currently only available to customers on our Enterprise and Startup subscription plans. + +### Log in to an organization + +Log in to an organization by using `withOrganization()` when building the Authorization URL: + +```java +AuthAPI auth = AuthAPI.newBuilder("{YOUR_DOMAIN}", "{YOUR_CLIENT_ID}", "{YOUR_CLIENT_SECRET}").build(); +String url = auth.authorizeUrl("https://me.auth0.com/callback") + .withOrganization("{YOUR_ORGANIZATION_ID}") + .build(); +``` + +**Important!** When logging into an organization, it is important to ensure the `org_id` claim of the ID Token matches the expected organization value. The `IdTokenVerifier` can be configured with an expected `org_id` claim value, as the example below demonstrates. +For more information, please read [Work with Tokens and Organizations](https://auth0.com/docs/organizations/using-tokens) on Auth0 Docs. +```java +IdTokenVerifier.init("{ISSUER}", "{AUDIENCE}", signatureVerifier) + .withOrganization("{ORG_ID}") + .build() + .verify(jwt); +``` + +### Accept user invitations + +Accept a user invitation by using `withInvitation()` when building the Authorization URL: + +```java +AuthAPI auth = AuthAPI.newBuilder("{YOUR_DOMAIN}", "{YOUR_CLIENT_ID}", "{YOUR_CLIENT_SECRET}").build(); +String url = auth.authorizeUrl("https://me.auth0.com/callback") + .withOrganization("{YOUR_ORGANIZATION_ID}") + .withInvitation("{YOUR_INVITATION_ID}") + .build(); +``` + +## Asynchronous operations + +### Management API + +The Management API provides an async client that returns `CompletableFuture` for all operations: + +```java +import com.auth0.client.mgmt.AsyncManagementApi; +import com.auth0.client.mgmt.core.ClientOptions; + +AsyncManagementApi asyncClient = new AsyncManagementApi(clientOptions); + +// Async user retrieval +CompletableFuture future = asyncClient.users().get("user_id"); +future.thenAccept(user -> { + System.out.println(user.getEmail()); +}); +``` + +### Authentication API + +The Authentication API supports async operations via the `executeAsync()` method: + +```java +AuthAPI auth = AuthAPI.newBuilder("{YOUR_DOMAIN}", "{YOUR_CLIENT_ID}", "{YOUR_CLIENT_SECRET}").build(); +CompletableFuture future = auth.requestToken("https://{YOUR_DOMAIN}/api/v2/").executeAsync(); +future.thenAccept(holder -> { + String accessToken = holder.getBody().getAccessToken(); +}); +``` diff --git a/README.md b/README.md index 595814536..c8a9646f5 100644 --- a/README.md +++ b/README.md @@ -17,8 +17,9 @@ :books: [Documentation](#documentation) - :rocket: [Getting Started](#getting-started) - :computer: [API Reference](#api-reference) :speech_balloon: [Feedback](#feedback) ## Documentation +- [Reference](./reference.md) - code samples for Management APIs. - [Examples](./EXAMPLES.md) - code samples for common auth0-java scenarios. -- [Migration Guide](./MIGRATION_GUIDE) - guidance for updating your application to use version 3 of auth0-java. +- [Migration Guide](./MIGRATION_GUIDE.md) - guidance for updating your application to use version 3 of auth0-java. - [Docs site](https://www.auth0.com/docs) - explore our docs site and learn more about Auth0. ## Getting Started @@ -61,48 +62,52 @@ AuthAPI auth = AuthAPI.newBuilder("{YOUR_DOMAIN}", "{YOUR_CLIENT_ID}", "{YOUR_CL #### Management API Client -The Management API client is based on the [Management API Docs](https://auth0.com/docs/api/management/v2). +The Management API client is based on the [Management API Docs](https://auth0.com/docs/api/management/v2). In v3, the Management API is Fern-generated and uses `ManagementApi` as the entry point. -Create a `ManagementAPI` instance by providing the domain from the [Application dashboard](https://manage.auth0.com/#/applications) and a valid API Token. +Create a `ManagementApi` instance with a static token: ```java -ManagementAPI mgmt = ManagementAPI.newBuilder("{YOUR_DOMAIN}", "{YOUR_API_TOKEN}").build(); +ManagementApi mgmt = ManagementApi.builder() + .domain("{YOUR_DOMAIN}") + .token("{YOUR_API_TOKEN}") + .build(); ``` -OR - -Create a `ManagementAPI` instance by providing the domain from the [Application dashboard](https://manage.auth0.com/#/applications) and Token Provider. +Or use client credentials for automatic token management (recommended for server-to-server applications): ```java -TokenProvider tokenProvider = SimpleTokenProvider.create("{YOUR_API_TOKEN}"); -ManagementAPI mgmt = ManagementAPI.newBuilder("{YOUR_DOMAIN}", TokenProvider).build(); +ManagementApi mgmt = ManagementApi.builder() + .domain("{YOUR_DOMAIN}") + .clientCredentials("{YOUR_CLIENT_ID}", "{YOUR_CLIENT_SECRET}") + .build(); ``` -The Management API is organized by entities represented by the Auth0 Management API objects. +The Management API is organized into resource clients. Methods return typed response objects directly: ```java -User user = mgmt.users().get("auth0|user-id", new UserFilter()).execute().getBody(); -Role role = mgmt.roles().get("role-id").execute().getBody(); +GetUserResponseContent user = mgmt.users().get("user_id"); +GetRoleResponseContent role = mgmt.roles().get("role_id"); ``` -You can use the Authentication API to obtain a token for a previously authorized Application: +You can also obtain a token via the Authentication API and use it with the Management API client: ```java AuthAPI authAPI = AuthAPI.newBuilder("{YOUR_DOMAIN}", "{YOUR_CLIENT_ID}", "{YOUR_CLIENT_SECRET}").build(); TokenRequest tokenRequest = authAPI.requestToken("https://{YOUR_DOMAIN}/api/v2/"); TokenHolder holder = tokenRequest.execute().getBody(); String accessToken = holder.getAccessToken(); -ManagementAPI mgmt = ManagementAPI.newBuilder("{YOUR_DOMAIN}", accessToken).build(); +ManagementApi mgmt = ManagementApi.builder() + .domain("{YOUR_DOMAIN}") + .token(accessToken) + .build(); ``` -An expired token for an existing `ManagementAPI` instance can be replaced by calling the `setApiToken` method with the new token. - See the [Auth0 Management API documentation](https://auth0.com/docs/api/management/v2/tokens) for more information on how to obtain API Tokens. ## API Reference - [AuthAPI](https://javadoc.io/doc/com.auth0/auth0/latest/com/auth0/client/auth/AuthAPI.html) -- [ManagementAPI](https://javadoc.io/doc/com.auth0/auth0/latest/com/auth0/client/mgmt/ManagementAPI.html) +- [ManagementApi](https://javadoc.io/doc/com.auth0/auth0/latest/com/auth0/client/mgmt/ManagementApi.html) ## Feedback From fac7a20e5c99903da992f4bcea998fc44a63262c Mon Sep 17 00:00:00 2001 From: tanya732 Date: Tue, 3 Mar 2026 15:58:05 +0530 Subject: [PATCH 2/2] Updated jackson dependency to 2.18.6 --- build.gradle | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/build.gradle b/build.gradle index 92aeb6f7e..a25efcd81 100644 --- a/build.gradle +++ b/build.gradle @@ -22,9 +22,9 @@ logger.lifecycle("Using version ${version} for ${name} group $group") dependencies { // Core dependencies api 'com.squareup.okhttp3:okhttp:5.2.1' - api 'com.fasterxml.jackson.core:jackson-databind:2.18.2' - api 'com.fasterxml.jackson.datatype:jackson-datatype-jdk8:2.18.2' - api 'com.fasterxml.jackson.datatype:jackson-datatype-jsr310:2.18.2' + api 'com.fasterxml.jackson.core:jackson-databind:2.18.6' + api 'com.fasterxml.jackson.datatype:jackson-datatype-jdk8:2.18.6' + api 'com.fasterxml.jackson.datatype:jackson-datatype-jsr310:2.18.6' // Dependencies for legacy management code from auth0-real implementation 'com.squareup.okhttp3:logging-interceptor:5.2.1'