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:
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.
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:
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:
pom.xml
under <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:
git clone {repo}
cd conjur-spring-boot-sdk
mvn package -DskipTests
to generate a JAR file. The output .jar
files are located
in the target
directory 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.
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.
$ git --version
Should return the version of the Git, if already installed.
Property files can created one for each environment (Dev,Test, Prod)
$> mkdir example-repo
$> 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>
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"
Properties file can created for different environment from Dev to Prod exampleService-dev.properties exampleService-uat.properties exampleService-prod.properties
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>
There are two ways to use the plugin.
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;
}
}
@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
.