Was this helpful?

To configure functionality that relies on public key infrastructure (SSL and SAML, for example) you need to create keystores and truststores that provide the necessary keys and X.509 digital certificates.

For information on implementing SSL, see Client-SSL to backend servers.

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)

A keystore can contain only one certificate.

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

Create keystore in an environment

You must upload the keystore file to an environment in your organization, and then reference this file in the element of SSL or SAML configuration.

First check your environment for any existing keystores:

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

A default keystore is provided for free trial organizations. You should see:

[ "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"
}

To create a different keystore in an 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"
}

Upload keystore JAR to Apigee Edge

Once you have created a named keystore in the environment, you can upload a keystore as a JAR file as follows:

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

This enables you to create your JAR files locally.

Verify that your keystore uploaded properly:

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

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 Apige Edge and your backend service. You can also use these keys for signing and encryption, when configuring SAML.

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.

For usage, see Client-SSL to backend servers and Authenticate and authorize using SAML 2.0.

TrustStores

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 the SSL or SAML configuration file.

For usage, see Client-SSL to backend servers and Authenticate and authorize using SAML 2.0.

Delete a keystore

You can delete a keystore with the following call:

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

If you delete and recreate a keystore, you must redeploy your API proxies. See Understanding deployment.

Get SSL certificate details

You can use the following API to view details about SSL certificates in the keystore, such as expiration date and issuer, 

First, obtain the name of the certificate in which you are interested. This example fetches information for the keystore called "freetrial".

$ 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"
}

Then, with this information, you can use this API to get the certificate details. The default response type for this API is JSON. Note that here, we ask for the response in XML. 

$ curl -u myname:mypass -H 'accept: application/xml' https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/freetrial/certs/wildcard.apigee.net.crt

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<CertsInfo>
    <CertInfo>
        <ExpiryDate>Wed, 23 Apr 2014 20:50:02 UTC</ExpiryDate>
        <Issuer>CN=Go Daddy Secure Certificate Authority - G2, OU=http://certs.godaddy.com/repository/, O=&quot;GoDaddy.com, Inc.&quot;, L=Scottsdale, ST=Arizona, C=US</Issuer>
        <Subject>CN=*.example.apigee.net, OU=Domain Control Validated</Subject>
        <SubjectAlternativeNames>
            <SubjectAlternativeName>*.example.apigee.net</SubjectAlternativeName>
            <SubjectAlternativeName>example.apigee.net</SubjectAlternativeName>
        </SubjectAlternativeNames>
        <isValid>No</isValid>
        <ValidFrom>Tue, 15 Apr 2014 09:17:03 UTC</ValidFrom>
        <Version>3</Version>
    </CertInfo>

    <Name>example.apigee.net.crt</Name>

</CertsInfo>

Get help

For help, see Apigee Customer Support.

Help or comments?

  • Something's not working: See Apigee Support
  • Something's wrong with the docs: Click Send Feedback in the lower right.
    (Incorrect? Unclear? Broken link? Typo?)