SAP-owned keys in the tenant keystore need to be renewed when they expire. You can activate newly provisioned SAP keys yourself using the Keystore Monitor. This blog describes how to use the Keystore Monitor to manage the renewal of SAP-owned keys, how to update the affected backends and how to activate the new key. It also describes how to reset the key in case of errors.
SAP-owned keys in the Keystore Monitor can also be used by customers in setting up secure HTTP connections to backend systems using client certificate. This is described in blogs 'Maintain Keys and Certificate in Keystore Monitor ' and 'Setup Secure Outbound HTTP Connection Using Keystore Monitor'. In addition, the SAP keys can also be used for message level security; to sign or decrypt messages using PKCS7, XML or simple signer or in WS Security.
Private key pairs need to be renewed regularly as they are only valid for a certain time interval. After expiration, the key cannot be used anymore for establishing connections and should not be used anymore for signing messages.
The updated SAP-owned keys will be provided by SAP, the customer tenant administrator will get a notification mail about the required renewal. As the tenant administrator has to trigger the overall process of the key/certificate update, the final activation of the new key has to be done by the tenant administrator.
The process for changing keys and certificates in the CPI tenant is described in online help chapter 'Security Artifact Renewal ' in detail for specific scenarios, so this will not be detailed out here. This blog will only describe the general process using Keystore Monitor keeping the same alias during renewal.
The overall process starts with preparing the renewal; downloading the new certificates, identifying the affected scenarios and backend systems and finally, it is important to agree with the backend administrator on a downtime.
In the Keystore Monitor there is a new screen New SAP Keys for the updated SAP Keys. Already at the top you see if there are new SAP Keys available, notifying you, that there is some action necessary.
The screen lists the new SAP keys available for activation. But before activating the key you need to make sure the certificates are also updated in all affected backend systems.
For client certificate based authentication at the receiver system the root certificate and the client certificate of the cloud integration tenants private key are needed in the receiver system. For this, export the certificate and the root certificate of the private key pair in the Keystore Monitor. These options are available as single line options.
To download the public certificate select Download Certificate from the actions button in the line of the private Key Pair. Download Certificate for a Key Pair will create a file with the name <alias>.cer in the download directory. The file contains the public certificate for the private key.
To download the root certificate select Download Root Certificate from the actions button in the line of the private Key Pair. Download Root Certificate for a Key Pair will create a file with the name <alias>_rootCA.cer in the download directory. The file contains the root certificate for the private key.
Both certificates need to be imported into the receiver system in the next step.
For client certificate-based authentication at the receiver system the root certificate and the client certificate of the Cloud Integration tenants' private key are needed in the receiver system. For verifying the signature or for encrypting messages the client certificate is needed in the respective sender or receiver backend system.
To provide the new certificates to the adminstrators of the respective backend systems, export the certificate chain and/or the certificate of the private key pair in the New SAP Keys screen. This option is available as single line option, select Download Certificate Chain or Download Certificate from the actions button in the line of the new SAP Key Pair.
Download Certificate Chain will create a file with the name <alias>.p7b in the download directory. The file contains the whole certificate chain assigned to the private key. The certificate chain file can, for example, be opened with the Certificates Snap-in of Microsoft Management Console (Certmgr.msc), which is usually available on Windows systems.
Open the downloaded <alias>.p7b file with the Certificates Snap-in on your system and open the tab Certificate Path. There, the whole certificate chain can be seen.
The entry on top is the root certificate. Open the root certificate via double click. This will open the root certificate. In tab Details export the root certificate into a file via Copy to File. In the Certificate Export Wizard export the root certificate as DER encoded binary X.509 file. Use any arbitrary file name to save the certificate as *.cer file.
In the same way you exported the root certificate, also export the client certificate, which is the one at the bottom of the certificate chain. Alternatively, download it using the option Download Certificate from New SAP Keys monitor.
This part is actually the tricky part, because it is not easy to find out in which scenarios the specific key is used. Optimal would be, if the tenant administrator knows all the scenarios and knows where the key is used.
But as this may not always be the case here some details how to find the affected scenarios. Analyze all scenarios deployed in the tenant:
After this analysis, you now know all the backend systems that need the new certificate(s).
To avoid failing messages you should agree on a downtime for the affected scenarios with the administrator of the backend systems.
Otherwise messages will fail during the renewal, because private key in CPI tenant and certificate in the backend do not match. If the sender system re-tries the message in such cases, you do not necessarily need to have a complete downtime, but except the temporary errors.
During the agreed downtime, the certificates need to be imported into the backend systems and the new SAP key needs to be activated in the Cloud Integration tenant.
For outbound communication using client certificate-based authentication, in the receiver system the root certificate and the client certificate of the cloud integration tenants' private key are to be imported.
To do this, import the root certificate retrieved in previous step into the trust store of the receiver system. In addition, you normally need to import the client certificate into a user-to-certificate mapping in the receiver backend.
If the key is used for message level security (PKCS7, XML Signature, WS Security), the new certificate has to be updated in the sender or receiver backend.
The new SAP Key needs to be activated in the New SAP Keys screen. This option is available as single line option for the new key, select Activate to trigger the activation of the new key. The old SAP Key in the CPI tenant keystore will be overwritten.
During activation of the new key, a backup of the old key will be stored in the SAP Key History to revert the change, if necessary.
The security flow steps (Signer and Decryptor) will use the updated key immediately, but in the scenarios, where an existing connection is re-used, like for example in outbound connections, the key is cached within the connection for some time. To make these connections use the new key, you need to restart the respective integration flows.
This can be done in the Operations UI in Manage Integration Content section. Select the integration flow and select Restart to trigger a restart.
After the changes are performed in the CPI tenant and the affected backend systems, all the scenarios need to be tested carefully. For testing the client-certificate based authentication, you can additionally use the Outbound Connectivity Tests.
All scenarios identified above need to be tested. Make sure all affected configurations are tested, not only the straight forward process flow.
After changing the SAP key used for connection using client certificate towards the backend system, the connectivity test feature can be used to test the communication.
The Connectivity Test, which is described in detail in online help chapter 'TLS Connectivity Test', is available in Operations View in Web, in section Manage Security Material. Selecting the Connectivity Test tile from Overview Page will open the test tool offering tests for different protocols. To test the HTTPS-based outbound communication the TLS option is to be selected.
Enter the address of your connected cloud backend system (Tests to On-Premise backends via Cloud Connector cannot be done) as used in the outbound channel. Client Certificate-based authentication can be checked via option Authenticate with Client Certificate. Enter the alias of the key that was updated and execute the test. The test will give a success message or an error with detailed error information.
In case there are errors after the activation, you should try to identify the root cause and solve it. Most probably the update of the certificate was forgotten in one backend system.
If you do not get the problem solved, there also is the option to revert the change in the CPI tenant and go back to the old SAP Key. This can be done in the SAP Key History screen using the single line action Add to New SAP Keys for the old SAP key. Identify the correct key by the Active Until timestamp.
Selecting this option will move the old SAP key back to the New SAP Keys screen. From there you can activate it as described earlier.
But keep in mind, that some backends may have correctly activated the new certificate. Therefore, use this option with care!
If the tenant administrator does not trigger the activation on his or her own, the key gets automatically activated one day before the old SAP key expires. Therefore, scenarios using this key may not work anymore, because the respective certificate was not updated in the backend systems. But as the old key is expired, the connections would also not work anymore with the old key.
So, you are requested to exchange the new certificates with the administrators of the backend systems as soon as possible to get the scenarios working again.
To secure the use of Keystore Monitor in Web, two roles are available.
With the role NodeManager.read the user is able to see the entries in keystore and to download public content, but activation of keys or changes are not possible. For changing role NodeManager.deploysecuritycontent is required.
Role NodeManager.read is available in the group roles AuthGroup.IntegrationDeveloper and AuthGroup.ReadOnly, and role NodeManager.deploysecuritycontent is contained in group role AuthGroup.Administrator.
Activate SAP Keys in Keystore Monitor
SAP-owned keys in the Keystore Monitor can also be used by customers in setting up secure HTTP connections to backend systems using client certificate. This is described in blogs 'Maintain Keys and Certificate in Keystore Monitor ' and 'Setup Secure Outbound HTTP Connection Using Keystore Monitor'. In addition, the SAP keys can also be used for message level security; to sign or decrypt messages using PKCS7, XML or simple signer or in WS Security.
Private key pairs need to be renewed regularly as they are only valid for a certain time interval. After expiration, the key cannot be used anymore for establishing connections and should not be used anymore for signing messages.
The updated SAP-owned keys will be provided by SAP, the customer tenant administrator will get a notification mail about the required renewal. As the tenant administrator has to trigger the overall process of the key/certificate update, the final activation of the new key has to be done by the tenant administrator.
The process for changing keys and certificates in the CPI tenant is described in online help chapter 'Security Artifact Renewal ' in detail for specific scenarios, so this will not be detailed out here. This blog will only describe the general process using Keystore Monitor keeping the same alias during renewal.
Prepare Activation of New SAP Key
The overall process starts with preparing the renewal; downloading the new certificates, identifying the affected scenarios and backend systems and finally, it is important to agree with the backend administrator on a downtime.
Check for New SAP Keys
In the Keystore Monitor there is a new screen New SAP Keys for the updated SAP Keys. Already at the top you see if there are new SAP Keys available, notifying you, that there is some action necessary.
The screen lists the new SAP keys available for activation. But before activating the key you need to make sure the certificates are also updated in all affected backend systems.
Download Certificate and Root Certificate from Keystore Monitor (Option to be used with 20-January-2019 release)
For client certificate based authentication at the receiver system the root certificate and the client certificate of the cloud integration tenants private key are needed in the receiver system. For this, export the certificate and the root certificate of the private key pair in the Keystore Monitor. These options are available as single line options.
To download the public certificate select Download Certificate from the actions button in the line of the private Key Pair. Download Certificate for a Key Pair will create a file with the name <alias>.cer in the download directory. The file contains the public certificate for the private key.
To download the root certificate select Download Root Certificate from the actions button in the line of the private Key Pair. Download Root Certificate for a Key Pair will create a file with the name <alias>_rootCA.cer in the download directory. The file contains the root certificate for the private key.
Both certificates need to be imported into the receiver system in the next step.
Download Certificate and Certificate Chain from Keystore Monitor(Option to be used until 20-January-2019 release)
For client certificate-based authentication at the receiver system the root certificate and the client certificate of the Cloud Integration tenants' private key are needed in the receiver system. For verifying the signature or for encrypting messages the client certificate is needed in the respective sender or receiver backend system.
To provide the new certificates to the adminstrators of the respective backend systems, export the certificate chain and/or the certificate of the private key pair in the New SAP Keys screen. This option is available as single line option, select Download Certificate Chain or Download Certificate from the actions button in the line of the new SAP Key Pair.
Download Certificate Chain will create a file with the name <alias>.p7b in the download directory. The file contains the whole certificate chain assigned to the private key. The certificate chain file can, for example, be opened with the Certificates Snap-in of Microsoft Management Console (Certmgr.msc), which is usually available on Windows systems.
Open the downloaded <alias>.p7b file with the Certificates Snap-in on your system and open the tab Certificate Path. There, the whole certificate chain can be seen.
The entry on top is the root certificate. Open the root certificate via double click. This will open the root certificate. In tab Details export the root certificate into a file via Copy to File. In the Certificate Export Wizard export the root certificate as DER encoded binary X.509 file. Use any arbitrary file name to save the certificate as *.cer file.
In the same way you exported the root certificate, also export the client certificate, which is the one at the bottom of the certificate chain. Alternatively, download it using the option Download Certificate from New SAP Keys monitor.
Identify all Backend Systems to be Updated
This part is actually the tricky part, because it is not easy to find out in which scenarios the specific key is used. Optimal would be, if the tenant administrator knows all the scenarios and knows where the key is used.
But as this may not always be the case here some details how to find the affected scenarios. Analyze all scenarios deployed in the tenant:
- Check if the alias is used in any PKCS7, XML or simple signer flow steps. -> The certificate also needs to be updated in the backend systems, these scenarios send the signed messages to.
- Check if the alias is used in any SOAP 1.x sender or receiver channels under WS-Security. -> The certificate also needs to be updated in the backend systems, these scenarios send the signed message to or receives an encrypted message from.
- Check if PKCS7 decryptor flow steps are used. -> As for decryption any valid key in the keystore is used, the certificate potentially also needs to be updated in the backend systems, form which encrypted messages are received in these scenarios.
- Check if the alias is used in any outbound HTTP-based adapter channels (e.g. SOAP, IDOC, HTTP, AS2) for client-certificate based authentication. -> The certificate also needs to be updated in the backend systems, to which messages are being sent in these scenarios.
- Check if there are outbound HTTP-based adapter channels (e.g. SOAP, IDOC, HTTP, AS2) configured with client-certificate based authentication without private key alias specified. -> As in this case any valid key from keystore is used, the certificate potentially also needs to be updated in the backend systems, to which messages are being sent in these scenarios.
After this analysis, you now know all the backend systems that need the new certificate(s).
Agree on Downtime for Key Renewal
To avoid failing messages you should agree on a downtime for the affected scenarios with the administrator of the backend systems.
Otherwise messages will fail during the renewal, because private key in CPI tenant and certificate in the backend do not match. If the sender system re-tries the message in such cases, you do not necessarily need to have a complete downtime, but except the temporary errors.
Update the Keys and Certificates
During the agreed downtime, the certificates need to be imported into the backend systems and the new SAP key needs to be activated in the Cloud Integration tenant.
Import Certificate into Backend System
For outbound communication using client certificate-based authentication, in the receiver system the root certificate and the client certificate of the cloud integration tenants' private key are to be imported.
To do this, import the root certificate retrieved in previous step into the trust store of the receiver system. In addition, you normally need to import the client certificate into a user-to-certificate mapping in the receiver backend.
If the key is used for message level security (PKCS7, XML Signature, WS Security), the new certificate has to be updated in the sender or receiver backend.
Activate SAP Key in Keystore Monitor
The new SAP Key needs to be activated in the New SAP Keys screen. This option is available as single line option for the new key, select Activate to trigger the activation of the new key. The old SAP Key in the CPI tenant keystore will be overwritten.
During activation of the new key, a backup of the old key will be stored in the SAP Key History to revert the change, if necessary.
Restart the Integration Flows
The security flow steps (Signer and Decryptor) will use the updated key immediately, but in the scenarios, where an existing connection is re-used, like for example in outbound connections, the key is cached within the connection for some time. To make these connections use the new key, you need to restart the respective integration flows.
This can be done in the Operations UI in Manage Integration Content section. Select the integration flow and select Restart to trigger a restart.
Testing and Reverting
After the changes are performed in the CPI tenant and the affected backend systems, all the scenarios need to be tested carefully. For testing the client-certificate based authentication, you can additionally use the Outbound Connectivity Tests.
Scenario Tests
All scenarios identified above need to be tested. Make sure all affected configurations are tested, not only the straight forward process flow.
Connectivity Test
After changing the SAP key used for connection using client certificate towards the backend system, the connectivity test feature can be used to test the communication.
The Connectivity Test, which is described in detail in online help chapter 'TLS Connectivity Test', is available in Operations View in Web, in section Manage Security Material. Selecting the Connectivity Test tile from Overview Page will open the test tool offering tests for different protocols. To test the HTTPS-based outbound communication the TLS option is to be selected.
Enter the address of your connected cloud backend system (Tests to On-Premise backends via Cloud Connector cannot be done) as used in the outbound channel. Client Certificate-based authentication can be checked via option Authenticate with Client Certificate. Enter the alias of the key that was updated and execute the test. The test will give a success message or an error with detailed error information.
Revert to Previously Used SAP Key in Case of Error
In case there are errors after the activation, you should try to identify the root cause and solve it. Most probably the update of the certificate was forgotten in one backend system.
If you do not get the problem solved, there also is the option to revert the change in the CPI tenant and go back to the old SAP Key. This can be done in the SAP Key History screen using the single line action Add to New SAP Keys for the old SAP key. Identify the correct key by the Active Until timestamp.
Selecting this option will move the old SAP key back to the New SAP Keys screen. From there you can activate it as described earlier.
But keep in mind, that some backends may have correctly activated the new certificate. Therefore, use this option with care!
Automatic Activation when the old SAP Key is Expired
If the tenant administrator does not trigger the activation on his or her own, the key gets automatically activated one day before the old SAP key expires. Therefore, scenarios using this key may not work anymore, because the respective certificate was not updated in the backend systems. But as the old key is expired, the connections would also not work anymore with the old key.
So, you are requested to exchange the new certificates with the administrators of the backend systems as soon as possible to get the scenarios working again.
Authorizations
To secure the use of Keystore Monitor in Web, two roles are available.
With the role NodeManager.read the user is able to see the entries in keystore and to download public content, but activation of keys or changes are not possible. For changing role NodeManager.deploysecuritycontent is required.
Role NodeManager.read is available in the group roles AuthGroup.IntegrationDeveloper and AuthGroup.ReadOnly, and role NodeManager.deploysecuritycontent is contained in group role AuthGroup.Administrator.
- SAP Managed Tags:
19 Comments
