Description
Description
Mutual authentication establishes trust by exchanging secure sockets layer (SSL) certificates.
Before connecting to a server, the client requests an SSL certificate. The server responds by requesting that the client send its own certificate. Both respond by validating the certificates and sending acknowledgments before initiating an HTTPS connection.
This article outline the steps required to set up mutual authentication.
Observe that this feature only enables mutual authentication on outbound https connections.
Procedure
The following steps can be executed to setup the mutual authentication:
A) Creating the Key Store
In this step you will create a keystore file containing the private an public keys that will be used by ServiceNow side mutual authentication.
ServiceNow instance will use the public key certificate as authentication with the 3rd party web server.
1. Generate a new Java keystore and key pair (keyool -genkey command).
2. Generate a CSR (Certificate Signing Request) for the existing Java keystore (keytool -certreq command).
Use your own domain for this certificate request.
3. Import a root or intermediate certificates from the certificate authority into the Java keystore (keytool -import -trustcacerts command).
4. Import the signed primary certificate returned by your CA authority into the Java keystore (keytool -import -trustcacerts command).
Notes:
- CA authority may provide you specific instructions about what to include in the certificate request.
- Keep record of your Keystore password and certificate alias.
B) Setting up the Key Store record in ServiceNow.
Role required: admin
1. On the System Definition > Certificates page, click New and set the following fields:
- Enter a Name.
- Set Type = Java Key Store.
- Set the key store as Active.
- Provide a Key store password (the one used to create the keystore).
2. Attach the keystore file created in step (A) into the record.
3. Click Submit to create the Java Key Store entry.
C) Share the new keystore's public key with your 3rd party web service provider.
This is the authentication certificate used by ServiceNow.
1. Using Java "keytool -export" command, export the public key from your recently created keystore file into a DER or PEM format certificate file.
2. Share this file with your 3rd Party web service provider.
D) Specifying a Trusted Server Certificate.
This step will import into ServiceNow trust store a public certificate provided by your 3rd party web service. This is the authentication certificate used by your 3rd party.
Role required: admin
1. Navigate to System Definition > Certificates.
2. Click New and provide:
- A record a name
- Set the Type field to be "Trust Store Cert".
- If the certificate provided by the 3rd party is in PEM format, set the Format field to PEM and paste the PEM string into the PEM Certificate field on the record.
- If the certificate provided by the 3rd party is in DER format, set the Format field to DER and just attach the certificate file to the record.
3. Click on Submit.
E) Create a protocol profile
Role required: admin
1. Navigate to System Security > Protocol Profiles.
2. Click New.
- Enter a unique name to identify this protocol, such as myhttps ( this name cannot be http).
- Enter the protocol communication port (443 for SSL).
- Select the Keystore Record created on B) above.
3. Save the record.
F) Enable mutual authentication
Role required: web_service_admin or admin
1. Navigate to System Web Services > SOAP Message or System Web Services > REST Message.
2. Select a message record.
3. Select the Use mutual authentication check box.
4. In the Protocol profile field, select a protocol profile configured on D) above for mutual authentication.
5. Click Update.
Test your web service, the Mutual Authentication should allow the web service to complete the call.
Applicable Versions
Madrid, New York.
Additional Information
Documents used to outline solution:
Setting up mutual authentication
Outbound web services mutual authentication
Create a protocol profile
Enable mutual authentication