From ca06fbb278caecc3e3ea784d74873c7cde2642d8 Mon Sep 17 00:00:00 2001 From: Igor Petrov Date: Thu, 19 Dec 2024 23:08:21 +0200 Subject: [PATCH 1/2] docs: added x.509 docs for java clients --- docs/apis-tools/java-client/index.md | 44 +++++++++++++++++++ .../spring-zeebe-sdk/configuration.md | 42 ++++++++++++++++++ 2 files changed, 86 insertions(+) diff --git a/docs/apis-tools/java-client/index.md b/docs/apis-tools/java-client/index.md index 30212b1bdc8..cafe36ae584 100644 --- a/docs/apis-tools/java-client/index.md +++ b/docs/apis-tools/java-client/index.md @@ -92,6 +92,50 @@ ZeebeClient client = .build(); ``` +### X.509 authorizers + +Several identity providers, such as Keycloak, support client X.509 authorizers as an alternative to client credentials +flow. + +As a prerequisite, you need to have proper keystore and truststore configured, so that: (1) both Spring Zeebe application +and identity provider share the same CA trust certificates; (2) both Spring Zeebe and identity provider own certificates +signed by trusted CA; (3) your Spring Zeebe application own certificate has proper `Distinguished Name` (DN), e.g. +`CN=My Zeebe Client, OU=Camunda Users, O=Best Company, C=DE`; (4) your application DN registered in the identity provider +client authorization details. + +In that case, configuring `OAuthCredentialsProvider` might look like this + +```java +final OAuthCredentialsProvider provider = + new OAuthCredentialsProviderBuilder() + .clientId("myClient") + .clientSecret("") + .audience("myClient-aud") + .authorizationServerUrl(ZEEBE_AUTHORIZATION_SERVER_URL) + .keystorePath(Paths.get("/path/to/keystore.p12")) + .keystorePassword("password") + .keystoreKeyPassword("password") + .truststorePath(Paths.get("/path/to/truststore.jks")) + .truststorePassword("password") + .build(); +``` + +Or via environment variables + +```bash +export ZEEBE_CLIENT_ID='[Client ID]' +export ZEEBE_CLIENT_SECRET='' +export ZEEBE_AUTHORIZATION_SERVER_URL='[OAuth API]' +export ZEEBE_SSL_CLIENT_KEYSTORE_PATH='[Keystore path]' +export ZEEBE_SSL_CLIENT_KEYSTORE_SECRET='[Keystore password]' +export ZEEBE_SSL_CLIENT_KEYSTORE_KEY_SECRET='[Keystore material password]' +export ZEEBE_SSL_CLIENT_TRUSTSTORE_PATH='[Truststore path]' +export ZEEBE_SSL_CLIENT_TRUSTSTORE_SECRET='[Truststore password]' +``` + +Please refer your identity provider reference page on how to configure X.509 authentication, for example, +[Keycloak](https://www.keycloak.org/server/mutual-tls). + ## Javadoc The official Java client library API documentation can be found [here](https://javadoc.io/doc/io.camunda/zeebe-client-java). These are standard Javadocs, so your favorite JVM IDE will be able to install them locally as well. diff --git a/docs/apis-tools/spring-zeebe-sdk/configuration.md b/docs/apis-tools/spring-zeebe-sdk/configuration.md index 6cff515bf51..fcea8a12533 100644 --- a/docs/apis-tools/spring-zeebe-sdk/configuration.md +++ b/docs/apis-tools/spring-zeebe-sdk/configuration.md @@ -510,6 +510,31 @@ camunda: - foo ``` +### Custom identity provider security context + +If you require configuring SSL context exclusively for identity provider: + +```yaml +camunda: + client: + auth: + keystore-path: /path/to/keystore.p12 + keystore-password: password + keystore-key-password: password + truststore-path: /path/to/truststore.jks + truststore-password: password +``` + +- **keystore-path**: path to client's keystore; can be both in JKS or PKCS12 formats +- **keystore-password**: keystore password +- **keystore-key-password**: key material password +- **truststore-path**: path to client's truststore +- **truststore-password**: truststore password + +When the properties are not specified, the default SSL context will be applied, thus if you configure application with +`javax.net.ssl.*` or `spring.ssl.*`, the latter is applied. If both `camunda.client.auth.*` and either `javax.net.ssl.*` +or `spring.ssl.*` properties are defined, the `camunda.client.auth.*` will take precedence. + ## Observing metrics The Spring Zeebe SDK provides some out-of-the-box metrics that can be leveraged via [Spring Actuator](https://docs.spring.io/spring-boot/docs/current/actuator-api/htmlsingle/). Whenever actuator is on the classpath, you can access the following metrics: @@ -534,3 +559,20 @@ management: ``` Access them via [http://localhost:8080/actuator/metrics/](http://localhost:8080/actuator/metrics/). + +## Using identity provider X.509 authorizers + +Several identity providers, such as Keycloak, support client X.509 authorizers as an alternative to client credentials +flow. + +As a prerequisite, you need to have proper keystore and truststore configured, so that: (1) both Spring Zeebe application +and identity provider share the same CA trust certificates; (2) both Spring Zeebe and identity provider own certificates +signed by trusted CA; (3) your Spring Zeebe application own certificate has proper `Distinguished Name` (DN), e.g. +`CN=My Zeebe Client, OU=Camunda Users, O=Best Company, C=DE`; (4) your application DN registered in the identity provider +client authorization details. + +Once prerequisites are satisfied, your Spring Zeebe application has to be configured either via global SSL context, or +with [identity provider exclusive context](#custom-identity-provider-security-context). + +Please refer your identity provider reference page on how to configure X.509 authentication, for example, +[Keycloak](https://www.keycloak.org/server/mutual-tls). From 94b2420d9c66db1c288565fe7198a1a6c9a0c560 Mon Sep 17 00:00:00 2001 From: Christina Ausley Date: Fri, 27 Dec 2024 09:42:57 -0500 Subject: [PATCH 2/2] style(formatting): grammatical review --- docs/apis-tools/java-client/index.md | 20 +++++------ .../spring-zeebe-sdk/configuration.md | 36 +++++++++---------- 2 files changed, 28 insertions(+), 28 deletions(-) diff --git a/docs/apis-tools/java-client/index.md b/docs/apis-tools/java-client/index.md index cafe36ae584..6a508646204 100644 --- a/docs/apis-tools/java-client/index.md +++ b/docs/apis-tools/java-client/index.md @@ -94,14 +94,15 @@ ZeebeClient client = ### X.509 authorizers -Several identity providers, such as Keycloak, support client X.509 authorizers as an alternative to client credentials -flow. +Several identity providers, such as Keycloak, support client X.509 authorizers as an alternative to client credentials flow. -As a prerequisite, you need to have proper keystore and truststore configured, so that: (1) both Spring Zeebe application -and identity provider share the same CA trust certificates; (2) both Spring Zeebe and identity provider own certificates -signed by trusted CA; (3) your Spring Zeebe application own certificate has proper `Distinguished Name` (DN), e.g. -`CN=My Zeebe Client, OU=Camunda Users, O=Best Company, C=DE`; (4) your application DN registered in the identity provider -client authorization details. +As a prerequisite, ensure you have proper KeyStore and TrustStore configured, so that: + +- Both the Spring Zeebe application and identity provider share the same CA trust certificates. +- Both the Spring Zeebe and identity provider own certificates signed by trusted CA. +- Your Spring Zeebe application own certificate has proper `Distinguished Name` (DN), e.g. + `CN=My Zeebe Client, OU=Camunda Users, O=Best Company, C=DE`. +- Your application DN registered in the identity provider client authorization details. In that case, configuring `OAuthCredentialsProvider` might look like this @@ -120,7 +121,7 @@ final OAuthCredentialsProvider provider = .build(); ``` -Or via environment variables +Or via environment variables: ```bash export ZEEBE_CLIENT_ID='[Client ID]' @@ -133,8 +134,7 @@ export ZEEBE_SSL_CLIENT_TRUSTSTORE_PATH='[Truststore path]' export ZEEBE_SSL_CLIENT_TRUSTSTORE_SECRET='[Truststore password]' ``` -Please refer your identity provider reference page on how to configure X.509 authentication, for example, -[Keycloak](https://www.keycloak.org/server/mutual-tls). +Refer to your identity provider documentation on how to configure X.509 authentication. For example, [Keycloak](https://www.keycloak.org/server/mutual-tls). ## Javadoc diff --git a/docs/apis-tools/spring-zeebe-sdk/configuration.md b/docs/apis-tools/spring-zeebe-sdk/configuration.md index fcea8a12533..e088ccd1878 100644 --- a/docs/apis-tools/spring-zeebe-sdk/configuration.md +++ b/docs/apis-tools/spring-zeebe-sdk/configuration.md @@ -512,7 +512,7 @@ camunda: ### Custom identity provider security context -If you require configuring SSL context exclusively for identity provider: +If you require configuring SSL context exclusively for your identity provider: ```yaml camunda: @@ -525,15 +525,15 @@ camunda: truststore-password: password ``` -- **keystore-path**: path to client's keystore; can be both in JKS or PKCS12 formats -- **keystore-password**: keystore password -- **keystore-key-password**: key material password -- **truststore-path**: path to client's truststore -- **truststore-password**: truststore password +- **keystore-path**: Path to client's KeyStore; can be both in JKS or PKCS12 formats +- **keystore-password**: KeyStore password +- **keystore-key-password**: Key material password +- **truststore-path**: Path to client's TrustStore +- **truststore-password**: TrustStore password -When the properties are not specified, the default SSL context will be applied, thus if you configure application with +When the properties are not specified, the default SSL context is applied. For example, if you configure an application with `javax.net.ssl.*` or `spring.ssl.*`, the latter is applied. If both `camunda.client.auth.*` and either `javax.net.ssl.*` -or `spring.ssl.*` properties are defined, the `camunda.client.auth.*` will take precedence. +or `spring.ssl.*` properties are defined, the `camunda.client.auth.*` takes precedence. ## Observing metrics @@ -562,17 +562,17 @@ Access them via [http://localhost:8080/actuator/metrics/](http://localhost:8080/ ## Using identity provider X.509 authorizers -Several identity providers, such as Keycloak, support client X.509 authorizers as an alternative to client credentials -flow. +Several identity providers, such as Keycloak, support client X.509 authorizers as an alternative to client credentials flow. -As a prerequisite, you need to have proper keystore and truststore configured, so that: (1) both Spring Zeebe application -and identity provider share the same CA trust certificates; (2) both Spring Zeebe and identity provider own certificates -signed by trusted CA; (3) your Spring Zeebe application own certificate has proper `Distinguished Name` (DN), e.g. -`CN=My Zeebe Client, OU=Camunda Users, O=Best Company, C=DE`; (4) your application DN registered in the identity provider -client authorization details. +As a prerequisite, ensure you have proper KeyStore and TrustStore configured, so that: -Once prerequisites are satisfied, your Spring Zeebe application has to be configured either via global SSL context, or +- Both the Spring Zeebe application and identity provider share the same CA trust certificates. +- Both the Spring Zeebe and identity provider own certificates signed by trusted CA. +- Your Spring Zeebe application own certificate has proper `Distinguished Name` (DN), e.g. + `CN=My Zeebe Client, OU=Camunda Users, O=Best Company, C=DE`. +- Your application DN registered in the identity provider client authorization details. + +Once prerequisites are satisfied, your Spring Zeebe application must be configured either via global SSL context, or with [identity provider exclusive context](#custom-identity-provider-security-context). -Please refer your identity provider reference page on how to configure X.509 authentication, for example, -[Keycloak](https://www.keycloak.org/server/mutual-tls). +Refer to your identity provider documentation on how to configure X.509 authentication. For example, [Keycloak](https://www.keycloak.org/server/mutual-tls).