Contents
- Overview
- How SSL certificates are signed in a domain
- Add the first Admin Node Manager to the domain
- Add a Node Manager to the domain
- Add an API Gateway instance to the domain
- Change the admin capabilities of a Node Manager
- Change the domain SSL certificate
- Admin Node Manager backup and disaster recovery
- SSL private key and certificate locations
The Admin Node Manager (ANM) is the central administration server for an API Gateway domain, and is responsible for performing management operations across the domain. The Node Manager (NM) on each machine manages all the local API Gateways on that machine, regardless of the group they are in. This includes collecting monitoring information, managing dynamic settings, deploying configuration, and so on.
In addition to managing the local API Gateways on its host, the Admin Node Manager communicates with the Node Managers
in the domain to perform management operations across the domain. In this architecture, the Node Managers only
communicate with the Admin Node Manager, and the API Gateway Manager, Policy Studio, and managedomain
tools
connect to the Admin Node Manager. For more details on Admin Node Manager architecture, see the API Gateway Concepts
Guide.
API Gateway uses Secure Sockets Layer (SSL) for communications between all processes in a domain (for example, internal management traffic between the Admin Node Manager and API Gateway instances). The domain SSL certificate signs the Admin Node Manager and API Gateway instance SSL certificates. These certificates are also used to determine whether a Node Manager is a basic Node Manager or an Admin Node Manager.
Server-side SSL authentication is used in communication between the Admin Node Manager and client applications
(Policy Studio, API Gateway Manager, managedomain
). Mutual SSL is used in communication between
the Node Manager and Node Manager, and also between the Node Manager and API Gateway instance. Each process
(Node Manager and API Gateway) in the domain has an SSL certificate that is signed by the domain SSL
certificate.
Important | |
---|---|
It is recommended that you configure at least two Admin Node Managers in an API Gateway domain for high availability.
This topic describes how to use the using the managedomain command to configure and secure
multiple Admin Node Managers in a domain.
|
When applying for an SSL certificate for an Admin Node Manager, Node Manager, or API Gateway instance, a standard Certificate Signing Request (CSR) is sent to the domain SSL certificate. The domain SSL certificate acts as the domain Certificate Authority (CA) that signs the certificates.
You can use the following options to sign SSL certificates:
-
Sign with API Gateway system-generated domain CA key and certificate
-
Sign with user-provided domain CA key and certificate
-
Sign with external CA
CSRs are generated for each SSL certificate, regardless of how they are signed. This enables you to use the CSR with your own private key and certificate, or with a standard external CA.
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.
Important | |
---|---|
When registering Admin Node Managers, you must run managedomain -i on the host machine that
will run the Admin Node Manager. This generates the private key for the Admin Node Manager, and private keys must
always be generated where they are used. No SSL certificates are provided out-of-the-box
.
|
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:
-
Generates the domain private key, the CSR for the domain certificate, and the self-signed domain certificate.
-
Generates the Node Manager private key, the CSR for the Node Manager certificate, and the Node Manager certificate signed by self-signed domain certificate.
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:
-
Extracts the user-provided domain key and certificate into
.pem
format from the.p12
file, and writes toapigateway\groups\certs\private
andapigateway\groups\certs
. The.pem
file is encrypted and removed after use. -
Generates the Node Manager private key, the CSR for the Node Manager certificate, and the Node Manager certificate signed by user-provided domain certificate.
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:
-
Generates the Node Manager private key, and the CSR for the Node Manager certificate.
-
Writes the CSR to a file, and writes a JSON file to the following location:
apigateway/groups/certs/pending/nodemanger-id-group-id-host-id.json
This contains the topology details of the new Node Manager.
-
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 Node Manager configuration:
managedomain --submit_cert --cert cert.pem
managedomain
uses the details saved in the file in the pending
directory.
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 inapigateway/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
:
--domain_passhrase |
Encrypt a newly generated domain.p12 , or unlock a user-provided
domain.p12 .
|
--domain_name |
Specify the Distinguished Name (DName) for a system-generated domain key
certificate. Defaults to CN=Domain .
|
--sign_alg |
Specify the certificate signing algorithm (for example, sha1 ,
sha256 , or sha512 ). Defaults to sha1 .
|
--subj_alt_name |
Specify a subject alternative name content for the Node Manager certificate. This is used by web browsers during the SSL handshake exchange. You can specify this multiple times. |
--key_passphrase |
You can also encrypt temporary private key files stored on disk. For example, for the Node Manager private key before it is consumed and written to the Node Manager configuration. |
The steps for adding a Node Manager (basic or Admin Node Manager) are different because there is now an Admin Node Manager running in the domain that must be invoked to add another Node Manager.
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:
-
Gets a reserved topology ID from the Admin Node Manager for the new Node Manager (to generate the CSR).
-
Generates the Node Manager private key, and the CSR for the Node Manager certificate.
-
Passes the CSR, and expects a signed certificate in response.
-
When the Admin Node Manager receives a request to sign a CSR, it checks if it has a
domain.p12
locally on disk to sign the CSR. Otherwise, it passes the request to other Admin Node Managers in the domain until one is found that can sign the CSR. -
When it receives the certificate, completes registration of the new Node Manager in the domain.
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:
-
Writes a JSON file to the following location:
apigateway/groups/certs/pending/nodemanger-id-group-id-host-id.json
This contains the topology details of the new Node Manager.
-
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 Node Manager configuration:
managedomain --submit_cert --cert cert.pem
managedomain
uses the details saved in the file in the pending
directory.
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”.
You can run managedomain
on any host in the domain, but it always connects to
one of the Admin Node Managers in the domain. If the local Node Manager is not an Admin Node Manager,
managedomain
does not connect to it.
For example, managedomain
running on host B can ask an Admin Node Manager on host A to
create a new API Gateway instance on host C. In this case, the Admin Node Manager asks the Node Manager
on host C (the new API Gateway host) to generate the private key and CSR for the new API Gateway.
This means that the private key is always generated and stored on the host machine that uses
it.
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:
-
Requests the Admin Node Manager to generate the new API Gateway private key and CSR. The Admin Node Manager can invoke another Node Manager if the API Gateway is to be on a remote host. The topology ID and CSR for the new instance is returned.
-
Passes the CSR, and expects a signed certificate in response.
-
When it receives the certificate, completes the registration of the new API Gateway in the domain.
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:
-
Writes a JSON file to the following location:
apigateway/groups/certs/pending/instance-id-group-id-host-id.json
This contains the topology details for the new API Gateway.
-
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 API Gateway configuration:
managedomain --submit_cert --cert cert.pem
managedomain
uses the details saved in the file in the pending
directory.
You can change the admin capabilities of the Node Manager running on the host local to
managedomain
using the --edit host
option. You can change a
Node Manager to an Admin Node Manager, and vice versa.
Note | |
---|---|
To change admin capabilities, you must run
You cannot remove admin capabilities if the Node Manager is the only Admin Node Manager in the domain
because there must be at least one Admin Node Manager. Changing admin capabilities means the tags
on the Node Manager in the topology are updated, and a new certificate is generated.
|
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:
-
Generates a private key and CSR for the Node Manager.
-
Passes the CSR, and expects a signed certificate in response. When the Admin Node Manager receives a request to sign a CSR, it checks if it has a
domain.p12
on disk to sign the CSR. Otherwise, it passes the request to other Admin Node Managers in the topology until one is found that can sign the CSR. -
Updates the private key and certificate in the local Node Manager configuration.
-
Prompts you to reboot the Node Manager.
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 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:
-
Generates a private key and CSR for the Node Manager.
-
Write a JSON file to
apigateway/groups/certs/pending/instance-id-group-id-host-id.json
, which contains the topology details of the updated Node Manager. -
Prompts you to take your CSR file to your 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 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. |
The domain SSL certificate is the root CA used to sign SSL certificates for Admin Node Managers, Node Managers, and
API Gateway instances. By default, the API Gateway domain SSL certificate is self-signed. This section explains how
to regenerate and change the domain SSL certificate and private key. You use the managedomain
on each host in the domain to regenerate the SSL certificates for the domain, Node Manager, and API Gateway
instances. You can do this using an API Gateway system-generated domain SSL key, a user-generated domain
SSL key, or an external CA.
Tip | |
---|---|
You can change the domain certificate management option using managedomain . For example, if
the domain was first configured to use a system-generated domain key and certificate to sign all SSL
certificates, you can change to a user-provided domain key and certificate, or an external CA. However,
you must use the same option on all hosts in the domain.
|
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:
-
If
apigateway/groups/certs/private/domain.p12
exists, the domain private key is regenerated locally, along with the CSR, and self-signed domain certificate. -
If the domain private key is on the local host, the Node Manager private key and CSR are generated, and the certificate is signed locally by
managedomain
. -
If the domain private key is on another Admin Node Manager,
managedomain
generates the private key and CSR locally, and asks an Admin Node Manager to sign the CSR. -
The Node Manager's new private key and certificate are stored in the Node Manager configuration.
-
For each local API Gateway instance, the following occurs:
-
If the domain private key is on the local host, the API Gateway private key and CSR are generated, and the certificate is signed locally.
-
If the domain private key is on another Admin Node Manager,
managedomain
generates the private key and CSR locally, and asks an Admin Node Manager to sign the CSR. -
The API Gateway's new private key and certificate are written to its
certs.xml
file.
-
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:
-
The Node Manager private key and CSR are generated, and the certificate is signed locally using the specified key and certificate.
-
The Node Manager’s new private key and certificate are stored in the Node Manager configuration.
-
For each local API Gateway instance, an API Gateway private key and CSR are generated, and the certificate is signed locally using the specified key and certificate.
-
The API Gateway’s new private key and certificate are written to the instance’s
certs.xml
file.
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:
-
The Node Manager private key is generated locally and the CSR is written to a file. Details are saved to
apigateway/groups/certs/pending
. -
For each local API Gateway, a private key is generated locally and the CSR is written to a file. Details are saved to
apigateway/groups/certs/pending
. -
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
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.
Tip | |
---|---|
You can use managedomain in interactive mode (option 24 ) to regenerate a subset
of certificates on the host. If you regenerate the domain key and certificate, the Node Manager and all
API Gateway certificates are automatically generated. If you do not regenerate the domain key and certificate,
you can choose whether to regenerate the Node Manager certificate, and which API Gateway certificates to
regenerate.
|
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”.
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.
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:
-
Copy the
domain.p12
file toapigateway/groups/certs/private/
. -
Create an
apigateway/groups/certs/serial
file with contents of01
. -
Create an empty
apigateway/groups/certs/index.txt
file. -
Parse
domain.p12
intodomainkey.pem
anddomaincert.pem
(if these files were not backed up originally). For example, assuming a passphrase offred
for the domain 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 private keys and certificates for the API Gateway domain, Node Manager, and API Gateway instances.
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:
-
Domain private key:
apigateway\groups\certs\private\domainkey.pem
-
Domain private key and certificate:
apigateway\groups\certs\private\domain.p12
-
Domain 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 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-idThe 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-idThe 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. |