{"id":19963711,"url":"https://github.com/cyberark/conjur-api-java","last_synced_at":"2026-04-10T14:01:57.194Z","repository":{"id":10797421,"uuid":"13068807","full_name":"cyberark/conjur-api-java","owner":"cyberark","description":"Java client for the CyberArk Conjur API","archived":false,"fork":false,"pushed_at":"2024-10-23T15:12:07.000Z","size":555,"stargazers_count":17,"open_issues_count":22,"forks_count":14,"subscribers_count":26,"default_branch":"main","last_synced_at":"2024-12-05T22:22:39.081Z","etag":null,"topics":["api-client","conjbot-notify","conjur","conjur-core","conjur-sdk","core","java"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cyberark.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null}},"created_at":"2013-09-24T15:33:46.000Z","updated_at":"2024-08-12T19:12:21.000Z","dependencies_parsed_at":"2022-09-02T08:50:58.630Z","dependency_job_id":null,"html_url":"https://github.com/cyberark/conjur-api-java","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cyberark%2Fconjur-api-java","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cyberark%2Fconjur-api-java/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cyberark%2Fconjur-api-java/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cyberark%2Fconjur-api-java/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cyberark","download_url":"https://codeload.github.com/cyberark/conjur-api-java/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230408170,"owners_count":18220974,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-client","conjbot-notify","conjur","conjur-core","conjur-sdk","core","java"],"created_at":"2024-11-13T02:17:07.692Z","updated_at":"2026-04-10T14:01:57.187Z","avatar_url":"https://github.com/cyberark.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"Secrets Manager API for Java\n===================\nProgrammatic Java access to the Secrets Manager API (for both Conjur OSS and Secrets Manager, Self-Hosted).\nThis Java SDK allows developers to build new apps in Java that communicate with Conjur by\ninvoking our Secrets Manager API to perform operations on stored data (add, retrieve, etc).\n\n## Table of Contents\n\n- [Prerequisites](#prerequisites)\n  * [Using conjur-api-java with Conjur Open Source](#using-conjur-api-java-with-conjur-open-source)\n- [Setup](#setup)\n  * [Using the Source Code](#using-the-source-code)\n  * [Using the Jarfile](#using-the-jarfile)\n  * [Using Maven Releases](#using-maven-releases)\n  * [Using Maven Snapshots](#using-maven-snapshots)\n  * [Using Other Dependency Management Configurations](#using-other-dependency-management-configurations)\n- [Configuration](#configuration)\n  * [Environment Variables](#environment-variables)\n  * [System Properties](#system-properties)\n- [Set Up Trust Between App and Secrets Manager](#set-up-trust-between-app-and-secrets-manager)\n  * [Client-level trust](#client-level-trust)\n  * [JVM-level trust](#jvm-level-trust)\n- [Authorization Examples](#authorization-examples)\n  * [Environment Variables](#environment-variables-1)\n  * [System Properties](#system-properties-1)\n  * [System Properties with Maven](#system-properties-with-maven)\n  * [Username and Password](#username-and-password)\n  * [Credentials](#credentials)\n  * [Authorization Token](#authorization-token)\n- [Client APIs](#client-apis)\n  * [Secrets Manager Client Instance (`com.cyberark.conjur.api.Conjur`)](#secrets-manager-client-instance-comcyberarkconjurapiconjur)\n  * [Variables (`client.variables()`)](#variables-clientvariables)\n    + [`void addSecret(String variableId, String secret)`](#void-addsecretstring-variableid-string-secret)\n    + [`String retrieveSecret(String variableId)`](#string-retrievesecretstring-variableid)\n    + [`Map\u003cString, String\u003e retrieveBatchSecrets(String... variableIds)`](#mapstring-string-retrievebatchsecretsstring-variableids)\n  * [Resources (`client.resources()`)](#resources-clientresources)\n    + [`List\u003cConjurResource\u003e listResources(ResourceQuery query)`](#listconjurresource-listresourcesresourcequery-query)\n    + [`int countResources(ResourceQuery query)`](#int-countresourcesresourcequery-query)\n- [Jakarta REST JAX-RS Implementations](#jakarta-rest-jax-rs-implementations)\n- [Troubleshooting](#troubleshooting)\n  * [`error: package com.cyberark.conjur does not exist`](#error-package-comcyberarkconjur-does-not-exist)\n  * [`java.lang.NoClassDefFoundError: javax/xml/bind/JAXBException`](#javalangnoclassdeffounderror-javaxxmlbindjaxbexception)\n  * [SSL/TLS/Certificate Issues](#ssltlscertificate-issues)\n- [Contributing](#contributing)\n- [License](#license)\n\n\u003c!-- \n[Table of contents generated with markdown-toci](http://ecotrust-canada.github.io/markdown-toc/)\n--\u003e\n\n## Prerequisites\n\nIt is assumed that Conjur OSS or Secrets Manager, Self-Hosted and the Secrets Manager CLI have already been\ninstalled in the environment and running in the background. If you haven't done so,\nfollow these instructions for installation of the [OSS](https://docs.cyberark.com/conjur-open-source/latest/en/content/hometileslps/lp-tile2.htm?tocpath=Setup%7C_____0)\nand these for installation of [Secrets Manager, Self-Hosted](https://docs.cyberark.com/Product-Doc/OnlineHelp/AAM-DAP/Latest/en/Content/HomeTilesLPs/LP-Tile2.htm).\n\nOnce Secrets Manager and the Secrets Manager CLI are running in the background, you are ready to start\nsetting up your Java app to work with our Secrets Manager Java API!\n\n### Using conjur-api-java with Conjur Open Source \n\nAre you using this project with [Conjur Open Source](https://github.com/cyberark/conjur)? Then we \n**strongly** recommend choosing the version of this project to use from the latest [Conjur OSS \nsuite release](https://docs.conjur.org/Latest/en/Content/Overview/Conjur-OSS-Suite-Overview.html). \nConjur maintainers perform additional testing on the suite release versions to ensure \ncompatibility. When possible, upgrade your Conjur version to match the \n[latest suite release](https://docs.conjur.org/Latest/en/Content/ReleaseNotes/ConjurOSS-suite-RN.htm); \nwhen using integrations, choose the latest suite release that matches your Conjur version. For any \nquestions, please contact us on [Discourse](https://discuss.cyberarkcommons.org/c/conjur/5).\n\n## Setup\nThe Secrets Manager Java API can be imported manually through building the source code locally, \nor by using a dependency configuration to import from Maven Central. Please refer to\nthe following instructions for your specific use case.\n\n### Using the Source Code\n\nYou can grab the library's dependencies from the source by using Maven **or** locally\nby generating a JAR file and adding it to the project manually.\n\nTo do so from the source using Maven, following the setup steps below:\n\n1. Create new Maven project using an IDE of your choice\n2. If you are using Maven to manage your project's dependencies, include the following\n   Secrets Manager API dependency snippet in your `pom.xml` under `\u003cproject\u003e`/`\u003cdependencies\u003e`:\n\n```xml\n    \u003cdependency\u003e\n      \u003cgroupId\u003ecom.cyberark.conjur.api\u003c/groupId\u003e\n      \u003cartifactId\u003econjur-api\u003c/artifactId\u003e\n      \u003cversion\u003e3.2.0\u003c/version\u003e\n    \u003c/dependency\u003e\n```\n\n_NOTE:_ Depending on what version of the Java compiler you have, you may need to update\nthe version. At this time, the `{version}` that we are targeting compatibility with is\nJava 8:\n\n```xml\n  \u003cproperties\u003e\n    \u003cmaven.compiler.source\u003e{version}\u003c/maven.compiler.source\u003e\n    \u003cmaven.compiler.target\u003e{version}\u003c/maven.compiler.target\u003e\n  \u003c/properties\u003e\n```\n\n3. Run `mvn install -DskipTests` in this repo's directory to install Secrets Manager API into your\n   local maven repository.\n\n### Using the Jarfile\n\nIf generating a JAR is preferred, you can build the library locally and add the dependency\nto the project manually by following the setup steps below:\n\n1. Clone the Secrets Manager Java API repo locally: `git clone {repo}`\n2. Go into the cloned repository with `cd conjur-api-java`\n3. Run `mvn package -DskipTests` to generate a JAR file. The output `.jar` files will be located\n   in the `target` directory of the repo\n\n_NOTE:_ The above command runs `mvn package` without running the integration tests, since\nthese require access to a Secrets Manager instance. You can run the integration tests with mvn package\nonce you finish the configuration. For more information on how to run the tests, take a look at\nour [Contributing](https://github.com/cyberark/conjur-api-java/blob/main/CONTRIBUTING.md) guide.\n\n4a. For Intellij, Follow the steps outlined [here](https://www.jetbrains.com/help/idea/library.html)\n    to add the SDK JAR files into the new app's project.\n4b. For Eclipse you `Right click project \u003e Build Path \u003e Configure Build Path \u003e Library \u003e Add External JARs`.\n4c. If you are working with the Maven CLI, you can manually install the `.jar` into your Maven.\n    repository by running the following (replacing `$VERSION` with the appropriate version\n    of the API):\n    ```sh-session\n    $ mvn org.apache.maven.plugins:maven-install-plugin:2.5.2:install-file \\\n        -Dfile=/path/to/api/repo/target/conjur-api-$VERSION.jar\n    ```\n    or\n    ```sh-session\n    $ mvn org.apache.maven.plugins:maven-install-plugin:2.5.2:install-file \\\n        -Dfile=/path/to/api/repo/target/conjur-api-$VERSION-with-dependencies.jar\n    ```\n    or\n    ```sh-session\n    $ mvn install:install-file -Dfile=/path/to/api/repo/target/conjur-api-$VERSION-with-dependencies.jar \\\n        -DgroupId=com.cyberark.conjur.api \\\n        -DartifactId=conjur-api \\\n        -Dversion=$VERSION \\\n        -Dpackaging=jar\n    ```\n\n### Using Maven Releases\n\nTo make use of tagged releases published to Maven, verify that you have the dependency \nadded to your `pom.xml`\n\n1. Add the following snippet to `pom.xml`\n```xml\n\u003cdependency\u003e\n  \u003cgroupId\u003ecom.cyberark.conjur.api\u003c/groupId\u003e\n  \u003cartifactId\u003econjur-java-api\u003c/artifactId\u003e\n  \u003cversion\u003ex.x.x\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n### Using Maven Snapshots\nTo make use of SNAPSHOTS, which are deployed following a nightly build, there are \nseveral steps required for configuring your project.\n\n\u003e Note: Snapshots contain the latest changes to `conjur-java-api`, but it is recommended\n\u003e to use the current stable release unless there is a significant update required by your\n\u003e project \n\n1. Add the following to your `settings.xml`\n```xml\n\u003cprofiles\u003e\n  \u003cprofile\u003e\n     \u003cid\u003eallow-snapshots\u003c/id\u003e\n        \u003cactivation\u003e\u003cactiveByDefault\u003etrue\u003c/activeByDefault\u003e\u003c/activation\u003e\n     \u003crepositories\u003e\n       \u003crepository\u003e\n         \u003cid\u003esnapshots-repo\u003c/id\u003e\n         \u003curl\u003ehttps://oss.sonatype.org/content/repositories/snapshots\u003c/url\u003e\n         \u003creleases\u003e\u003cenabled\u003efalse\u003c/enabled\u003e\u003c/releases\u003e\n         \u003csnapshots\u003e\u003cenabled\u003etrue\u003c/enabled\u003e\u003c/snapshots\u003e\n       \u003c/repository\u003e\n     \u003c/repositories\u003e\n   \u003c/profile\u003e\n\u003c/profiles\u003e\n```\n\nAlternatively, add the following to your list of repositories in `pom.xml`\n```xml\n\u003crepository\u003e\n  \u003cid\u003eoss.sonatype.org-snapshot\u003c/id\u003e\n  \u003curl\u003ehttp://oss.sonatype.org/content/repositories/snapshots\u003c/url\u003e\n  \u003creleases\u003e\n    \u003cenabled\u003efalse\u003c/enabled\u003e\n  \u003c/releases\u003e\n  \u003csnapshots\u003e\n    \u003cenabled\u003etrue\u003c/enabled\u003e\n  \u003c/snapshots\u003e\n\u003c/repository\u003e\n```\n\n2. In your `pom.xml`, verify that your `conjur-java-api` dependency includes `SNAPSHOT`\nin the version tag.\n```xml\n\u003cdependency\u003e\n  \u003cgroupId\u003ecom.cyberark.conjur.api\u003c/groupId\u003e\n  \u003cartifactId\u003econjur-java-api\u003c/artifactId\u003e\n  \u003cversion\u003ex.x.x-SNAPSHOT\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n### Using Other Dependency Management Configurations\nPlease refer to the instructions available on [Maven Central](https://search.maven.org/artifact/com.cyberark.conjur.api/conjur-api) \nand select a version for specific instructions on including the Secrets Manager Java API in your\nproject through Gradle, Kotlin, and more!\n\n## Configuration\n\nOnce the setup steps have been successfully run, we will now define the variables needed\nto make the connection between the new app and Secrets Manager. You can do this by setting\n[environment variables](#environment-variables), [system properties](#system-properties),\nor some combination of both.\n\n_NOTE:_ System properties will override enviroment values when both are defined for a\nvariable.\n\n### Environment Variables\n\nIn Secrets Manager and Conjur OSS, environment variables are mapped to configuration variables\nby prepending `CONJUR_` to the all-caps name of the configuration variable. For example,\n`appliance_url` is `CONJUR_APPLIANCE_URL`, `account` is `CONJUR_ACCOUNT` etc.\n\nThe following environment variables need to be included in the app's runtime environment in\norder use the Secrets Manager API if no other configuration is done (e.g. over system properties or\nCLI parameters):\n\n- `CONJUR_APPLIANCE_URL` - The URL of the Secrets Manager instance you are connecting to. When connecting to\n  Secrets Manager, Self-Hosted configured for high availability, this should be the URL of the master load balancer (if\n  performing read and write operations) or the URL of a follower load balancer (if performing\n  read-only operations).\n- `CONJUR_ACCOUNT` - Secrets Manager account that you are connecting to. This value is set during Secrets Manager deployment.\n- `CONJUR_AUTHN_LOGIN` - User/host identity\n- `CONJUR_AUTHN_API_KEY` - User/host API key (or password; see notes on `CONJUR_AUTHN_URL`)\n- `CONJUR_AUTHN_URL` - (optional) Alternate authentication endpoint. By default the client\n  uses the standard `\u003capplianceUrl\u003e/authn` for generic username and API key login flow.\n\n_Note:_ **If you use the default `CONJUR_AUTHN_URL` value or your `CONJUR_AUTHN_URL` ends with `/authn`,\nthe `CONJUR_AUTHN_API_KEY` is treated as a password otherwise `CONJUR_AUTHN_API_KEY` is treated as\nan API key.**\n\nFor example, you can specify the environment variables like so:\n\n```sh-session\nexport CONJUR_APPLIANCE_URL=https://conjur.myorg.com/api\nexport CONJUR_ACCOUNT=myorg\nexport CONJUR_AUTHN_LOGIN=host/myhost.example.com\nexport CONJUR_AUTHN_API_KEY=sb0ncv1yj9c4w2e9pb1a2s\n```\n\nor you could provide these at runtime to your jar:\n```sh-session\n$ CONJUR_APPLIANCE_URL=https://conjur.myorg.com/api \\\n  CONJUR_ACCOUNT=myorg \\\n  CONJUR_AUTHN_LOGIN=host/myhost.example.com \\\n  CONJUR_AUTHN_API_KEY=sb0ncv1yj9c4w2e9pb1a2s \\\n  java -jar myConjurClient.jar\n```\nIf you are using a host-based user like this example shows, you will need to add the host to Secrets Manager with the proper privileges in policy in order to know the appropriate\n`CONJUR_AUTHN_LOGIN` and `CONJUR_AUTHN_API_KEY` values.\n\n### System Properties\n\nThis API can also be configured using [Java system properties](https://docs.oracle.com/javase/tutorial/essential/environment/sysprop.html)\nYou can specify any portion (or all) of the configuration values this way. The advantage\nof this approach is that the values can be changed dynamically as needed. For example,\nthis snippet would let your client be able to use the API methods using properties defined\nfrom the CLI:\n```sh-session\njava -jar myConjurClient.jar \\\n     -DCONJUR_APPLIANCE_URL=https://conjur.myorg.com/api \\\n     -DCONJUR_ACCOUNT=myorg \\\n     -DCONJUR_AUTHN_LOGIN=host/myhost.example.com \\\n     -DCONJUR_AUTHN_API_KEY=sb0ncv1yj9c4w2e9pb1a2s\n```\n\nIf you are using Maven, you can also specify these proprerties on the CLI:\n\n```sh-session\nmvn exec:java \\\n     -DCONJUR_APPLIANCE_URL=https://conjur.myorg.com/api \\\n     -DCONJUR_ACCOUNT=myorg \\\n     -DCONJUR_AUTHN_LOGIN=host/myhost.example.com \\\n     -DCONJUR_AUTHN_API_KEY=sb0ncv1yj9c4w2e9pb1a2s \\\n     -Dexec.mainClass=\"com.myorg.client.App\"\n```\n\n_NOTE:_ When using properties to configure Secrets Manager APIs, be careful not to persist sensitive\nvalues (like the API key) in source-controlled property files!\n\n## Set Up Trust Between App and Secrets Manager\n\nBy default, the Secrets Manager appliance generates and uses self-signed SSL certificates. Without\ntrusting them, your Java app will not be able to connect to the Secrets Manager server over APIs\nand so you will need to configure your app to trust them. You can accomplish this by using\nthe [Client-level `SSLContext`](#client--level-trust) when creating the client or with a\n[JVM-level trust](#jvm--level-trust) by loading the Secrets Manager certificate into Java's CA\nkeystore that holds the list of all the allowed certificates for https connections.\n\n### Client-level trust\n\nWe can set up a trust between the client application and a Secrets Manager server using\nJava `javax.net.ssl.SSLContext`. This can be done from Java code during\nSecrets Manager class initialization.\n\nUsable in Kubernetes/OpenShift environment to setup TLS trust with Secrets Manager\nserver dynamically from the Kubernetes secret and/or configmap data.\n\n```java\nfinal String conjurTlsCaPath = \"/var/conjur-config/tls-ca.pem\";\n\nfinal CertificateFactory cf = CertificateFactory.getInstance(\"X.509\");\nfinal FileInputStream certIs = new FileInputStream(conjurTlsCaPath);\nfinal Certificate cert = cf.generateCertificate(certIs);\n\nfinal KeyStore ks = KeyStore.getInstance(\"JKS\");\nks.load(null);\nks.setCertificateEntry(\"conjurTlsCaPath\", cert);\n\nfinal TrustManagerFactory tmf = TrustManagerFactory.getInstance(\"SunX509\");\ntmf.init(ks);\n\nSSLContext conjurSSLContext = SSLContext.getInstance(\"TLS\");\nconjurSSLContext.init(null, tmf.getTrustManagers(), null);\n```\n\n### JVM-level trust\n\nFor a JVM-level trust between Secrets Manager and the API client, you need to load the Secrets Manager\ncertificate into Java's CA keystore that holds the list of all the allowed certificates\nfor https connections.\n\nFirst, we need to get a copy of this certificate, which you can get using `openssl`. Run the\nfollowing step from a terminal with OpenSSL that has access to Secrets Manager:\n\n```sh-session\n$ openssl s_client -showcerts -servername myconjurserver.com \\\n    -connect myconjusrserver.com:443 \u003c /dev/null 2\u003e /dev/null \\\n    | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' \u003e conjur.pem\n\n$ # Check that the certificate was properly retrieved. If you do not see this kind of output\n$ # ensure that you are providing OpenSSL the correct server information\n$ cat conjur.pem\n-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n```\nThis will save the certificate chain to a file called 'conjur.pem'. Since Java doesn't work\nnatively with the `pem` certificate encoding format, you'll need to convert it to the `der`\nformat:\n\n```sh-session\n$ openssl x509 -outform der -in conjur.pem -out conjur-default.der\n```\n\nNext, you'll need to locate the path to the JRE from the process environment running the Java\napp. In the case of Java 8 on most standard Linux distributions it's\n`/usr/lib/jvm/java-8-openjdk-amd64/jre`. We will export this path to `$JRE_HOME` for convenience.\nIf the file `$JRE_HOME/lib/security/cacerts` doesn't exist (you might need to be root to see it),\ndouble check that the `JRE_HOME` path is correct. Once you've found it, you can add the\nappliance's cert to Java's certificate authority keystore like this:\n\n```sh-session\n$ sudo -E keytool -importcert \\\n    -alias conjur-default \\\n    -keystore \"$JRE_HOME/lib/security/cacerts\" \\\n    -storepass changeit \\\n    -file ./conjur-default.der\n\nOwner: CN=myconjurserver.com\nIssuer: CN=myconjurserver.com, OU=Conjur CA, O=myorg\nSerial number: 9e930ced498d74b4faf98e6d4f9d90ebdebebd57\nValid from: Mon Mar 30 16:51:15 CDT 2020 until: Thu Mar 28 16:51:15 CDT 2030\nCertificate fingerprints:\n         SHA1: 7A:A3:78:22:50:03:52:C2:B5:3E:1D:98:48:26:82:71:18:FB:2E:26\n         SHA256: ED:77:BA:4A:81:EB:6C:26:E9:82:AC:75:51:99:9A:2F:76:D5:3C:A2:B4:8D:5D:87:EB:A6:01:49:FC:2F:28:FF\n...\nTrust this certificate? [no]:  yes\nCertificate was added to keystore\n\n$ # Make sure you do not see `keytool error: java.io.FileNotFoundException` error. If you do,\n$ # your addition of the cert did not work.\n```\n\n_Note:_ On macOS, your default Java may not be able to run this tool so you may need to install\nan alternate JDK like `openjdk`. You can find more info about this [here](https://docs.oracle.com/javase/8/docs/technotes/guides/install/mac_jdk.html)\nand [here](https://formulae.brew.sh/formula/openjdk).\n\nVerify the addition of the SSL key:\n```sh-session\n$ sudo -E keytool -list \\\n    -storepass changeit \\\n    -keystore $JAVA_HOME/lib/security/cacerts | grep conjur\nconjur-default, May 6, 2020, trustedCertEntry,\n```\n\nThere you have it! Now you are all configured to start leveraging the Secrets Manager Java API in\nyour Java program.\n\n## Authorization Examples\n\nAs mentioned in the [Configuration](#configuration) section, you can provide varying ways\nfor your app to authenticate against a Secrets Manager server. Generally environment variables are\nmost common but this isn't the only way. In addition to explicitly setting these environment\nvariables, you can do so by providing [properties](#system-properties), using the Credentials\nobject, or by providing an Authorization Token. Once you have chosen from one of the\npatterns below that works for you, you can now create a `Conjur` class instance values to\naccess Secrets Manager services and make RESTful API calls.\n\n_Note:_ **As mentioned before, if you use the default `CONJUR_AUTHN_URL` value or your\n`CONJUR_AUTHN_URL` ends with `/authn`, the `CONJUR_AUTHN_API_KEY` is treated as a password\notherwise `CONJUR_AUTHN_API_KEY` is treated as an API key.**\n\n### Environment Variables\n\n```bash\nexport CONJUR_ACCOUNT=\u003caccount specified during Secrets Manager setup\u003e\nexport CONJUR_APPLIANCE_URL=\u003cSecrets Manager endpoint URL\u003e\nexport CONJUR_AUTHN_LOGIN=\u003cuser/host identity\u003e\nexport CONJUR_AUTHN_API_KEY=\u003cuser/host API key or password - see notes about `CONJUR_AUTHN_URL`\u003e\n```\n```java\nimport com.cyberark.conjur.api.Conjur;\n\n// Configured using environment variables\nConjur conjur = new Conjur();\n// or using custom SSLContext setup as conjurSSLContext variable\nConjur conjur = new Conjur(conjurSSLContext);\n```\n\n### System Properties\n\n```sh-session\n$ java -jar myConjurClient.jar \\\n     -DCONJUR_ACCOUNT=\u003caccount specified during Secrets Manager setup\u003e \\\n     -DCONJUR_APPLIANCE_URL=\u003cSecrets Manager endpoint URL\u003e \\\n     -DCONJUR_AUTHN_LOGIN=\u003cuser/host identity\u003e \\\n     -DCONJUR_AUTHN_API_KEY=\u003cuser/host API key - see notes about `CONJUR_AUTHN_URL`\u003e\n```\n```java\nimport com.cyberark.conjur.api.Conjur;\n\n// Configured using system properties\nConjur conjur = new Conjur();\n// or using custom SSLContext setup as conjurSSLContext variable\nConjur conjur = new Conjur(conjurSSLContext);\n```\n\n### System Properties with Maven\n\n```sh-session\n$ mvn exec:java \\\n  -DCONJUR_ACCOUNT=\u003caccount specified during Secrets Manager setup\u003e \\\n  -DCONJUR_APPLIANCE_URL=\u003cSecrets Manager endpoint URL\u003e \\\n  -DCONJUR_AUTHN_LOGIN=\u003cuser/host identity\u003e \\\n  -DCONJUR_AUTHN_API_KEY=\u003cuser/host API key - see notes about `CONJUR_AUTHN_URL`\u003e \\\n  -Dexec.mainClass=\"com.myorg.client.App\"\n```\n```java\nimport com.cyberark.conjur.api.Conjur;\n\n// Configured using system properties\nConjur conjur = new Conjur();\n// or using custom SSLContext setup as conjurSSLContext variable\nConjur conjur = new Conjur(conjurSSLContext);\n```\n\n### Username and Password\n\n```bash\nexport CONJUR_ACCOUNT=\u003caccount specified during Secrets Manager setup\u003e\nexport CONJUR_APPLIANCE_URL=\u003cSecrets Manager endpoint URL\u003e\n```\n\n```java\nimport com.cyberark.conjur.api.Conjur;\n\n// Authenticate using provided username/hostname and password/API key. See notes about\n// `CONJUR_AUTHN_URL` regarding how 'password-or-api-key' is processed.\nConjur conjur = new Conjur('host/host-id', 'password-or-api-key');\n// or\nConjur conjur = new Conjur('username', 'password-or-api-key');\n// or using custom SSLContext setup as conjurSSLContext variable\nConjur conjur = new Conjur('username', 'password-or-api-key', conjurSSLContext);\n```\n\n### Credentials\n\n```bash\nexport CONJUR_ACCOUNT=\u003caccount specified during Secrets Manager setup\u003e\nexport CONJUR_APPLIANCE_URL=\u003cSecrets Manager endpoint URL\u003e\n```\n\n```java\nimport com.cyberark.conjur.api.Conjur;\nimport com.cyberark.conjur.api.Credentials;\n\n// Authenticate using a Credentials object. See notes about `CONJUR_AUTHN_URL`\n// regarding how 'password-or-api-key' is processed.\nCredentials credentials = new Credentials('username', 'password-or-api-key');\nConjur conjur = new Conjur(credentials);\n// or using custom SSLContext setup as conjurSSLContext variable\nConjur conjur = new Conjur(credentials, conjurSSLContext);\n```\n\n### Authorization Token\n\n```bash\nexport CONJUR_ACCOUNT=\u003caccount specified during Secrets Manager setup\u003e\nexport CONJUR_APPLIANCE_URL=\u003cSecrets Manager endpoint URL\u003e\n# Optional path for non-standard authenticators (e.g. `$CONJUR_APPLIANCE_URL/authn-k8s/myauthenticator`)\n# export CONJUR_AUTHN_URL=\"\u003cauthenticator authn url\u003e\"\n```\n\n```java\nimport com.cyberark.conjur.api.Conjur;\nimport com.cyberark.conjur.api.Token;\n\nToken token = Token.fromFile(Paths.get('path/to/conjur/authentication/token.json'));\nConjur conjur = new Conjur(token);\n// or using custom SSLContext setup as conjurSSLContext variable\nConjur conjur = new Conjur(token, conjurSSLContext);\n```\n\nAlternatively, use the `CONJUR_AUTHN_TOKEN_FILE` environment variable:\n```bash\nexport CONJUR_ACCOUNT=\u003caccount specified during Secrets Manager setup\u003e\nexport CONJUR_APPLIANCE_URL=\u003cSecrets Manager endpoint URL\u003e\n# Optional path for non-standard authenticators (e.g. `$CONJUR_APPLIANCE_URL/authn-k8s/myauthenticator`)\n# export CONJUR_AUTHN_URL=\"\u003cauthenticator authn url\u003e\"\nexport CONJUR_AUTHN_TOKEN_FILE=\"path/to/conjur/authentication/token.json\"\n```\n```java\nimport com.cyberark.conjur.api.Conjur;\nimport com.cyberark.conjur.api.Token;\n\nToken token = Token.fromEnv();\nConjur conjur = new Conjur(token);\n// or using custom SSLContext setup as conjurSSLContext variable\nConjur conjur = new Conjur(token, conjurSSLContext);\n```\n\n## Client APIs\n\nTo use the client, you will first create an instance of the client and then call methods\nto send requests to the Secrets Manager API. The most common use case is adding and retrieving\na secret from Secrets Manager, so we provide some sample code for this use case below.\n\n### Secrets Manager Client Instance (`com.cyberark.conjur.api.Conjur`)\n\nThe client can be instantiated with any of these methods:\n```java\nConjur client = Conjur();\nConjur client = Conjur(SSLContext sslContext);\nConjur client = Conjur(String username, String password);\nConjur client = Conjur(String username, String password, SSLContext sslContext);\nConjur client = Conjur(String username, String password, String authnUrl);\nConjur client = Conjur(String username, String password, String authnUrl, SSLContext sslContext);\nConjur client = Conjur(Credentials credentials);\nConjur client = Conjur(Credentials credentials, SSLContext sslContext);\nConjur client = Conjur(Token token);\nConjur client = Conjur(Token token, SSLContext sslContext);\n```\n\n_Note:_ **As mentioned before, if you use the default `CONJUR_AUTHN_URL` value or your\n`CONJUR_AUTHN_URL` ends with `/authn`, the `password` parameter is treated as a \"password\"\notherwise `CONJUR_AUTHN_API_KEY` is treated as an \"API key\".**\n\n### Variables (`client.variables()`)\n\n#### `void addSecret(String variableId, String secret)`\n\nSets a variable to a specific value based on its ID.\n\nExample:\n```java\nimport com.cyberark.conjur.api.Conjur;\n\nConjur conjur = new Conjur();\nconjur.variables().addSecret(VARIABLE_ID, VARIABLE_VALUE);\n```\n\n_NOTE:_ For a variable to be set, it first needs to be created by a policy in Secrets Manager\notherwise this operation will fail. To do so, you will need a policy that resembles\nthe one supplied in the [Configuration](#configuration) section above.\n\n#### `String retrieveSecret(String variableId)`\n\nRetireves a variable based on its ID.\n\nExample:\n```java\nimport com.cyberark.conjur.api.Conjur;\n\nConjur conjur = new Conjur();\nString secret = conjur.variables().retrieveSecret(\"\u003cVARIABLE_ID\u003e\");\n```\n\n#### `Map\u003cString, String\u003e retrieveBatchSecrets(String... variableIds)`\n\nRetrieves multiple variables in one request using the Conjur Batch Secret Retrieval API.\nPass variable IDs without the account/kind prefix (for example, `test/testVariable`).\n\nExample:\n```java\nimport com.cyberark.conjur.api.Conjur;\n\nimport java.util.Map;\n\nConjur conjur = new Conjur();\n\nMap\u003cString, String\u003e secrets = conjur.variables().retrieveBatchSecrets(\n    \"test/testVariable\",\n    \"test/var with spaces\"\n);\n\nString testVariable = secrets.get(\"test/testVariable\");\nString variableWithSpaces = secrets.get(\"test/var with spaces\");\n```\n\n### Resources (`client.resources()`)\n\n#### `List\u003cConjurResource\u003e listResources(ResourceQuery query)`\n\nLists resources visible to the authenticated identity. \n\nExample — list all resources:\n```java\nimport com.cyberark.conjur.api.Conjur;\nimport com.cyberark.conjur.api.ConjurResource;\nimport com.cyberark.conjur.api.ResourceQuery;\n\nimport java.util.List;\n\nConjur conjur = new Conjur();\n\nList\u003cConjurResource\u003e all = conjur.resources().listResources(ResourceQuery.all());\n```\n\nExample — list only variables whose ID contains \"db\", returning up to 10 starting at offset 0:\n```java\nimport com.cyberark.conjur.api.Conjur;\nimport com.cyberark.conjur.api.ConjurResource;\nimport com.cyberark.conjur.api.ResourceQuery;\n\nimport java.util.List;\n\nConjur conjur = new Conjur();\n\nResourceQuery query = ResourceQuery.builder()\n    .kind(\"variable\")\n    .search(\"db\")\n    .limit(10)\n    .offset(0)\n    .build();\n\nList\u003cConjurResource\u003e variables = conjur.resources().listResources(query);\n```\n\n#### `int countResources(ResourceQuery query)`\n\nReturns the count of resources matching the query without fetching the full resource list.\n\nExample — count only host resources:\n```java\nimport com.cyberark.conjur.api.Conjur;\nimport com.cyberark.conjur.api.ResourceQuery;\n\nConjur conjur = new Conjur();\n\nint hostCount = conjur.resources().countResources(\n    ResourceQuery.builder().kind(\"host\").build()\n);\n```\n\n## Jakarta REST (JAX-RS) Implementations\nThe Secrets Manager API client uses the Jakarta REST (formerly JAX-RS) standard to make requests to the Secrets Manager web services.\nIt is compatible with Jakarta EE environments and may not work in Java EE environments that still use the\nolder javax.ws.rs packages.\n\nSecrets Manager API uses Jersey as the default Jakarta REST implementation for client requests. While it is broadly compatible,\nsome application servers (e.g., JBoss EAP or WildFly) may require overriding the Jersey dependency in `pom.xml` to\navoid conflicts.\n\n## Troubleshooting\n\n### `error: package com.cyberark.conjur does not exist`\n\nThis is caused by Maven's (or your dependency resolution tooling) inability to find Secrets Manager\nAPIs. Please ensure that you have followed the [setup](#setup) section to properly install\nthis as a dependency.\n\n### `java.lang.NoClassDefFoundError: javax/xml/bind/JAXBException`\n\nThis is due to the lack of dependencies required for this API. You can add this to your `pom.xml`\nto work around this:\n```xml\n    \u003cdependency\u003e\n      \u003cgroupId\u003ejavax.xml.bind\u003c/groupId\u003e\n      \u003cartifactId\u003ejaxb-api\u003c/artifactId\u003e\n      \u003cversion\u003e2.3.1\u003c/version\u003e\n    \u003c/dependency\u003e\n```\n\n### SSL/TLS/Certificate Issues\n\nIf you don't properly install the Secrets Manager certificate into the Java keystore, you may encounter\nthe folowing errors:\n- `org.apache.cxf.interceptor.Fault: Could not send Message.`\n- `jakarta.ws.rs.ProcessingException: javax.net.ssl.SSLHandshakeException: SSLHandshakeException`\n- `javax.net.ssl.SSLHandshakeException: SSLHandshakeException`\n- `javax.net.ssl.SSLHandshakeException: PKIX path building failed`\n- `sun.security.validator.ValidatorException: PKIX path building failed`\n- `sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target`\n\nIf you encounter these errors, please ensure that you have followed [this section](#set-up-trust-between-app-and-conjur)\non how to install Secrets Manager's SSL cetificate into your Java keystore correctly. You should also\nensure that the SSL certificate was added to the correct `cacerts` file if you have multiple\nJDKs/JREs installed.\n\n## Contributing\n\nFor instructions on how to contribute, please see our [Contributing](https://github.com/cyberark/conjur-api-java/blob/main/CONTRIBUTING.md)\nguide.\n\n## License\n\nThis repository is licensed under Apache License 2.0 - see [`LICENSE`](LICENSE) for more details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcyberark%2Fconjur-api-java","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcyberark%2Fconjur-api-java","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcyberark%2Fconjur-api-java/lists"}