Oracle® Fusion Middleware
Part 2. Manage an API Gateway domain

You can use a third-party external CA to sign the SSL certificates (for example, Verisign). This is the typical approach that is recommended in a production environment. For more details, see your external CA user documentation.

In a development environment, you can install API Gateway on a locked down host to act as an external CA for testing purposes. No license is required because only managedomain is running. This external CA host stores a system-generated CA private key and certificate. You can use managedomain to process CSRs and output certificates.

In this scenario, the CSR file is generated by an API Gateway installation on another host (with a Node Manager and API Gateways running), and transported to the external CA installation out-of-band. The certificate file generated by the external CA is transported back out-of-band to the installation that created the CSR and where the new Node Manager or API Gateway is created. The certificate is specified to managedomain using the submit certificate option to complete Node Manager host registration or API Gateway creation.

To register the first Admin Node Manager in the domain and sign its SSL certificate with a system-generated CA key, run the following command:

managedomain -i

This command generates the CA private key, and a self-signed certificate. It also generates the Admin Node Manager private key and certificate signed by self-signed CA certificate. This command uses the --sign_with_generated option by default, which means that the SSL certificates are signed with a system-generated CA private key and certificate. There are no Node Managers running in the domain to call yet.

To register the first Admin Node Manager in the domain and sign its SSL certificate with a user-provided CA key, run the following example command:

managedomain -i --sign_with_user_provided --ca=/home/keys/test.p12

This command generates the Admin Node Manager private key and certificate signed by user-provided CA certificate.

To register the first Admin Node Manager in the domain and sign its SSL certificate with an external CA, run the following example command:

managedomain -i --sign_with_external_ca

This command generates the Admin Node Manager private key and the CSR for the certificate. It then prompts you to take your CSR file to your external CA and return with the signed certificate.

When you have the signed certificate, use the following command to submit the certificate and finish creating the Admin Node Manager configuration:

managedomain --submit_cert --cert cert.pem

API Gateway as external CA

In a production environment, you can use the --sign_with_external_ca option, and take the generated CSR to an external CA (for example, Verisign). Alternatively, in a development environment, you can run the following command to generate the certificate on an isolated API Gateway installation:

managedomain --sign_csr --csr nodemanager.csr

This command creates a certificate signed using the system-generated CA key. It writes the certificate to a file, displays the file name so you can retrieve and copy to the host running managedomain, and complete registration of the new Node Manager.

	Tip
	If you wish to avoid using a system-generated self-signed certificate, you can manually copy a user-provided CA private key and certificate to the following locations: apigateway/groups/certs/private/domain.p12 apigateway/groups/certs/private/domainkey.pem apigateway/groups/certs/domaincert.pem

In addition to the example commands already shown, you can specify the following options when using managedomain to sign SSL certificates for inter-process communication:

--subj_alt_name "DNS.1=name.oracle.com" --subj_alt_name 
"DNS.2=othername.oracle.com" --subj_alt_name "IP.1=10.142.1.2"

To add a Node Manager to the domain and sign its SSL certificate with a system-generated CA key, run the following command:

managedomain -a --sign_with_generated --anm_host my_anm.com

This command generates the Node Manager private key, obtains the Node Manager certificate from the Admin Node Manager, and completes registration of the new Node Manager in the domain.

To add a Node Manager to the domain and sign its SSL certificate with a user-provided CA key, run the following command:

managedomain -a --sign_with_user_provided --ca=/home/keys/test.p12 --anm_host my_anm.com

This command signs the new Node Manager certificate with the user-provided CA key and certificate, and completes registration of the new Node Manager in the domain.

To add a Node Manager to the domain and sign its SSL certificate with an external CA, run the following command:

managedomain -a --sign_with_external_ca --anm_host my_anm.com

This command performs similar steps to adding the first Admin Node Manager to the domain and signing with an external CA.

When you have the signed certificate, use the following command to submit the certificate and finish creating the Node Manager configuration:

managedomain --submit_cert --cert cert.pem

See also the section called “API Gateway as external CA”.

You can use the --is_admin option to specify whether the process is an Admin Node Manager or Node Manager. For more details, see the section called “Change a Node Manager to an Admin Node Manager”. See also the section called “Additional certificate generation options”.

To add an API Gateway instance to the domain and sign its SSL certificate with a system-generated CA key, run the following example command:

managedomain -c -n APIGateway1 -g Group1

This command uses the --sign_with_generated option by default.

To add an API Gateway instance to the domain and sign its SSL certificate with a user-provided CA key, run the following example command:

managedomain -c -n APIGateway1 -g Group1 --sign_with_user_provided --ca=/home/keys/test.p12

To add an API Gateway instance to the domain and sign its SSL certificate with an external CA, run the following example command:

managedomain -c -n APIGateway1 -g Group1 --sign_with_external_ca

This command performs similar steps to adding the first Admin Node Manager to the domain and signing with an external CA.

When you have the signed certificate, use the following command to submit the certificate and finish creating the API Gateway configuration:

managedomain --submit_cert --cert cert.pem

See also the section called “API Gateway as external CA” and the section called “Additional certificate generation options”.

When host1.com has an Admin Node Manager, to change admin capabilities from Admin Node Manager to Node Manager, run the following example command:

managedomain --edit_host --host host1.com

In this case, because host1.com is an Admin Node Manager and the --is_admin parameter is not passed, managedomain interprets this command as a change of capabilities from Admin Node Manager to Node Manager. This command uses the --sign_with_generated option by default.

When host1.com has a Node Manager, to change admin capabilities from Node Manager to Admin Node Manager, run the following example command:

managedomain --edit_host --host host1.com --is_admin

In both cases, the command generates and updates the private key and certificate in the local Node Manager configuration, and prompts you to reboot the Node Manager.

	Important
	To remove admin capabilities from the first registered Admin Node Manager, you must first move the following directories to another Admin Node Manager: apigateway/groups/certs apigateway/groups/certs/private Otherwise, you will not be able to remove admin capabilities. This only applies to a system-generated CA key.

When host1.com has an Admin Node Manager, to change admin capabilities from Admin Node Manager to Node Manager, run the following example command:

managedomain --edit_host --host 10.142.12.31 --sign_with_user_provided 
  --ca=/home/keys/test.p12

When host1.com has a Node Manager, to change admin capabilities from Node Manager to Admin Node Manager, run the following example command:

managedomain --edit_host --host host1.com --sign_with_user_provided --ca=/home/keys/test.p12 
  --is_admin

In both cases, the command performs the same steps described in the section called “Sign Node Manager certificate with system-generated CA key”, and the same conditions apply.

When host1.com has an Admin Node Manager, to change admin capabilities from Admin Node Manager to Node Manager, run the following example command:

managedomain --edit_host --host host1.com --sign_with_external_ca

When host1.com has a Node Manager, to change admin capabilities from Node Manager to Admin Node Manager, run the following example command:

managedomain --edit_host --host host1.com --sign_with_external_ca --is_admin

In both cases, this command performs similar steps to adding the first Admin Node Manager to the domain and signing with an external CA.

When you have the signed certificate, use the following command to submit the certificate and finish updating the Node Manager configuration:

managedomain --submit_cert --cert cert.pem

See also the section called “Additional certificate generation options”.

Important

You must first regenerate on the Admin Node Manager host that will hold the system-generated self-signed CA key. This may or may not be the same host that held the system-generated self-signed CA key before regeneration. If you select a different host to hold the CA private key and certificate, you must delete the old CA private key and certificate from the other Admin Node Manager host to prevent certificates being signed by two different CA keys. This must be done before regeneration.

To regenerate all certificates on a host and sign with a system-generated key, run the following command on each host in the domain:

managedomain --regen_certs

This command uses the --sign_with_generated option by default. It regenerates the CA private key and self-signed certificate, and private keys and certificates for the Admin Node Manager, Node Manager, and API Gateway instances on the host that the command was run.

After regenerating certificates, you must reboot the Node Manager and API Gateway instances on the local machine.

	Tip
	When you regenerate certificates on the first Admin Node Manager, a Node Manager or API Gateway does not need to be running. When you regenerate certificates on subsequent hosts, the Admin Node Manager holding the CA key must be running because it is used to sign the certificates. This applies only for system-generated CA keys.

To regenerate all certificates on a host and sign with a user-provided key, run the following example command on each host in the domain:

managedomain --regen_certs --sign_with_user_provided --ca=/home/users/qa.p12 
   --domain_passphrase foo

This command generates the private keys for the Node Manager and API Gateway instances and signs their certificates. After regenerating the certificates, you must then reboot the Node Manager and API Gateway instances on the local machine.

In this case, managedomain does not communicate with an Admin Node Manager when regenerating certificates. The order of hosts selected for certificate regeneration does not matter. An Admin Node Manager does not need to be running when certificates are regenerated or submitted.

To regenerate all certificates on a host and sign with an external CA, run the following command on each host in the domain:

managedomain --regen_certs --sign_with_external_ca

This command generates the private keys for the Node Manager and API Gateway instances. You are prompted to take the CSR files to your CA and return with the signed certificates.

When you have the signed certificates, run the following command for each certificate:

managedomain --submit_cert --cert cert.pem

After regenerating certificates, you must reboot the Node Manager and API Gateway instances on the local machine. In this case, managedomain does not talk to an Admin Node Manager when regenerating certificates. The order of hosts selected for certificate regeneration does not matter. An Admin Node Manager does not need to be running when certificates are regenerated or submitted.

If a system-generated CA private key is used, you can reset the passphrase on the command line as follows:

managedomain --change_domain_passphrase --old_passphrase "oldpass" --new_passphrase "newpass"

You can only run this command on the host that has the domain.p12 file. It does not affect any of the SSL certificates that have already been generated. If a new SSL certificate is to be generated (due to a new Node Manager or new API Gateway instance), the new domain passphrase must be provided to unlock the CA private key. This command modifies local files only. It does not communicate with any Node Managers in the domain.

By default, the SSL certificates are valid for 100 years. To change this value, edit the apigateway/skel/openssl.cnf file, and change the value of the default_days setting in the CA_default section.

[CA_default]
 .
 .
default_days = 36500
 .
 .

This setting applies to signing with a system-generated or user-generated CA key, or if you are using an API Gateway installation as an external CA. If you are using a third-party external CA, the CA decides on the expiry date.

When the default_days setting is changed, all newly signed certificates have the new expiry date. You do not need to reboot the Node Manager. However, you must regenerate certificates if you wish to modify the expiry date of existing certificates.

For more details, see the section called “Location of SSL private keys and certificates”.

This section explains how to create a backup Admin Node Manager for signing certificates, and how to set up an Admin Node Manager for signing certificates from a backup domain.p12 file.

Create backup Admin Node Manager for signing certificates

If you are using a system-generated CA private key and certificate, the CA private key and certificate are only on the first Admin Node Manager registered in the domain. You can manually copy this CA private key and certificate to other Admin Node Managers so that there is always a backup Admin Node Manager available to sign certificates. Alternatively, you can copy the CA private key and certificate only when there is a problem with the first Admin Node Manager (for example, it is no longer running).

To create a backup Admin Node Manager that can sign certificates, copy the following files from Admin Node Manager 1 to Admin Node Manager 2:

apigateway/groups/certs/domaincert.pem
apigateway/groups/certs/index.txt
apigateway/groups/certs/serial
apigateway/groups/certs/private/domain.p12
apigateway/groups/certs/private/domainkey.pem

You do not need to reboot Admin Node Manager 2 to be able to sign certificates. You can test the Admin Node Manager’s ability to sign certificates by taking down Admin Node Manager 1. Connect the client to Admin Node Manager 2, and add an API Gateway instance on any Node Manager that is running.

	Important
	You can decide when and if to copy the CA private key to limit the copies of this sensitive data. You must always backup the domain.p12 file after the registration of the first Admin Node Manager in some secure offline location.

Set up Admin Node Manager for signing certificates from a backup .p12

You can set up an Admin Node Manager for signing certificates from a backup domain.p12 file only. Perform the following steps:

1. Copy the domain.p12 file to apigateway/groups/certs/private/.

2. Create an apigateway/groups/certs/serial file with contents of 01.

3. Create an empty apigateway/groups/certs/index.txt file.

4. Parse domain.p12 into domainkey.pem and domaincert.pem (if these files were not backed up originally). For example, assuming a passphrase of fred for the CA private key:

   cd apigateway/groups/certs/private
   openssl pkcs12 -in domain.p12 -out ../domaincert.pem -nokeys -passin pass:fred
   openssl pkcs12 -in domain.p12 -out domainkey.pem -nocerts -passin pass:fred 
     -passout pass:fred

	Tip
	For more details, see the OpenSSL user documentation.

This section describes the locations of the SSL private keys and certificates for the CA, Node Manager, and API Gateway instances.

Location of CA private key and certificate

The location of the CA private key and certificate depends on how they are signed.

System-generated CA private key and certificate: If SSL certificates are signed by a system-generated CA private key and certificate, the CA private key and certificate are written to disk when the first Admin Node Manager is created by managedomain:

• CA private key: apigateway/groups/certs/private/domainkey.pem

• CA private key and certificate: apigateway/groups/certs/private/domain.p12

• CA certificate: apigateway/groups/certs/domaincert.pem

	Warning
	The files in apigateway/groups/certs/private are security sensitive because they contain the private key. This directory must have restricted access. These files are not copied to any other Node Manager, and must be backed up elsewhere. If the CA private key and certificate are lost, you must recreate certificates for the entire domain before adding new Node Managers or API Gateways.

The CA private key files can be encrypted by a passphrase. You must enter this with managedomain when creating a new Node Manager or API Gateway. This is used to unlock the CA private key and sign the new SSL certificate.

User-provided CA private key and certificate: If SSL certificates are signed by a user-provided key and certificate, the key and certificate are in a location managed by the user. A .p12 file containing the private key and certificate must be made available to managedomain when a new Node Manager or API Gateway is created. The CA certificate is copied into the API Gateway configuration because it is part of the SSL certificate chain.

External CA private key and certificate: If SSL certificates are signed by an external CA, the CA private key remains with the external third-party CA, or isolated API Gateway installation acting as an external CA. The CA certificate is copied to the API Gateway configuration because it is part of the SSL certificate chain.

apigateway/conf/fed

Location of API Gateway private key and certificate

The API Gateway private key and certificate chain are stored in the following directory:

apigateway/groups/group-2/instance-1/conf/certs.xml

The private key is encrypted with the group configuration passphrase.

Warning

When Node Managers and API Gateway instances are being registered, private keys are written in apigateway/groups/certs/private/temp/instance-id and nodemanager-id. Temporary security sensitive files are removed on completion. If an external CA is signing the certificate, sensitive files may exist for a considerable time, so this directory must have restricted access. You can encrypt this sensitive data using the --key_passphrase parameter.