Configuring the administration endpoint to accept connections over TLS

Secure the administration (admin) endpoint on Eclipse Amlen V2.0 so that only connections over TLS are accepted.

The admin endpoint is a special endpoint that listens on the server that handles incoming connections from administrative REST API clients. By default, the admin endpoint is not secured. Complete the following steps to secure the admin endpoint so that only connections from clients that pass in the correct server certificate and key are accepted.

Note: If a problem occurs during the following process, the admin endpoint might get corrupted and no longer work. Messaging clients would still work, but you would not be able to administer your Eclipse Amlen server - either by using the REST API or by using the Web UI. Therefore, you might want to back up your server before securing the admin endpoint. The only way to recover the admin endpoint is to stop the server, delete all configuration information, and restart. Resetting the server to the default configuration results in the loss of all custom data.

The following table shows the files that are required to secure the admin endpoint, and provides names for the files that are used in our example:

Table 1. Files required to secure an admin endpoint.
File	Example name
CA certificate file	rootCA-crt.pem
Amlen server certificate file	msserver-crt.pem
Amlen server key file	msserver-key.pem
Amlen server certificate file (msserver-cert.pem) combined with the CA certificate file (rootCA-crt.pem) into a single certificate file	server-trust-chain.pem
Client certificate file	msclient-crt.pem
Client key file	msclient-key.pem
Client certificate and key file combined into a pkcs12 file	*.p12

Upload the Eclipse Amlen server certificate file. The following example shows a PUT method to upload the certificate file by using cURL:

curl -X PUT -T msserver-crt.pem http://localhost:9089/ima/v1/file/msserver-crt-admin.pem
Upload the Eclipse Amlen server key file. The following example shows a PUT method to upload the server key file by using cURL:

curl -X PUT -T msserver-key.pem http://localhost:9089/ima/v1/file/msserver-key-admin.pem
Upload the CA certificate file. The following example shows a PUT method to upload the CA certificate file by using cURL:

curl -X PUT -T rootCA-crt.pem http://localhost:9089/ima/v1/file/rootCA-crt-admin.pem
Create the "SecureAdmin" certificate profile called for the Eclipse Amlen server. The following example shows a POST method to create the certificate profile by using cURL:

curl -X POST http://localhost:9089/ima/v1/configuration -d '{"CertificateProfile":{"SecureAdmin":{"Certificate":"msserver-crt-admin.pem","Key":"msserver-key-admin.pem"}}}'
Create the "SecureAdminSecProfile" SecurityProfile. The following example shows a POST method to create the security profile by using cURL:

curl -X POST http://localhost:9089/ima/v1/configuration -d '{"SecurityProfile":{"SecureAdminSecProf":{"MinimumProtocolMethod":"TLSv1.2","UseClientCertificate":true,"Ciphers":"Fast","UsePasswordAuthentication":false,"CertificateProfile":"SecureAdmin"}}}'
Add the CA certificate as a TrustedCertificate for the SecureAdminSecProf security profile. The following example shows a POST method to add the CA certificate as a TrustedCertificate by using cURL:

curl -X POST http://localhost:9089/ima/v1/configuration -d '{"TrustedCertificate":[{"TrustedCertificate":"rootCA-crt-admin.pem","SecurityProfileName":"SecureAdminSecProf","Overwrite":true}]}'
Set the "SecureAdminSecProfile" as the SecurityProfile for the admin endpoint. The following example shows a POST method to set the security profile for the admin endpoint by using cURL:

curl -X POST http://localhost:9089/ima/v1/configuration -d '{ "AdminEndpoint": { "SecurityProfile": "SecureAdminSecProf" }}'

After the command completes, the admin endpoint accepts only TLS connections. If the TLS is not correctly configured, you cannot connect to the admin endpoint.
Test that you can connect to the secure admin endpoint. The following example shows a GET method to test the connection by using cURL:

curl -k --cacert /path/to/server-trust-chain.pem --cert /path/to/msclient-crt.pem --key /path/to/msclient-key.pem -X GET https://localhost:9089/ima/v1/service/status

Once the admin endpoint is secured to listen only for TLS connections, the URL for all REST calls must start with https, as shown in the previous example.

If you are using valid CA signed certificates, your browser can connect to the new TLS-only admin endpoint. If you are not using CA signed certifcates, you must import the msclient.p12 file into your browser as a trusted certificate. For example, if you are using Firefox, select Edit > Preferences > Advanced > Certificates > View Certificates > Your Certificates > Import.

Use following commands to create the files that are used in this example. Replace variable names with the appropriate value for your configuration.

Note: Do not use the following commands to create certificates for production environments.

cat > ext.cfg <<EOF
[ req ]
attributes              = req_attributes
distinguished_name      = req_distinguished_name
req_extensions          = v3_ca
prompt                  = no
[ req_attributes ]
[ v3_ca ]
subjectKeyIdentifier    = hash
authorityKeyIdentifier  = keyid:always,issuer
basicConstraints        = CA:true
[ req_distinguished_name ]
countryName                 = US
stateOrProvinceName                 = state_code
localityName                        = city_name
organizationalUnitName              = organization
commonName                          = descriptive_name
emailAddress                        = email
EOF

cat > srvext.cfg <<EOF
[ req ]
req_extensions          = v3_req
[ v3_req ]
subjectAltName          = DNS:server_hostname
EOF

openssl genrsa -out rootCA-key.pem 2048
openssl genrsa -out msCA-key.pem 2048
openssl genrsa -out msserver-key.pem 2048
openssl genrsa -out msclient-key.pem 2048
openssl req -new -x509 -days 3650 -subj subject_CA_dn -extensions v3_ca -set_serial 1 -key rootCA-key.pem -out rootCA-crt.pem
openssl req -new -days 3650 -subj subject_messagegateway_team_dn -key msCA-key.pem -out msCA-crt.csr
openssl x509 -days 3650 -in msCA-crt.csr -out msCA-crt.pem -req -CA rootCA-crt.pem -CAkey rootCA-key.pem -set_serial 3 -extensions v3_ca -extfile ext.cfg
openssl req -new -days 3650 -subj messagegateway_server_subject_dn -key msserver-key.pem -out msserver-crt.csr
openssl x509 -days 3650 -in msserver-crt.csr -out msserver-crt.pem -req -CA rootCA-crt.pem -CAkey rootCA-key.pem -extensions v3_req -extfile srvext.cfg -set_serial 2
openssl req -new -days 3650 -subj messagegateway_client_subject_dn -key msclient-key.pem -out msclient-crt.csr
openssl x509 -days 3650 -in msclient-crt.csr -out msclient-crt.pem -req -CA rootCA-crt.pem -CAkey rootCA-key.pem -extensions v3_req -set_serial 4
openssl pkcs12 -export -inkey msclient-key.pem -in msclient-crt.pem -out msclient.p12 -passout pass:

cat msserver-crt.pem > server-trust-chain.pem
cat rootCA-crt.pem >> server-trust-chain.pem

The following table provides example values for the file names that are required to secure an admin endpoint:

Table 2. Files required to secure an admin endpoint.
File	Example value
subject_CA_dn	/`C=US/ST=TX/L=City/O=Company/OU=Corporate/CN=Company Corporate`
subject_messagegateway_team_dn	`/C=US/ST=TX/L=City/O=Company/OU=MessageGateway/CN=MessageGateway Team`
messagegateway_server_subject_dn	`/C=US/ST=TX/L=City/O=Company/OU=MessageGateway/CN=MessageGateway Team (server)`
messagegateway_client_subject_dn	`/C=US/ST=TX/L=City/O=Company/OU=MessageGateway/CN=MessageGateway Team (msclient)`

where:

subject_CA_dn: might be set to the following values: /C=US/ST=TX/L=City/O=Company/OU=Corporate/CN=Company Corporate
subject_messagegateway_team_dn: might be set to the following values: /C=US/ST=TX/L=City/O=Company/OU=MessageGateway/CN=MessageGateway Team
messagegateway_server_subject_dn: might be set to the following values: /C=US/ST=TX/L=City/O=Company/OU=MessageGateway/CN=MessageGateway Team (server)
messagegateway_client_subject_dn: might be set to the following values: /C=US/ST=TX/L=City/O=Company/OU=MessageGateway/CN=MessageGateway Team (msclient)