Create and Sign Certificates for Production
In this article:
In this article:
Verify the Prerequisites
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:
Common Name (CN) Value
Note: If required, you can replace the wildcard for multiple domains using
subject alternative names(SANs).
Protects all public facing HTTPS traffic.
Note: Customers using a release prior to 22.214.171.124 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:
- foobaris the name of your Portal.
- mycompany.comis the PORTAL_DOMAIN variable defined in the configuration file (conf/portal.conf).
- SSH into the VM that is running API Portal.
- Navigate to the<installation>/utildirectory and execute the following command:sudo ./update-dispatcher FQDNWhere 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 isfoobar.mycompany.com:sudo ./update-dispatcher foobar.mycompany.comFrom 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).
- Yellowrelease 4.2.7 and higherTo 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
- Navigate to<installation>/certsand 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.
- Ensure that the certificate file is valid and that the certificate name matches your tenant URL. For example:foobar.mycompany.com.crt.
- Put the certificate file back in<installation>/certs.
- Re-run the dispatcher command with your FQDN:sudo ./update-dispatcher 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:
- 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> 2048openssl req -new -key <FILENAME>.key -passin pass:<PASSWORD> -out <FILENAME>.csr -days 365 -subj "/CN=XXXX"
- After the private key is created, store the key in a secure location.
- Send the CSR to a trusted CA authority to be signed.The CA authority returns a signed certificate.
- Create a PKCS12 container to hold a private key and signed certificate for consumption by our application. This PKCS 12 filemusthold one private key and one signed certificate and the passwordmustbe 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 theopensslcommand 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 theopensslcommand only once and define the same key file location for thePORTAL_HTTPD_SSL_KEYandPORTAL_TSSG_SSL_KEYvariables.
- 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:
- Edit theportal.conffile 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 inportal.conf, the values should be in single quotes.
- Save and exit the file.
- Run theportal.shfile 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:
- 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.
- Run theupdate-dispatcher.shcommand.
If you have a new Portal install or you have no certificate, perform the following procedure:
- Sinceupdate-dispatcher.shdoesn't support SAN, follow these steps to temporarily modifyupdate-dispatcher.shto provide an additionalsubject Alt Nameto include in this cert:
- Run thevi update-dispatcher.shcommand.
- Modifyfunction generate_ssl_certto addsubjectAltName(for example,subjectAltName=foobar.mycompany.com)
- Generate a CSR by going throughupdate-dispatcher.sh.
- Take the CSR to get a certificate signed by a CA.
- Replace the self-signed certificate (.crt) found in/<portal installation dir>/certs/with the signed certificate.
- Remember to roll back the temporary change made onupdate-dispatcher.sh.
Verifying the Install of a Self-Signed SAN Certificate
- On the browser, selectNot securein the address bar. The following is an example in Chrome:
- Expand the certificate, and look for the Subject Alternative Name, as shown in the below example:
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: