Was this helpful?

A most common mechanism used to secure traffic from Apigee Edge to your backend service is Client SSL. Client SSL provides authentication and encryption of all messages flowing over the network from Apigee Edge to your services.


For last-mile security, another option is to use outbound authentication, which requires an API proxy to present a credential to the backend service. For more information, see Last-mile security.

If your proxy target is a Node.js application, you can use the Node.js tls module to create secure connections to backend services. You make outgoing requests with the tls module the same way you would normally in Node.js. Basically, you need to add client-side keys and certificates (.pem files) to the resources/node directory and load them inside your script. For information on using the tls module and its methods, see the Node.js tls module documentation. For more information, see Understanding Edge support for Node.js modules.

Step 1: Generate client credentials

To configure client SSL for mutual authentication between Apigee Edge and your backend server, you require a public/private key pair and an X.509 certificate. The certificate can be issued by a certificate authority, or it can be self-signed by the private key that you generate. If you have access to a CA, follow instructions provided by your CA for generating keys and issuing certificates. If you do not have access to a CA, you can generate a self-signed certificate using one of the many publicly available free tools, such as openssl.

Supported key formats are:

  • PEM
  • DER
  • PKCS12
  • JKS (Can be imported directly without creating keystore--bypassing Step 2, below)

Apigee Edge supports key sizes up to 2048 bits.

Step 2: Create a JAR file containing your keystore

Create a JAR file with your key pair, certificate, and a manifest. The JAR file must contain the following files and directories:

  • /META-INF/descriptor.properties
  • myCert.pem
  • myKey.pem (Passphrase is optional)

Create a directory called /META-INF. Create a file called descriptor.properties in /META-INF with the following contents:

certFile={myCertificate}.pem
keyFile={myKey}.pem

Generate the JAR file containing your key pair and certificate:

$ jar -cf myKeystore.jar myCert.pem myKey.pem

Add descriptor.properties to your JAR file:

$ jar -uf myKeystore.jar META-INF/descriptor.properties

Step 3: Create keystore on Apigee Edge

You must upload the keystore file to an environment in your Apigee Edge organization, and then reference this file in your target endpoint configuration.

First check your environment for any existing keystores:

$ curl -u myname:mypass -X GET https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores
[ "freetrial" ]

Check the contents of the keystore. At a minimum, you should see a single server SSL certificate — the default certificate that Apigee Edge provides for free trial accounts.

$ curl -u myname:mypass https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/freetrial
{
  "certs" : [ "wildcard.apigee.net.crt" ],
  "keys" : [ "freetrial" ],
  "name" : "freetrial"
}

Create your own keystore in the environment:

Sample request:

$ curl -u myname:mypass https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores -H "Content-Type: text/xml" -d '<KeyStore name="myKeystore"/>'

Sample response:

{
  "certs" : [ ],
  "keys" : [ ],
  "name" : "myKeystore"
}

Step 4: Upload keystore JAR to Apigee Edge

Sample request:

$ curl -u myname:mypass -X POST -H "Content-Type: multipart/form-data" -F file="@myKeystore.jar" 'https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/{myKeystore}/keys?alias={key_alias}&password={key_pass}'

Verify that your keystore uploaded properly:

$ curl -u myname:mypass https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/myKeystore

Sample response:

{  "certs" : [ "myCertificate" ],
  "keys" : [ "myKey" ],
  "name" : "myKeystore"
}

You now have a private key available for mutual authentication between the specified environment in your organization on Apigee Edge and your backend service. If you are using a self-signed certificate instead of a certificate issued by a CA, then you must import the self-signed certificate to the trust store on the target server. To do so, refer to the instructions for the target server where your backend service is deployed.

Step 5: Configure TargetEndpoint for client SSL

In the TargetEndpoint configuration for your API proxy, add the following elements to the HTTPConnection configuration:

<ClientAuthEnabled>true</ClientAuthEnabled>
<KeyStore>myKeystore</KeyStore>
<KeyAlias>myKey</KeyAlias>

For example:

<TargetEndpoint name="default">
  <HTTPTargetConnection>
    <SSLInfo>
      <Enabled>true</Enabled>
      <ClientAuthEnabled>true</ClientAuthEnabled>
      <KeyStore>myKeystore</KeyStore>
      <KeyAlias>myKey</KeyAlias>
    </SSLInfo>
    <URL>https://myservice.com</URL>
  </HTTPTargetConnection>
</TargetEndpoint>

If no ciphers are specified, then all ciphers available for the JVM will be permitted.

To restrict ciphers, add the following elements to <SSLInfo>:

<Ciphers>
	<Cipher>TLS_RSA_WITH_3DES_EDE_CBC_SHA</Cipher>
	<Cipher>TLS_RSA_WITH_DES_CBC_SHA</Cipher>
</Ciphers>

If no protocols are specified, then all protocols available for the JVM will be permitted.

To restrict protocols, add the following elements to <SSLInfo>

<Protocols>
    <Protocol>TLSv1</Protocol>
    <Protocol>SSLv2Hello</Protocol>
</Protocols>

Step 6: Configure a trust store

To validate the backend server's SSL certificate, create and upload a trust store containing the server's certificate. Name the trust store, for example, myTruststore.

First, create an empty trust store in the environment.

$ curl -X POST -H "Content-Type: text/xml" -d \
'<KeyStore name="myTruststore"/>' \
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores \
-u myname:mypass

Then upload the certificate to the trust store you created.

Note that in this example, the file that you upload is not a JAR file. Instead, it is a PEM file.

$ curl -X POST -H "Content-Type: multipart/form-data" -F file="@trust.pem" \ "https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/myTruststore/certs?alias=myTruststore" \
-u myname:mypass 

Then, reference the uploaded trust store by its alias in SSLInfo:

<TargetEndpoint name="default">
  <HTTPTargetConnection>
    <SSLInfo>
      <Enabled>true</Enabled>
      <ClientAuthEnabled>true</ClientAuthEnabled>
      <KeyStore>myKeystore</KeyStore>
      <KeyAlias>myKey</KeyAlias>
      <TrustStore>myTruststore</TrustStore>
    </SSLInfo>
    <URL>https://myservice.com</URL>
  </HTTPTargetConnection>
</TargetEndpoint>

 

コメント

The text says:
"JKS (Can be imported directly without creating keystore--bypassing Step 2, below)"

But the text does not describe what it means to "import directly" the JKS. Please provide clear, complete instructions for how to "import JKS directly."

I am having the same issue. Can someone please clarify how exactly to import a JKS file?

Thanks Tom & Dino. We've got a ticket open to track down that information. Meantime, Tom, please post the question to http://stackoverflow.com/questions/tagged/apigee (and add the apigee tag). You're likely to get a faster response there. Best, Floyd

コメントを追加

Provide your email address if you wish to be contacted offline about your comment.
We will not display your email address as part of your comment.

We'd love your feedback and perspective! Please be as specific as possible.
Type the characters you see in this picture. (verify using audio)

Type the characters you see in the picture above; if you can't read them, submit the form and a new image will be generated. Not case sensitive.