The Spring boot conjur sdk plugin provides client-side support for externalized configuration of secrets in a distributed system. The existing and new Spring Boot Applications can retrieve secrets from Conjur by adding the plugin as dependency.There are two ways to integrate the plugin:
- With minimal code change by annotating existing or new POJO/Class with @ConjurPropertySource
- With no code change.
The Authentication parameters to connect to Conjur Server can be configured either as the System Env variables(while using @ConjurPropertySource annotation) or through external property source Spring Cloud Config Server.
Benefits of storing application secrets in Conjur
- Provides one central location to store and retrieve secrets for applications across all environments.
- Supports the management of static and dynamic secrets such as username and password for remote applications and resources.
- Provides credentials for external services like MySQL, PostgreSQL, Apache Cassandra, Couchbase, MongoDB, Consul, AWS, and more.
Note for Kubernetes users: Customers and users intending to run their Spring Boot based application in Kubernetes are encouraged to follow an alternative to the plugin solution described in this readme. Cyberark offers a Kubernetes native feature 'Push To File' described here. The documentation illustrates a process to assemble spring-boot application.properties files dynamically and avoids the need for any Java code changes in order to draw secrets directly from Conjur.
This repo is a Certified level project. It's a community contributed project that has been reviewed and tested by CyberArk and is trusted to use with Conjur Open Source, Conjur Enterprise, and Conjur Cloud. For more detailed information on our certification levels, see our community guidelines.
The following features are available with the Spring Boot Plugin:
- Seamless integration of the spring boot conjur plugin to exisitng or new Spring Boot application to retireve secrets from CyberArk Conjur with miniaml code change by annotating with @ConjurPropertySource or no code change (dynamic mapping of secrets to credential variables annotated with @Value.
- Externalize the properties using the Spring cloud Config Server or as System Property
- API authentication
The Spring Cloud Config Conjur plugin does not support creating, updating or removing secrets
| Technology | Version |
|---|---|
| Java | 8+ |
| Conjur OSS | 1.9+ |
| Conjur Enterprise | 12.5+ |
| Conjur Cloud | |
| ConjurSDK(Java) | 4.1.0 |
| Conjur API | 5.1 |
| Spring Cloud | 2021.x and 2022.x |
| Spring Boot | 2.x and 3.x |
The following are prerequisites to using the Spring Boot Plugin.
Conjur (OSS or Enterprise) and the Conjur CLI are installed in the environment and running in the background. If you haven't yet done so, follow the instructions for installing OSS or Enterprise.
Once Conjur and the Conjur CLI are running in the background, you can start setting up your Spring Boot application to work with our Conjur Spring Boot Plugin.
You can import the Conjur Spring Boot Plugin manually by building the source code locally or using a dependency configuration to import from Maven Central. For information about your specific use case, see the following instructions.
You can grab the library's dependencies using Maven:
- Create a new Maven project using an IDE of your choice.
- If you are using Maven to manage your project's dependencies, include the following
Spring Boot Plugin dependency snippet in your
pom.xmlunder<project>/<dependencies>:
<dependency>
<groupId>com.cyberark</groupId>
<artifactId>conjur-sdk-springboot</artifactId>
<version>LATEST</version>
</dependency>
View available versions at Github Releases or Maven Central.
NOTE: Depending on the Java compiler version you have, you may need to update the version. At this time, we are targeting compatibility with Java 11:
<properties>
<maven.compiler.source>{version}</maven.compiler.source>
<maven.compiler.target>{version}</maven.compiler.target>
</properties>Run mvn install -DskipTests in this repository's directory to install the Spring Boot Plugin into your local Maven repository.
If generating a JAR is preferred, build the library locally and add the dependency to the project manually:
- Clone the Spring Boot Plugin repository locally:
git clone {repo} - Go into the cloned repository with
cd conjur-spring-boot-sdk - Run
mvn package -DskipTeststo generate a JAR file. The output.jarfiles are located in thetargetdirectory of the repository.
4a. For Intellij, follow the steps outlined here to add the SDK JAR files to the new app's project.
4b. For Eclipse, right click project > Build Path > Configure Build Path > Library > Add External JARs.
By default, Conjur generates and uses self-signed SSL certificates. Without trusting them, the Java app cannot connect to the Conjur server using the Conjur APIs. You need to configure your app to trust them.
- Copy the .pem certificate created while setting up the Conjur.
- Select the Client Class in Eclipse then right-click and select Properties-> Run&Debug Setting-> New.
- Select Configuration popup and click the Java app.
- In the Edit Launch Configuration properties window, select the Environment Tab and click Add.
- In the New Environment Variable window, enter 'CONJUR_SSL_CERTIFICATE' in the Name field and the copied certificate in the Value field.
- Spring Cloud Config provides server-side and client-side support for externalized configuration in a distributed system. * Config Server provides a central place to manage external properties for applicaiton across all environments. Best * Can be integrated with any application running any language including Spring applicaiton as Spring Environment provides mapping to the \n property sources. * Configuration can be managed across the enviornment while migrating from dev to test and to production, to make sure that applicaitons have\n everything they need to run when they migrate. * Default storage is git, so it easily supports labeled versions of configuration environment as well as being accessible to a wide range of tooling for managing the content * Support for configuration file security through the encryption/decryption mechanism
Setting up the Config Server involves two step process, installing the Server and Client
The Spring Cloud Config Server can be integrated with different storage mechanism like GitHub, File System Backend, Conjur Backend etc,to access Property files from. The default implementation of the Spring Cloud Config Server uses Git. In this documentation Git Backend has been used as an repository to store and acces the application properties. Below are the steps to follow to integrate Spring Cloud Config Server with Git Repository.
Below are the steps to create a .properties file and to initialize the Git Repository.
- Check if git is installed on the sytem with the below command, if not download Git here
$ git --version
Should return the version of the Git, if already installed.
- Create a folder in local environment, to store the .properties file that will be used by the application
Property files can created one for each environment (Dev,Test, Prod)
$> mkdir example-repo
- Change to the directory and create a properties file
$> cd example-repo
$ example-repo > vi exampleService.properties
Enter the below properties in the exampleService.properties
exampleService.properties
CONJUR.ACCOUNT = <Account to connect>
CONJUR.APPLIANCE_URL = <Conjur instance to connect>
CONJUR.AUTHN_LOGIN = <User /host identity>
CONJUR.API_KEY = <User/host API Key/password>
CONJUR.AUTHN_TOKEN_FILE = <Path to token file containing API key> -optional
CONJUR.CERT_FILE = <Path to certificate file>
CONJUR.SSL_CERTIFICATE = <Certificate content>
- Initializing the Git
The below commands will be used to initialize Git in the configuration folder and commit the property files to the Git
$> cd example-repo
$ example-repo> git init
$ example-repo> git add .
$ example-repo> git commit -m "Initial commit"
- Creating property file for different environment
Properties file can created for different environment from Dev to Prod exampleService-dev.properties exampleService-uat.properties exampleService-prod.properties
- The local Git repository is created only for Dev/Test deployment. To work on the Production deployment, Repository needs to be more secured
and created in remote location.
Spring Cloud Config Server provides a HTTP resource based API for extenral configuration by Key/Value pair or .yml file @EnableConfigServer annotation will be used to embed the server into the Spring Boot Application
@EnableConfigServer
@SpringBootApplication
public class ConfigServerApplication {
public static void main(String[] args) {
SpringApplication.run(ConfigServerApplication.class, args);
}
}
bootstrap.properties
server.port= <port to connect to the server>
spring.profiles.active= <environment dev/stage/test/prod>
spring.cloud.config.server.native.search-locations= <location of the storage where the configuration file is maintained,
by default its Git>
spring.cloud.config.server.git.clone-on-start= <specify 'true' to refresh the config server on server startup>
spring.application.name=<point to the properties file for that particular application>
Following dependency needs to be included for Spring Cloud Config Server to be started
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-starter-config</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-config-server</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-actuator</artifactId>
</dependency>
Conjur OSS
Once the setup steps are successfully run, define the variables needed to make the connection between the plugin and Conjur. You can do this by setting Conjur Properties or Environment variables.
The following configuration properties can be set in the standard spring-boot configuration files, application.properties or application.yml:
| Parameter name | Description |
|---|---|
| conjur.account | CyberArk Conjur Account |
| conjur.appliance-url | CyberArk Conjur Appliance URL |
| conjur.authn-login | CyberArk Conjur User /host identity |
| conjur.authn-api-key | CyberArk Conjur API KEY of the host |
| conjur.auth-token-file | CyberArk Conjur Token, stored in a file |
| conjur.cert-file | CyberArk Conjur SSL Certificate path |
| conjur.ssl-certificate | CyberArk Conjur SSL Certificate Content |
In Conjur,environment variables are mapped to configuration variables by prepending CONJUR_ to the all-caps name of the configuration variable.
For example:appliance_url is CONJUR_APPLIANCE_URL, account is CONJUR_ACCOUNT.
If no other configuration is done (e.g. over system properties or CLI parameters), include the following environment variables in the app's runtime environment to use the Spring Boot Plugin.
| Name | Environment ID | Description | API KEY | JWT |
|---|---|---|---|---|
| Conjur Account | CONJUR_ACCOUNT | Account to connect | Yes | Yes |
| API key | CONJUR_AUTHN_API_KEY | User/host API Key/password | Yes | No |
| Connection url | CONJUR_APPLIANCE_URL | Conjur instance to connect | Yes | Yes |
| User/host identity | CONJUR_AUTHN_LOGIN | User /host identity | Yes | No |
| SSL Certificate Path | CONJUR_CERT_FILE | Path to certificate file | Yes | Yes |
| SSL Certificate Content | CONJUR_SSL_CERTIFICATE | Certificate content | Yes | Yes |
Only one CONJUR_CERT_FILE and CONJUR_SSL_CERTIFICATE is required. There are two variables to allow the user to specify the path to a certificate file or provide the certificate data directly in an environment variable.
Conjur Enterprise
Once the setup steps are successfully run, define the variables needed to make the connection between the plugin and Conjur. You can do this by setting Conjur Properties or [Environment variables](#environment-variables).The following configuration properties can be set in the standard spring-boot configuration files, application.properties or application.yml:
| Parameter name | Description |
|---|---|
| conjur.account | CyberArk Conjur Account |
| conjur.appliance-url | CyberArk Conjur Appliance URL |
| conjur.authn-login | CyberArk Conjur User /host identity |
| conjur.authn-api-key | CyberArk Conjur API KEY of the host |
| conjur.auth-token-file | CyberArk Conjur Token, stored in a file |
| conjur.cert-file | CyberArk Conjur SSL Certificate path |
| conjur.ssl-certificate | CyberArk Conjur SSL Certificate Content |
| conjur.authenticator-id | CyberArk Conjur authenticator ID |
| conjur.jwt-token-path | CyberArk Conjur Path of the JWT Token |
| conjur.mapping-path | CyberArk Conjur Mapping Path |
In Conjur,environment variables are mapped to configuration variables
by prepending CONJUR_ to the all-caps name of the configuration variable.
For example:appliance_url is CONJUR_APPLIANCE_URL, account is CONJUR_ACCOUNT.
If no other configuration is done (e.g. over system properties or CLI parameters), include the following environment variables in the app's runtime environment to use the Spring Boot Plugin.
| Name | Environment ID | Description | API KEY | JWT |
|---|---|---|---|---|
| Conjur Account | CONJUR_ACCOUNT | Account to connect | Yes | Yes |
| API key | CONJUR_AUTHN_API_KEY | User/host API Key/password | Yes | No |
| Connection url | CONJUR_APPLIANCE_URL | Conjur instance to connect | Yes | Yes |
| User/host identity | CONJUR_AUTHN_LOGIN | User /host identity | Yes | No |
| SSL Certificate Path | CONJUR_CERT_FILE | Path to certificate file | Yes | Yes |
| SSL Certificate Content | CONJUR_SSL_CERTIFICATE | Certificate content | Yes | Yes |
| Path of the JWT Token | CONJUR_JWT_TOKEN_PATH | Path of the JWT Token | No | Yes |
| Conjur authenticator ID | CONJUR_AUTHENTICATOR_ID | Conjur authenticator ID | No | Yes |
| Conjur MAPPING PATH | CONJUR_MAPPING_PATH | Conjur Mapping PATH | Yes | Yes |
Only one CONJUR_CERT_FILE and CONJUR_SSL_CERTIFICATE is required. There are two variables to allow the user to specify the path to a certificate file or provide the certificate data directly in an environment variable.
Conjur Cloud
Once the setup steps are successfully run, define the variables needed to make the connection between the plugin and Conjur. You can do this by setting Conjur Properties or Environment variables.
The following configuration properties can be set in the standard spring-boot configuration files, application.properties or application.yml:
| Parameter name | Description |
|---|---|
| conjur.account | CyberArk Conjur Account |
| conjur.appliance-url | CyberArk Conjur Appliance URL |
| conjur.authn-login | CyberArk Conjur User /host identity |
| conjur.authn-api-key | CyberArk Conjur API KEY of the host |
In Conjur, environment variables are mapped to configuration variables by prepending CONJUR_ to the all-caps name of the configuration variable.
For example:appliance_url is CONJUR_APPLIANCE_URL, account is CONJUR_ACCOUNT.
If no other configuration is done (e.g. over system properties or CLI parameters), include the following environment variables in the app's runtime environment to use the Spring Boot Plugin.
| Name | Environment ID | Description | API KEY | JWT |
|---|---|---|---|---|
| Conjur Account | CONJUR_ACCOUNT | Account to connect | Yes | Yes |
| API key | CONJUR_AUTHN_API_KEY | User/host API Key/password | Yes | No |
| Connection url | CONJUR_APPLIANCE_URL | Conjur instance to connect | Yes | Yes |
| User/host identity | CONJUR_AUTHN_LOGIN | User /host identity | Yes | No |
- Select the Client Class in Eclipse, then right click Properties -> Run&Debug Setting-> New.
- In the Select Configuration popup, click the Java App.
- In the Edit Launch Configuration properties window, select the Environment Tab and click Add.
- In the New Environment Variable window, enter the properties with the corresponding name and vale one at a time by clciking the Add button followed by Apply & Close.
- Enter CONJUR_ACCOUNT in the Name field and the Account Id created during the Conjur OSS setup. For example: myConjurAccount) as value.
- CONJUR_APPLIANCE_URL is the URL of the Conjur instance to which you are connecting. When connecting to Conjur Enterprise, configure for high availability by including the URL of the master load balancer (if performing read and write operations) or the URL of a follower load balancer (if performing read-only operations).
- CONJUR_AUTHN_LOGIN in the Name field and the host/fileName1 created during the Conjur OSS setup. For example: host/<file name where grant permission is defined for the user/userName (for whom the access is granted in fileName1).
- CONJUR_CERT_FILE in the Name field and the <path /.der> (.der file created during the Conjur OSS setup.
- CONJUR_SSL_CERTIFICATE in the Name field and the details of the certificate in the Value field.
- CONJUR_JWT_TOKEN_PATH in the Name field and the JWT token path (Only required for JWT)
- CONJUR_AUTHENTICATOR_ID in the Name field and the Conjur authenticator ID (Only required for JWT)
- For IntelliJ, set up trusted Conjur self-signed certs by following the steps outlined here.
There are two ways to use the plugin.
- @Value annotation and an optional conjur.properties file that enables the mapping of secret names.
- @ConjurValue and @ConjurValues, which are Conjur native annotations (custom annotations) that enable individual and bulk secret retrieval.
The @ConjurPropertySource annotation allows you to specify the root of a policy to look up. The Spring Boot Plugin routes the look up to Conjur through the Conjur Spring Boot SDK and a REST API we expose. Using @ConjurPropertySource in conjunction with @Configuration classes is required. The names of secrets, passwords, and user IDs all remain as originally specified. You can fetch Conjur managed secrets using a standard @Value annotation. By adding an optional file with the name conjur.properties in a Spring Boot classloader discoverable location (<a path>/resources/), you can map the names of secrets as specified in the application code to the names stored in CyberArk Conjur.
Example use case: Given the following Conjur path policy/my-application containing this configuration data pair database.password=mysecretpassword, the following @Configuration class uses @ConjurPropertySource to contribute policy/my-application to the environment's set of PropertySources.
@Configuration
@ConjurPropertySource("policy/my-application/")
@ConjurPropertySource("policy/my-other-application/")
@ConjurPropertySource(value={"policy/my-application/", "policy/my-other-application/"}, name="")
public class AppConfig {
@Autowired
Environment env;
@Value("${database.password}")
private byte[] password;
@Bean
public TestBean testBean() {
TestBean testBean = new TestBean();
testBean.setPassword(password);
return testBean;
}
}
Conjur Properties (conjur.properties)
conjur.mapping.database.password=MyConjurOraclePassword
The @ConjurValue and @ConjurValues annotations are intended for new Spring Boot applications. Injecting @ConjurValue
into your Spring Boot code allows you to retrieve a single secret from the CyberArk Conjur. @ConjurValues allows you to retrieve multiple secrets from the CyberArk Conjur.
@Configuration
public class AppConfig {
@ConjurValue("policy/my-application/database.password")
private byte[] password;
@ConjurValues({"policy/my-application/db.userName","policy/my-application/db.password","policy/my-application/db.name"})
private byte[] secrets;
@Bean
public TestBean testBean() {
TestBean testBean = new TestBean();
testBean.setPassword(password);
return testBean;
}
}
##Option 3: Spring Cloud @value Annotation
@SpringBootApplication
public class ConjurSpringCloudPluginTest implements CommandLineRunner{
private static Logger logger = LoggerFactory.getLogger(ConjurSpringCloudPluginTest.class);@Value("${test1}")
private byte[] pass1;
@Value("${test2}")
private byte[] pass2;
@Value("${test3}")
private byte[] pass3;
@Autowired
ApplicationContext appContext;
public static void main(String[] args) {
SpringApplication.run(ConjurSpringCloudPluginTest.class, args);
}
public void run(String... args) throws Exception {
logger.info("By Using Standard Spring annotation --> " + new String(pass1) + " " );
logger.info("By Using Standard Spring annotation --> " + new String(pass2) + " " );
logger.info("By Using Standard Spring annotation --> " + new String(pass3) + " " );
}}
We welcome contributions of all kinds to this repository. For instructions on how to get started and descriptions of our development workflows, see our contributing guide.
Copyright (c) 2022 CyberArk Software Ltd. All rights reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
For the full license text see LICENSE.