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). Alternatively, you can install the API Gateway on a locked down machine to act purely as an external CA. No license is required because only managedomain is running (with no Node Manager or API Gateway instances). This external CA machine holds the domain private key and certificate generated internally by managedomain. 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 machine (with 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 when adding the Node Manager or API Gateway to the domain.

To sign with a system-generated domain key on the first host in the domain, run the following command:

managedomain -i

This command performs the following:

There are no running Node Managers to call yet. These steps are equivalent to passing the --sign_with_generated option, which is the default. This means that the SSL certificates are signed with a system-generated domain private key and certificate.

To sign with a user-provided domain key on the first host in the domain, run the following example command:

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

This command performs the following:

To sign with an external CA on the first host in the domain, run the following command:

managedomain -i --sign_with_external_ca

This command performs the following:

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

managedomain uses the details saved in the file in the pending directory.

API Gateway as an external CA

You can use the --sign_with_external_ca option to take the CSR to an external CA such as Verisign. Alternatively, you can run the following command to generate the certificate on an isolated API Gateway installation:

managedomain --sign_csr --csr nodemanager.csr

This isolated API Gateway installation runs on a locked-down machine purely used to manage the domain private key and process CSRs (sign certificates).

This command performs the following:

• If you regenerate the domain.p12, or it does not exist in apigateway/groups/certs/private, generates the domain private key, CSR, and creates a self-signed certificate.

• Processes the CSR in the file you provided, and creates a certificate signed using the domain private key.

• Writes the certificate to a file on disk, and displays the filename so you can retrieve and copy to the host running managedomain and used to register the new Node Manager.

	Tip
	If wish to avoid regenerating a key and certificate, you can manually copy a user-provided domain 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

You can also specify the following options when signing with managedomain:

To sign with a system-generated domain key, run the following example command:

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

This command performs the following:

To sign with a user-provided domain key, run the following example command:

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

This command performs similar steps to signing with system-generated domain key except that it signs the CSR, and uses the user-provided key and certificate to sign the new Node Manager certificate.

To sign with an external CA, run the following example command:

managedomain -i --sign_with_external_ca

This command performs similar steps to signing with system-generated domain key except for the following:

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

managedomain uses the details saved in the file in the pending directory.

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

You can use the --is_admin option to specify whether the new Node Manager is a Admin Node Manager or a basic Node Manager. For more details, see the section called “Change the admin capabilities of a Node Manager”. See also the section called “Additional signing options”.

To sign with a system-generated domain key, run the following example command:

managedomain -c -n APIGateway1 -g Group1 --sign_with_generated

This command performs the following:

To sign with a user-provided domain key, run the following example command:

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

This command performs similar steps to signing with system-generated domain key except that it signs the CSR, and uses the user-provided key and certificate to sign the new API Gateway certificate.

Run the following example command on the new API Gateway host to sign with an external CA:

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

This command performs similar steps to signing with system-generated domain key except for the following:

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

managedomain uses the details saved in the file in the pending directory.

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

See also the section called “Additional signing options”.

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

managedomain --edit_host --host host1.com --sign_with_generated

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

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

In both cases, the command performs the following:

Important

If you remove admin capabilities from the first Admin Node Manager in your domain, you no longer have an Admin Node Manager with the internally generated domain private key. You must manually copy the apigateway/groups/certs and apigateway/groups/certs/private directories to another Admin Node Manager. You cannot remove admin capabilities on an Admin Node Manager that holds the domain private key.

When host1.com has an Admin Node Manager, to change admin capbilities from Admin Node Manager to basic 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 an Node Manager, to change admin capbilities from basic Node Manager to Admin Node Manager, run the following example command:

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

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

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

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

When host1.com has an Node Manager, to change admin capbilities from basic 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, the command performs the following:

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

managedomain uses the details saved in the file in the pending directory.

	Tip
	You can submit a Node Manager certificate even if some topology changes have occurred after the CSR is generated. In this case, you do not need to worry about removing admin rights from an Admin Node Manager and leaving the domain without an Admin Node Manager to sign CSRs. This is because the CSRs are signed by the external CA instead.

See also the section called “Additional signing options”.

To regenerate and sign with a system-generated key, run the folllowing command:

managedomain --regen_certs --sign_with_generated

Important

You must first regenerate on the host that holds the domain private key. When certificates are regenerated, you can select another Admin Node Manager host to hold the domain private key and certificate. You must delete the old domain private key and certificate from the other Admin Node Manager machine to prevent certificates being signed by two different domain keys. When you regenerate certificates on the first Admin Node Manager, you do not need a Node Manager or API Gateway running. When you regenerate certificates on subsequent hosts, the Admin Node Manager holding the domain private key must be running because it is used to sign the certificates. This applies only for system-generated domain private key.

This command performs the following:

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

To regenerate and sign with a specified user-generated key, run the folllowin example command:

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

This command performs the following:

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 and sign with an external CA, run the following command:

managedomain --regen_certs --sign_with_external_ca

This command performs the following:

When you have the signed certificates, run the following command

managedomain --submit_cert --cert cert.pem

This submits each certificate and updates the private key and certificate in the local Node Manager configuration, and the API Gateway certs.xml. managedomain does this using the details saved in apigateway/groups/certs/pending.

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 domain 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 domain 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 domain 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 “SSL private key and certificate locations”.

If you are using a system-generated domain private key and certificate, the domain private key and certificate are only on the first Admin Node Manager registered in the domain. You can manually copy this domain 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 may choose to copy the domain 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 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 domain 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.

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

	Tip
	For more details, see the OpenSSL user documentation.

If SSL certificates are signed by a system-generated domain private key and certificate, the domain private key and certificate are written to disk when the first Node Manager (always an Admin Node Manager) is created by managedomain.

The following files are created:

	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 domain private key and certificate are lost, you must recreate certificates for the entire domain before adding new Node Managers or API Gateways.

The domain private key files may 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 domain private key and sign the new SSL 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 domain certificate is copied into the API Gateway configuration because it is part of the SSL certificate chain.

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

The Node Manager private key and certificate chain are stored in the Node Manager configuration in apigateway/conf/fed. The private key is encrypted using the entity store passphrase.

Warning

When a Node Manager is being registered, the private key is written to disk into the following directory: apigateway/groups/certs/private/temp/nodemanager-id The temporary security sensitive files are removed when the Node Manager is fully registered in the domain topology. If an external CA is signing the certificate, these sensitive files may exist for a considerable time. This directory must have restricted access.

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 an API Gateway is being registered, the private key is written to disk into the following directory: apigateway/groups/certs/private/temp/instance-id The temporary security sensitive files are removed when the API Gateway is fully registered in the domain topology. If an external CA is signing the certificate, these sensitive files may exist for a considerable time. This directory must have restricted access.