feat(references): hashicorp vault integration

.cspell.json

@@ -141,6 +141,7 @@
         "Pluralsight",
         "PREEMPTIBLE",
         "printf",
+        "proxied",
         "proxiesremaining",
         "pushd",
         "queryparam",

CODEOWNERS

@@ -13,6 +13,7 @@
 /references/data-converters-shared-flow @tyayers
 /references/dutch-healthcare            @seymen
 /references/gcp-sa-auth-shared-flow     @danistrebel
+/references/hashicorp-vault-integration @yuriylesyuk
 /references/identity-facade             @joelgauci
 /references/java-callout                @omidtahouri
 /references/js-callout                  @seymen

README.md

@@ -59,6 +59,8 @@ further to fit a particular use case.
   popular API auth schemes
 - [reCAPTCHA enterprise](references/recaptcha-enterprise) - A reference for
   API protection against bot leveraging reCAPTCHA enterprise
+- [HashiCorp Vault Integration](references/hashicorp-vault-integration) - A reference for
+  integrating Apigee Proxies with HashiCorp Vault for EaaS services
 
 ## Tools
 

references/hashicorp-vault-integration/.gitignore

@@ -0,0 +1 @@
+**/edge.json

references/hashicorp-vault-integration/README.md

@@ -0,0 +1,47 @@
+<!-- markdownlint-disable MD033 -->
+
+# Apigee Proxy and HashiCorp Vault Integration
+
+This repository demonstrates an interaction between an Apigee API proxy and HashiCorp Vault. The operation of signing JWT token is delegated to the Vault server that is used as an EaaS (Encryption as a Service) solution. The private key thus is locked in the Vault server and never exposed. The public keys used for signature verification are proxied from the Vault server and returned in a canonical JWKS format.
+
+## Technical Setup
+
+The vault-facade proxy exposes two endpoints:
+
+- /jwks -- returns a collection of public keys so that a client can verify the signature;
+- /login -- models a typical authentication endpoint that returns a JWT ID token.
+
+The solution uses Java Callout to perform auxiliary operations of adding base64url encode operation, which is absent is Apigee templating functionality.
+
+The second operation is transforming a public key from a PEM format published by Vault to JWKS format, expected by a client application.
+
+<img src="images/vault-facade-proxy-diagram.png" alt="Vault Facade Diagram" width="800">
+
+## Deploy vs Mock Run
+
+The *pipeline.sh* script can be used to deploy the solution in both scenarios: a mocked Vault server and a real Vault server.
+
+The SKIP_MOCKING variable controls required changes and tweaks.
+
+Here is the list of environment variable to set up to configure setup environment:
+
+```sh
+export APIGEE_X_ORG=<apigee-org>
+export APIGEE_X_ENV=<apigee-env>
+
+export APIGEE_X_HOSTNAME=<apigee-hostname>
+
+export SKIP_MOCKING=Y
+
+export VAULT_HOSTNAME=<vault-hostname>
+export VAULT_PORT=<vault-port>
+export VAULT_SSL_INFO=''
+
+export VAULT_TOKEN=<vault-token>
+```
+
+Then run pipeline.sh script.
+
+```sh
+./pipeline.sh
+```

references/hashicorp-vault-integration/apigee-lib-install.sh

@@ -0,0 +1,39 @@
+#!/bin/sh
+# Copyright 2020 Google LLC
+#
+# 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.
+
+export APIGEE_LIB="$1"
+if [ -z "$APIGEE_LIB" ]; then
+    echo "No apigee lib directory is provided as an expected argument."
+    exit 1
+fi
+
+
+if [ ! -f "$APIGEE_LIB/message-flow-1.0.0.jar" ]; then
+    mkdir -p "$APIGEE_LIB"
+
+    curl  --output-dir "$APIGEE_LIB" -L -o message-flow-1.0.0.jar  https://github.com/apigee/api-platform-samples/blob/5b67fe2c3ab23514b67d458a19b63159a2e3f2ab/doc-samples/java-hello/lib/message-flow-1.0.0.jar?raw=true
+
+    mvn install:install-file -Dfile="$APIGEE_LIB/message-flow-1.0.0.jar" \
+    -DgroupId=com.apigee.edge -DartifactId=message-flow -Dversion=1.0.0 -Dpackaging=jar -DgeneratePom=true
+fi
+
+if [ ! -f "$APIGEE_LIB/expressions-1.0.0.jar" ]; then
+    mkdir -p "$APIGEE_LIB"
+
+    curl  --output-dir "$APIGEE_LIB" -L -o expressions-1.0.0.jar https://github.com/apigee/api-platform-samples/blob/5b67fe2c3ab23514b67d458a19b63159a2e3f2ab/doc-samples/java-hello/lib/expressions-1.0.0.jar?raw=true
+
+    mvn install:install-file -Dfile="$APIGEE_LIB/expressions-1.0.0.jar" \
+    -DgroupId=com.apigee.edge -DartifactId=expressions -Dversion=1.0.0 -Dpackaging=jar -DgeneratePom=true
+fi