{"id":3370,"date":"2025-04-11T14:11:34","date_gmt":"2025-04-11T21:11:34","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/azure-sdk\/?p=3370"},"modified":"2025-04-11T14:11:34","modified_gmt":"2025-04-11T21:11:34","slug":"introducing-spring-cloud-azure-starter-key-vault-jca-streamlined-tls-and-mtls-for-spring-boot","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/azure-sdk\/introducing-spring-cloud-azure-starter-key-vault-jca-streamlined-tls-and-mtls-for-spring-boot\/","title":{"rendered":"Introducing Spring Cloud Azure Starter Key Vault JCA: Streamlined TLS and mTLS for Spring Boot"},"content":{"rendered":"

We\u2019re excited to unveil Spring Cloud Azure Starter Key Vault Java Crypto Architecture (JCA)<\/strong>, a new addition to the Spring Cloud Azure family, arriving with version 5.21.0<\/strong>. Designed for Spring Boot 3.1+<\/strong>, this starter applies the Spring SSL Bundles<\/strong> abstraction and the JCA Provider for Azure Key Vault<\/strong> to simplify secure communication in your Spring Boot applications. Whether you\u2019re enabling TLS for your server or setting up mutual TLS (mTLS) for client-server authentication, this starter integrates Azure Key Vault\u2019s certificate management with Spring\u2019s modern security framework.<\/p>\n

In this blog post, we dive into the starter\u2019s capabilities and demonstrate its usage with practical examples for enabling embedded server TLS, securing RestTemplate<\/code>, securing WebClient<\/code>, and configuring mTLS communication. Let\u2019s get started!<\/p>\n

What is Spring Cloud Azure Starter Key Vault JCA?<\/h2>\n

The Spring Cloud Azure Starter Key Vault JCA combines the power of Spring Boot\u2019s SSL Bundles (introduced in Spring Boot 3.1) with Azure Key Vault\u2019s JCA provider. This integration allows developers to use certificates stored in Key Vault directly within Spring applications, eliminating the complexity of traditional keystore management seen in older configurations. For example, Securing Spring Boot applications based on older version<\/a>. For a deeper dive into Spring SSL Bundles, see Spring SSL Bundles<\/a>.<\/p>\n

Get started<\/h2>\n

Add the following dependency to your pom.xml<\/code> file:<\/p>\n

<dependency>\r\n    <groupId>com.azure.spring<\/groupId>\r\n    <artifactId>spring-cloud-azure-starter-keyvault-jca<\/artifactId>\r\n    <version>5.21.0<\/version>\r\n<\/dependency><\/code><\/pre>\n
Complete the following steps to prepare the Azure resources:<\/p>\n
    \n
  1. Create two self-signed certificates in two Key Vault resources by following the steps at Add a self-signed certificate to Key Vault<\/a>. The certificate names are server<\/code> and client<\/code>, respectively. Assume that keyvault1<\/code> stores the server<\/code> certificate and keyvault2<\/code> stores the client<\/code> certificate.<\/li>\n
  2. Create a Service Principal for accessing Key Vault by following the steps at Create a Service Principal<\/a>.<\/li>\n
  3. Grant role Key Vault Certificate User<\/code> to the Service Principal for each Key Vault instance by following the steps at Role assignment<\/a>.<\/li>\n<\/ol>\n
    Note:\nEnvironment variables prefixed with KEY_VAULT_SSL_BUNDLES<\/code> represent the connection information for your Key Vault instances and Service Principal.<\/p><\/blockquote>\n
    Enable embedded server TLS<\/h2>\n
    Secure inbound HTTP calls for the embedded server. The embedded server applies the Key Vault SSL Bundle to enable Server TLS and that applies to all web servers supported by Spring Boot.<\/p>\n
    Update your application.yml<\/code> file:<\/p>\n
    spring:\r\n  application:\r\n    name: ssl-bundles-server\r\n  ssl:\r\n    bundle:\r\n      keyvault:\r\n        tlsServerBundle:\r\n          key:\r\n            alias: server\r\n          keystore:\r\n            keyvault-ref: keyvault1\r\n  cloud:\r\n    azure:\r\n      keyvault:\r\n        jca:\r\n          vaults:\r\n            keyvault1:\r\n              endpoint: ${KEY_VAULT_SSL_BUNDLES_KEYVAULT_URI_01}\r\n              profile:\r\n                tenant-id: ${KEY_VAULT_SSL_BUNDLES_TENANT_ID}\r\n              credential:\r\n                client-id: ${KEY_VAULT_SSL_BUNDLES_CLIENT_ID}\r\n                client-secret: ${KEY_VAULT_SSL_BUNDLES_CLIENT_SECRET}\r\nserver:\r\n  ssl:\r\n    bundle: tlsServerBundle<\/code><\/pre>\n
    Secure RestTemplate<\/h2>\n
    Secure outbound HTTP calls with RestTemplate<\/code> using a Key Vault SSL Bundle.<\/p>\n
      \n
    1. Update your application.yml<\/code> file:\n
      spring:\r\nssl:\r\n  bundle:\r\n    keyvault:\r\n      tlsClientBundle:\r\n        truststore:\r\n          keyvault-ref: keyvault1\r\ncloud:\r\n  azure:\r\n    keyvault:\r\n      jca:\r\n        vaults:\r\n          keyvault1:\r\n            endpoint: ${KEY_VAULT_SSL_BUNDLES_KEYVAULT_URI_01}\r\n            profile:\r\n              tenant-id: ${KEY_VAULT_SSL_BUNDLES_TENANT_ID}\r\n            credential:\r\n              client-id: ${KEY_VAULT_SSL_BUNDLES_CLIENT_ID}\r\n              client-secret: ${KEY_VAULT_SSL_BUNDLES_CLIENT_SECRET}<\/code><\/pre>\n<\/li>\n
    2. Update your RestTemplate<\/code> configuration to set the Key Vault SSL Bundle:\n
      @Bean\r\nRestTemplate restTemplateWithTLS(RestTemplateBuilder restTemplateBuilder, SslBundles sslBundles) {\r\n  return restTemplateBuilder.sslBundle(sslBundles.getBundle(\"tlsClientBundle\")).build();\r\n}<\/code><\/pre>\n<\/li>\n<\/ol>\n
      Then you can use bean restTemplateWithTLS<\/code> to access the HTTPS resource owned by app ssl-bundles-server<\/code>.<\/p>\n
      Secure WebClient<\/h2>\n
      Secure outbound HTTP calls with WebClient<\/code> using a Key Vault SSL Bundle.<\/p>\n
        \n
      1. Update your application.yml<\/code> file according to the configuration of the Secure RestTemplate<\/code> scenario.<\/li>\n
      2. Update your WebClient<\/code> bean configuration to apply the Key Vault SSL Bundle:\n
        @Bean\r\nWebClient webClientWithTLS(WebClientSsl ssl) {\r\n  return WebClient.builder().apply(ssl.fromBundle(\"tlsClientBundle\")).build();\r\n}<\/code><\/pre>\n<\/li>\n<\/ol>\n
        Then you can use bean webClientWithTLS<\/code> to access the HTTPS resource owned by app ssl-bundles-server<\/code>.<\/p>\n
        Enable mTLS communication<\/h2>\n
        Set up mTLS for two-way authentication between client and server.<\/p>\n
        Server side<\/h3>\n
        Update your application.yml<\/code> file to trust the client certificates in Key Vault keyvault2<\/code>, and enable the client authentication:<\/p>\n
        spring:\r\n  application:\r\n    name: ssl-bundles-server\r\n  ssl:\r\n    bundle:\r\n      keyvault:\r\n        tlsServerBundle:\r\n          key:\r\n            alias: server\r\n          keystore:\r\n            keyvault-ref: keyvault1\r\n          truststore:\r\n            keyvault-ref: keyvault2\r\n  cloud:\r\n    azure:\r\n      keyvault:\r\n        jca:\r\n          vaults:\r\n            keyvault1:\r\n              endpoint: ${KEY_VAULT_SSL_BUNDLES_KEYVAULT_URI_01}\r\n              profile:\r\n                tenant-id: ${KEY_VAULT_SSL_BUNDLES_TENANT_ID}\r\n              credential:\r\n                client-id: ${KEY_VAULT_SSL_BUNDLES_CLIENT_ID}\r\n                client-secret: ${KEY_VAULT_SSL_BUNDLES_CLIENT_SECRET}\r\n            keyvault2:\r\n              endpoint: ${KEY_VAULT_SSL_BUNDLES_KEYVAULT_URI_02}\r\n              profile:\r\n                tenant-id: ${KEY_VAULT_SSL_BUNDLES_TENANT_ID}\r\n              credential:\r\n                client-id: ${KEY_VAULT_SSL_BUNDLES_CLIENT_ID}\r\n                client-secret: ${KEY_VAULT_SSL_BUNDLES_CLIENT_SECRET}\r\nserver:\r\n  ssl:\r\n    bundle: tlsServerBundle\r\n    client-auth: NEED<\/code><\/pre>\n
        Client side<\/h3>\n
        Complete the following steps:<\/p>\n
          \n
        1. Update your application.yml<\/code> file to provide keystore for client authentication in Key Vault keyvault2<\/code>:\n
          spring:\r\nssl:\r\n  bundle:\r\n    keyvault:\r\n      mtlsClientBundle:\r\n        key:\r\n          alias: client\r\n        for-client-auth: true\r\n        keystore:\r\n          keyvault-ref: keyvault2\r\n        truststore:\r\n          keyvault-ref: keyvault1\r\ncloud:\r\n  azure:\r\n    keyvault:\r\n      jca:\r\n        vaults:\r\n          keyvault1:\r\n            endpoint: ${KEY_VAULT_SSL_BUNDLES_KEYVAULT_URI_01}\r\n            profile:\r\n              tenant-id: ${KEY_VAULT_SSL_BUNDLES_TENANT_ID}\r\n            credential:\r\n              client-id: ${KEY_VAULT_SSL_BUNDLES_CLIENT_ID}\r\n              client-secret: ${KEY_VAULT_SSL_BUNDLES_CLIENT_SECRET}\r\n          keyvault2:\r\n            endpoint: ${KEY_VAULT_SSL_BUNDLES_KEYVAULT_URI_02}\r\n            profile:\r\n              tenant-id: ${KEY_VAULT_SSL_BUNDLES_TENANT_ID}\r\n            credential:\r\n              client-id: ${KEY_VAULT_SSL_BUNDLES_CLIENT_ID}\r\n              client-secret: ${KEY_VAULT_SSL_BUNDLES_CLIENT_SECRET}<\/code><\/pre>\n<\/li>\n
        2. Register another RestTemplate<\/code> bean for mTLS connection, and the same if you use WebClient<\/code>:\n
          @Bean\r\nRestTemplate restTemplateWithMTLS(RestTemplateBuilder restTemplateBuilder, SslBundles sslBundles) {\r\n  return restTemplateBuilder.sslBundle(sslBundles.getBundle(\"mtlsClientBundle\")).build();\r\n}\r\n\r\n\/\/ or you can use WebClient instead\r\n@Bean\r\nWebClient webClientWithMTLS(WebClientSsl ssl) {\r\n  return WebClient.builder().apply(ssl.fromBundle(\"mtlsClientBundle\")).build();\r\n}<\/code><\/pre>\n<\/li>\n<\/ol>\n
          Now you can use beans restTemplateWithMTLS<\/code> or webClientWithMTLS<\/code> to access the HTTPS resource owned by app ssl-bundles-server<\/code>.<\/p>\n
          Feedback<\/h2>\n
          Your feedback and contributions are always welcome on StackOverflow<\/a> or GitHub<\/a>.<\/p>\n
          Resources<\/h2>\n
          To learn more about Spring Cloud Azure, visit the following links:<\/p>\n