Create and Sign Certificates for Production

In this article:
apip43
In this article:
3
Verify the Prerequisites
Review your DNS entries and make sure the values match the prerequisites listed in Configure Your DNS Server.
Important Portal Certificates
API Portal exposes services publicly over HTTPS. Before going into production, ensure that the following two certificates are signed to protect your services:
Service Name
Common Name (CN) Value
Usage
dispatcher
CN=*.domain
Note
: If required, you can replace the wildcard for multiple domains using
subject alternative names
(SANs).
Protects all public facing HTTPS traffic.
apim
CN=
apim
-ssg.domain
Note
: Customers using a release prior to 4.2.5.1 may have a PORTAL_TENANT_ID value that is different than the 'apim' value.
Protects the OTK token HTTPS traffic.
Signing Portal Certificate
To use a Portal certificate:
The example uses the following values:
  • foobar
    is the name of your Portal.
  • mycompany.com
    is the PORTAL_DOMAIN variable defined in the configuration file (
    conf/portal.conf)
    .
  1. SSH into the VM that is running API Portal.
  2. Navigate to the
    <installation>/util
    directory and execute the following command:
    sudo ./update-dispatcher.sh FQDN
    Where FQDN is your fully qualified domain name that combines the value of your tenant ID with your domain. As shown in the following example, the FQDN is
    foobar.mycompany.com
    :
    sudo ./update-dispatcher.sh foobar.mycompany.com
    From this input, the script will look for the cert (
    foobar.mycompany.com
    .crt) and key (
    foobar.mycompany.com
    .pem) associated to the FQDN in
    /<portal installation dir>/certs/
    . If not found, the script will generate a CSR with the FQDN using the pem file(key).
  3. To generate the Portal certificate, fill in the prompt with the following inputs:
    • Organization Name
    • Organizational Unit Name
    • City or Locality Name
    • State or Province Name
    • Country Name (2-letter code)
    • Email Address
  4. Navigate to
    <installation>/certs
    and send the newly generated CSR file (
    foobar.mycompany.com.csr
    ) to a trusted CA authority to be signed.
    The CA authority returns a signed certificate with the extension .crt.
  5. Ensure that the certificate file is valid and that the certificate name matches your tenant URL. For example:
    foobar.mycompany.com.crt
    .
  6. Put the certificate file back in
    <installation>/certs
    .
  7. Re-run the dispatcher command with your FQDN:
    sudo ./update-dispatcher.sh foobar.mycompany.com
Signing the APIM Portal Certificate
If you cannot get an already signed certificate from your Certificate Authority (CA), then you can follow this procedure to sign the APIM Portal certificate. The APIM Portal certificate (for example,
apim.example.com
) should also be signed by the CA authority key.
To generate the key and Certificate Signing Request (CSR), follow these steps:
  1. To generate the key and Certificate Signing Request (CSR), execute the following commands using OpenSSL and substitute
    <FILENAME>
    and
    <PASSWORD>
    accordingly:
    openssl genrsa -des3 -out <FILENAME>.key -passout pass:<PASSWORD> 2048
    openssl req -new -key <FILENAME>.key -passin pass:<PASSWORD> -out <FILENAME>.csr -days 365 -subj "/CN=XXXX"
  2. After the private key is created, store the key in a secure location.
  3. Send the CSR to a trusted CA authority to be signed.
    The CA authority returns a signed certificate.
  4. Create a PKCS12 container to hold a private key and signed certificate for consumption by our application. This PKCS 12 file
    must
    hold one private key and one signed certificate and the password
    must
    be protected. Use the following command to create a PKCS12 container:
    openssl pkcs12 -export -inkey <FILENAME>.key -in <FILENAME>.crt -out <FILENAME>.p12 -passin pass:<PASSWORD> -passout pass:<PASSWORD>
    If you want to use a different key for the HTTPD service (the dispatcher service) and the APIM service (the Ingress), run the
    openssl
    command in this step twice to generate two different p12 files.
    If you want to use the same key for both the HTTPD service and the APIM service, run the
    openssl
    command only once and define the same key file location for the
    PORTAL_HTTPD_SSL_KEY
    and
    PORTAL_TSSG_SSL_KEY
    variables.
  5. The PKCS12 (p12) file(s) should be signed by CA authority key in production. To configure CA Services to use the new keys and certificates, perform the following steps:
    1. Edit the
      portal.conf
      file that is located in the
      <installer_dir>/conf/
      directory by adding the following configuration to the file:
      Note:
      The
      ~
      ,
      $
      ,
      `
      , and
      &
      character cannot be used in any of the key passwords. If special characters are used in
      portal.conf
      , the values should be in single quotes.
      PORTAL_HTTPD_SSL_KEY='/home/qa/dispatcher_new.p12' PORTAL_HTTPD_SSL_KEY_PASS='[email protected]#%^*()_-+=' PORTAL_TSSG_SSL_KEY='/home/qa/tssg_new.p12' PORTAL_TSSG_SSL_KEY_PASS='[email protected]#%^*()_-+='
    2. Save and exit the file.
    3. Run the
      portal.sh
      file to update the containers in the background.
Getting a Signed SAN Certificate Installed
This section is only applicable to customers who are using multi-public facing host names for Portal - that is, Portal being accessible in the internal and external network that has two or multiple domains.
CA Portal currently does not support multi-tenancy. However, for exempted customers (who previously implemented solution or underwent a technical assessment by CA), a SAN Certificate can be used to address multiple host names for a signed certificate versus using a wildcard certificate.
If you already have a signed certificate, perform the following procedure:
  1. Prepare a CA signed SAN cert (for example,
    foobar.mycompany.com.crt
    ) and key (
    foobar.mycompany.com.pem
    ) in the
    /<portal installation dir>/certs/
    directory.
  2. Run the
    update-dispatcher.sh
    command.
If you have a new Portal install or you have no certificate, perform the following procedure:
  1. Since
    update-dispatcher.sh
    doesn't support SAN, follow these steps to temporarily modify
    update-dispatcher.sh
    to provide an additional
    subject Alt Name
    to include in this cert:
    1. Run the
      vi update-dispatcher.sh
      command.
    2. Modify
      function generate_ssl_cert
      to add
      subjectAltName
      (for example,
      subjectAltName
      =
      foobar.mycompany.com
      )
      Certificates Configuration.png
  2. Generate a CSR by going through
    update-dispatcher.sh
    .
  3. Take the CSR to get a certificate signed by a CA.
  4. Replace the self-signed certificate (.crt) found in
    /<portal installation dir>/certs/
    with the signed certificate.
  5. Run
    update-dispatcher.sh
    .
  6. Remember to roll back the temporary change made on
    update-dispatcher.sh
    .
Verifying the Install of a Self-Signed SAN Certificate
  1. On the browser, select
    Not secure
    in the address bar. The following is an example in Chrome:
    Certificates Configuration 2.png
  2. Expand the certificate, and look for the Subject Alternative Name, as shown in the below example:
    Certificates Configuration 4.png
Other Trust Relationships for Portal Certificates
A few services are exposed on the PSSG and Ingress service endpoints that are publicly accessible but have self-signed certificates. These services are not meant to be accessible through a web browser. The services are protected through 2-way SSL (mutual authentication) and have an explicit trust between the caller and the service. The trust is established during provisioning. Although these services are discoverable, users cannot access them because these services do not have the proper certificate to access the endpoints.
PSSG and Ingress services are accessible on the following endpoints which are not accessible for API Portal:
PSSG service:
  • sso.<domain>
  • sync.<domain>
  • enroll.<domain>
Ingress service:
  • analytics.<domain>
  • broker.<domain>