diff --git a/README.md b/README.md index d193a91..c3c4dac 100644 --- a/README.md +++ b/README.md @@ -30,10 +30,11 @@ More information about the API can be found at https://clerk.com/docs * [SDK Installation](#sdk-installation) * [SDK Example Usage](#sdk-example-usage) +* [Authentication](#authentication) +* [Request Authentication](#request-authentication) * [Available Resources and Operations](#available-resources-and-operations) * [Error Handling](#error-handling) * [Server Selection](#server-selection) -* [Authentication](#authentication) @@ -107,6 +108,68 @@ public class Application { ``` + +## Authentication + +### Per-Client Security Schemes + +This SDK supports the following security scheme globally: + +| Name | Type | Scheme | +| ------------ | ---- | ----------- | +| `bearerAuth` | http | HTTP Bearer | + +To authenticate with the API the `bearerAuth` parameter must be set when initializing the SDK client instance. For example: +```java +package hello.world; + +import com.clerk.backend_api.Clerk; +import com.clerk.backend_api.models.operations.GetPublicInterstitialResponse; +import java.lang.Exception; + +public class Application { + + public static void main(String[] args) throws Exception { + + Clerk sdk = Clerk.builder() + .bearerAuth("") + .build(); + + GetPublicInterstitialResponse res = sdk.miscellaneous().getInterstitial() + .frontendApi("") + .publishableKey("") + .call(); + + // handle response + } +} +``` + + +## Request Authentication + +Use the [authenticateRequest](https://github.com/clerk/clerk-sdk-java/blob/main/src/main/java/com/clerk/backend_api/helpers/jwks/AuthenticateRequest.java) method to authenticate a request from your app's frontend (when using a Clerk frontend SDK) to Clerk's Backend API. For example the following utility function checks if the user is effectively signed in: + +```java +import java.net.http.HttpRequest; +import com.clerk.backend_api.helpers.jwks.AuthenticateRequest; +import com.clerk.backend_api.helpers.jwks.AuthenticateRequestOptions; +import com.clerk.backend_api.helpers.jwks.RequestState; + +public class UserAuthentication { + + public static boolean isSignedIn(HttpRequest request) { + RequestState requestState = AuthenticateRequest.authenticateRequest(request, AuthenticateRequestOptions + .secretKey(System.getenv("CLERK_SECRET_KEY")) + .authorizedParty("https://example.com") + .build()); + return state.isSignedIn(); + } +``` + +If the request is correctly authenticated, the token's claims are made available in `requestState.claims()`. Otherwise the reason for the token verification failure is given by `requestState.reason()`. + + ## Available Resources and Operations @@ -417,43 +480,6 @@ public class Application { ``` - -## Authentication - -### Per-Client Security Schemes - -This SDK supports the following security scheme globally: - -| Name | Type | Scheme | -| ------------ | ---- | ----------- | -| `bearerAuth` | http | HTTP Bearer | - -To authenticate with the API the `bearerAuth` parameter must be set when initializing the SDK client instance. For example: -```java -package hello.world; - -import com.clerk.backend_api.Clerk; -import com.clerk.backend_api.models.operations.GetPublicInterstitialResponse; -import java.lang.Exception; - -public class Application { - - public static void main(String[] args) throws Exception { - - Clerk sdk = Clerk.builder() - .bearerAuth("") - .build(); - - GetPublicInterstitialResponse res = sdk.miscellaneous().getInterstitial() - .frontendApi("") - .publishableKey("") - .call(); - - // handle response - } -} -``` - diff --git a/src/test/java/com/clerk/backend_api/helpers/jwks/AuthenticateRequestTest.java b/src/test/java/com/clerk/backend_api/helpers/jwks/AuthenticateRequestTest.java index 98d3237..b1d2eb9 100644 --- a/src/test/java/com/clerk/backend_api/helpers/jwks/AuthenticateRequestTest.java +++ b/src/test/java/com/clerk/backend_api/helpers/jwks/AuthenticateRequestTest.java @@ -155,7 +155,7 @@ public void testAuthenticateRequestLocal() throws URISyntaxException { } @Test - @EnabledIfEnvironmentVariable(named = "CLERK_SESSION_KEY", matches = ".+") + @EnabledIfEnvironmentVariable(named = "CLERK_SESSION_TOKEN", matches = ".+") public void testAuthenticateRequestNoSecretKey() throws URISyntaxException { String token = sessionToken.get();