Spring Boot

Certification level: Certified

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

Benefits of storing secrets in Conjur

Storing secrets in Conjur provides the following benefits:

  • Provides one central location for storing and retrieving secrets for applications across all environments

  • Supports the management of static and dynamic secrets such as usernames and passwords for remote applications and resources

  • Provides credentials for external services like MySQL, PostgreSQL, Apache Cassandra, Couchbase, MongoDB, Consul, AWS, and more

Features of the plugin

The following features are available with the Spring Boot plugin:

  • API key or JWT authentication

  • Seamless integration of the Spring Boot plugin to existing or new Spring Boot applications to retrieve secrets from the CyberArk Vault using any of the following:

    • Minimal code changes by annotating with @ConjurPropertySource

    • No code change by dynamically mapping the secrets to credential variables annotated with @Value

    • An external properties file using the Spring Cloud Config Server as system properties:

      • Provides a central place to manage external properties for applications across all environments

      • Enables integration of any application running any language including Spring applications, whose environment provides mapping to property sources

      • Enables configuration management across the environment when migrating from dev to test and production, making sure that applications have everything they need to run when they migrate

      • Default storage in Git easily supports labeled versions of the configuration environment and is accessible to a wide range of tools for managing content

      • Configuration file security is supported through the encryption/decryption mechanism

Benefits

Moreover, using the Spring Cloud Config Server for your Conjur details, provides the following additional benefits:

Certification level: Certified

This integration is a Community contributed project, reviewed and tested by CyberArk and certified to use with Conjur. For more information about our certification levels, see our community guidelines.

Technical requirements

  • Java 8 or later

  • Spring Boot 2.x and 3.x

  • Spring Cloud 2021.x or 2022.x (for external property configuration)

  • Conjur SDK (Java) 4.1.0

  • Conjur API 5.1

Step 1: Set up the Spring Boot plugin

Step 1: Set up the 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 using a JAR file.

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 project's 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.

To import the plugin manually using a JAR, 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 JAR to the application's project:

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

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

Step 2: Set up trust between your 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:

    Create the environment variable, using the copied certificate as the value. For more information, see the Eclipse documentation.

    Follow the steps outlined in the IntelliJ documentation.

Step 2: Set up Conjur resources

Create resources in Conjur.

Make sure that the Conjur CLI is installed.

  • For JWT authentication, set up a JWT Authenticator, and note its service ID. Requires Conjur admin permissions.

    For details, see JWT Authentication.

  • Define a workload identity in Conjur that represents your workload. Note the workload's host id (full path). The workload definition depends on the method of authentication to be used: API key or JWT.

Step 3: Set up Conjur Cloud configuration parameters in Spring

You can set up Conjur details in your Spring environment locally, or you can set up receive property files from different storage mechanisms, such as GitHub, the file system backend, and the Vault backend, using the Spring Cloud Config Server plugin.

The default implementation of the Spring Cloud Config Server uses Git. The following examples use Git as a repository to store and access application properties.

  1. Set up Git.

    1. Check that Git is installed on the system by running the following command:

      $ git --version

      If Git is installed, the command returns the version number; otherwise, install Git before you continue.

    2. Create a directory in your local environment to store the .properties file used for the Conjur properties. You may want to create a .properties file for each environment, such as dev, test, and prod:

      $> mkdir example-repo
    3. In the repository directory, create a properties file containing the indicated properties.

      $> cd example-repo
      $ example-repo > vi exampleService.properties

      Enter the following properties based on the method you are using for authentication

      Parameter

      Description

      conjur.account

      Conjur account

      conjur.appliance-url

      Conjur URL

      conjur.authn-login

      Conjur user/host identity

      conjur.authn-api-key

      For API key authn only: Conjur API key of the host

      conjur.auth-token-file

      Conjur token, stored in a file

      conjur.cert-file

      OR

      conjur.ssl-certificate

      The path to the Conjur SSL certificate, or the content of the certificate

      Use only one of these.

      conjur.authenticator-id

      For JWT authn only: Conjur authenticator's service ID

      conjur.jwt-token-path

      For JWT authn only: Path to the JWT

      Example:
      exampleService.properties
      CONJUR.ACCOUNT = < Account to connect >
      CONJUR.APPLIANCE_URL = < Conjur URL >
      CONJUR.AUTH-TOKEN-FILE = < Conjur access token > 
      CONJUR.AUTHN_LOGIN = < User/host identity >
      CONJUR.CERT_FILE = <Path to certificate file>
      CONJUR.SSL_CERTIFICATE = <Certificate content>
    4. Initialize Git and commit the property files using the following command:

      $> cd example-repo
      $ example-repo> git init
      $ example-repo> git add .
      $ example-repo> git commit -m "Initial commit"

    Repeat these steps for each environment for which you want to create a .properties file.

    The local Git repository is only for development and test deployments. For production deployments, the repository must be secured and created in a remote location.

  2. Configure Spring Cloud Config Server:

    1. The Spring Cloud Config Server provides an HTTP resource-based API for external configuration by key/value pair or a .yml file @EnableConfigServer annotation is used to embed the server into the Spring Boot application.

      Enter the following

      @EnableConfigServer
      @SpringBootApplication
      public class ConfigServerApplication {
       
       public static void main(String[] args) {
         SpringApplication.run(ConfigServerApplication.class, args);
       }
      }
    2. Create an application.properties file in the /resource directory and copy the following into the file:

      server.port=8888
      spring.profiles.active=native
      spring.cloud.config.server.native.search-locations=file://${user.home}/conjur-repo
      spring.cloud.config.server.git.clone-on-start=true
      spring.application.name=conjur
    3. Enter the following dependencies in the pom.xml file:

      <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>

In Conjur, environment variables are mapped to configuration variables by prepending CONJUR_ to the all-caps name of the configuration property. For example: appliance_url is CONJUR_APPLIANCE_URL, account is CONJUR_ACCOUNT.

If no other configuration is done, such as over system properties or CLI parameters, include the following environment variables in the app's runtime environment to use the Spring Boot plugin.

Conjur environment variables

Name

Environment ID

Description

Conjur account

CONJUR_ACCOUNT

Conjur account to connect to

API key

CONJUR_AUTHN_API_KEY

For API key authn only: User/host API key/password

User/host identity

CONJUR_AUTHN_LOGIN

For API key authn only: User/host identity

Connection URL

CONJUR_APPLIANCE_URL

The Conjur URL

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).

SSL certificate path

OR
SSL certificate content

CONJUR_CERT_FILE

OR

CONJUR_SSL_CERTIFICATE

Path to certificate file or the certificate content

Use only one of these.

Path of the JWT token

CONJUR_JWT_TOKEN_PATH

For JWT authn only: Path of the JWT token

Conjur Authenticator ID

CONJUR_AUTHENTICATOR_ID

For JWT authn only: JWT Authenticator's service ID

Use the Spring Boot plugin

Add annotations to your Sprint Boot app so that it can connect to Conjur and retrieve secrets.

If you set up the Spring Cloud Config Server to provide the Conjur details, use the Spring Cloud @Value annotation.

Otherwise, use the Conjur-native or Spring @Value annotations to define the Conjur details.

If you configured the Spring Cloud Config Server to receive property files from an external storage mechanism, set up your code as follows:

@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) + "  " );

}}

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

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 Conjur.

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

Limitations

The Sprint Boot plugin does not support creating, updating, or removing secrets.