Spring Boot

Integrate the Conjur Spring Boot Plugin with existing and new Spring Boot applications to retrieve secrets from Conjur.

The Spring Boot Plugin provides client-side support for externalized configuration of secrets in a distributed system. Using the Spring Boot Plugin, applications can retrieve application credentials and secrets stored in Conjur with minimal code changes to the existing Spring Boot application code.

View available versions at GitHub Releases or Maven Central.

Benefits of storing application secrets in the CyberArk Vault

The following features are available with the Spring Boot Plugin:

  • Provides one central location for storing and retrieving 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 - If you intend to run your Spring Boot-based applications in Kubernetes, you are encouraged to follow an alternative to the Spring Boot Plugin solution. CyberArk offers a Kubernetes-native 'Push To File' feature, described inSecrets Provider - init container/sidecar - Push-to-File mode.

Certification level

This repository is a Certified-level project. It's a Community contributed project, reviewed and tested by CyberArk and trusted to use with Conjur. For more information about our certification levels, see our community guidelines.

Features

The following features are available with the Spring Boot Plugin:

  • Retrieve a single secret by specifying the path to the secret in the CyberArk Vault

  • Retrieve multiple secrets by specifying the paths to the secrets in the CyberArk Vault

  • Retrieve secrets from the CyberArk Vault and initialize the Spring Boot environment with remote property sources

Limitations

The Spring Boot Plugin does not support creating, deleting, or updating secrets.

Technical requirements

  • Java 11

  • Conjur Open Source Suite (OSS) version 1.9 or later

  • Conjur Enterprise 12.5

  • Conjur SDK (Java) 4.0.0

  • Conjur API 5.1

Set up the Spring Boot Plugin with Conjur

Step 1: Prerequisite: Set up Conjur

Make sure that Conjur and the Conjur CLI are installed and that they are running in the background.

Step 2: Set up Spring Boot Plugin

This section describes how to set up the Spring Boot Plugin. You can use a dependency configuration that is imported from Maven Central, or you can import the Spring Boot Plugin manually by building the source code locally.

If you are using Maven to manage your project's dependencies, you can obtain the library's dependencies as follows:

  1. Create a new Maven project using an IDE of your choice.

  2. In the pom.xml:

    1. Under <project>/<dependencies>, include the following Spring Boot Plugin dependency snippet:

      <dependency>
               <groupId>com.cyberark</groupId>
               <artifactId>conjur-sdk-springboot</artifactId>
               <version>LATEST</version>
            </dependency>
    2. Update the Java version:

      <properties>
          <maven.compiler.source>{Java version}</maven.compiler.source>
          <maven.compiler.target>{Java version}</maven.compiler.target>
        </properties>
  3. Install the Spring Boot Plugin into your local Maven repository by running mvn install -DskipTests.

If generating a JAR is preferred, build the library locally and add the dependency to the project manually.

  1. Clone the Spring Boot Plugin repository locally: git clone {repo}.

  2. Go into the cloned repository with cd conjur-spring-boot-sdk.

  3. Run mvn package -DskipTests to generate a JAR file. The output JAR files are located in the target directory of the repository.

  4. Add the JARs to the application's project:

    • Intellij users: Add the SDK JAR files to the new app's project. For details, see the IntelliJ documentation.

    • Eclipse users: Right-click the project and select Build Path > Configure Build Path > Library > Add External JARs.

Step 3: Set up trust between the app and Conjur

By default, Conjur generates and uses self-signed SSL certificates. Without trusting them, the Java app cannot connect to Conjur using the Conjur APIs. You need to configure your app to trust them.

  1. Copy the .pem certificate created while setting up Conjur.

  2. Set up trusted Conjur self-signed certificates:

    1. In Eclipse, right -click Client Class and select Properties > Run... > New.

    2. Select the Configuration popup and click the Java app.

    3. In the Edit Launch Configuration properties window, select the Environment tab and click Add.

    4. In the New Environment Variable window, enter CONJUR_SSL_CERTIFICATE in the Name field and the copied certificate in the Value field.

    Follow the steps outlined in the IntelliJ documentation.

Step 4: Set up environment variables

Define the variables needed to make the connection between the Spring Boot Plugin and Conjur. You can do this by setting environment variables.

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

Conjur account

CONJUR_ACCOUNT

Account to connect

API key

CONJUR_AUTHN_API_KEY

User/host API key/password
Connection url

CONJUR_APPLIANCE_URL

Conjur instance to connect
User/host identity CONJUR_AUTHN_LOGIN User/host identity
SSL certificate path CONJUR_CERT_FILE Path to certificate file
SSL certificate content CONJUR_SSL_CERTIFICATE Certificate content

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.

  1. In Eclipse, select the Client Class and right-click Properties -> Run&Debug Setting-> New.

  2. From the Select Configuration popup, select the Java App.

  3. From the Edit Launch Configuration properties window, select the Environment tab and click Add.

  4. In the New Environment Variable window, enter the properties with the corresponding name and vale one at a time by clicking the Add button followed by Apply & Close:

    Name Description
    CONJUR_ACCOUNT

    The Account Id created during the Conjur setup. For example: myConjurAccount) as value.

    CONJUR_APPLIANCE_URL

    The URL of the Conjur instance to which you are connecting. When connecting to Conjur configured for high availability, this should be the URL of the Conjur cluster load balancer (if performing read and write operations) or the URL of a Follower load balancer (if performing read-only operations).

    CONJUR_AUTHN_LOGIN

    The "host/fileName1 created during Conjur 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 The <path /.der> (.der file is created during the Conjur setup)
    CONJUR_SSL_CERTIFICATE

    The details of the certificate

Follow the steps outlined in the IntelliJ documentation.

Use the Spring Boot Plugin

You can use the Spring Boot Plugin using the standard Spring @Value annotation, or using Conjur native annotations.

Spring Standard @Value annotation

The @ConjurPropertySource annotation allows you to specify the root of a policy to look up. The Spring Boot Plugin routes the lookup to Conjur through the Conjur Spring Boot SDK and an exposed REST API. 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 the CyberArk Vault.

Example use case: Given the following Vault path policy/my-application containing the database.password=mysecretpassword configuration data pair, 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

Conjur native annotations (custom annotation)

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 Vault. @ConjurValues allows you to retrieve multiple secrets from the Vault.

@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;
      }
 }

Contributing

We welcome contributions. Visit the Contributing Guide repo on GitHub.