Skip to Content
Technical Articles
Author's profile photo Mandy Krimmel

Cloud Integration – Activate SAP Keys in Keystore Monitor

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.

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.

 

Assigned Tags

      19 Comments
      You must be Logged on to comment or reply to a post.
      Author's profile photo Sankara Bavirisetti
      Sankara Bavirisetti

      SAP Cloud Platform Integration client certificate is about to expire

      Hello Mandy,

      I received below alert e-mail from SAP support and I was able to generate keys but not able to find expired certificate details as per date stated in alert e-mail , I reviewed all the key-store and I could see only all certificates - only self signed ones ,

      I mean as of now no CA signed installed ones either in HCI-DS or connected systems ( SF , PI , HANA etc) my simplest question is HOWTO find-out expire certificate and relevant keystore? Is it alert raising from SF or other systems?

      "Note: If you do not take action before the expiry date the new keys will automatically get activated as soon as the old SAP keys expire. Still your communication from SAP Cloud Platform Integration to your external systems will most likely be disrupted in case the respective certificate was not updated in your back ends, as well.

      Please attend if this applies to your applications or you have questions. Please invite anyone you think needs this information.

      ------------------------

      Our monitors indicate that your SAP Cloud Platform Integration client certificate is about to expire on <13 January 2019>.

      We have prepared a new key pair for you that is ready to be downloaded as a self-service on your SAP Cloud Platform Integration Web UI (→ Operations View → Keystore → New SAP Keys).
      Please note that Tenant Administrator's authorization is required to access the new keys."

      Author's profile photo Mandy Krimmel
      Mandy Krimmel
      Blog Post Author

      Hello,

      so, you had a new key in the New SAP Keys tab and activated it as described in the blog?

      The one that is expired had the same alias then the one you now got in the New SAP Keys and if you activate it it overwrites the old expired key.

      The old expired one should now be visible in the SAP Key History tab as described.

      Please check there.

      If you have not used this SAP-owned certificate to connect to any of backends in any of your scenarios then you don't have to change it in the backends. This is something you need to check in your scenarios.

      The alert you got is only from Cloud Platform Integration Keystore, not from any other backend systems. If they have such an alerting, I do not know.

      Best regards,

      Mandy

      Author's profile photo somkuwar manoj
      somkuwar manoj

      If you have not used this SAP-owned certificate to connect to any of backends in any of your scenarios then you don't have to change it in the backends. This is something you need to check in your scenarios.

       

      Hi Mandy,

      Regarding your above statement, I have two Integration Content for Spain SII and Canary Islands Tax submission. Can you please help me check how can I check inside these scenarios whether certificate with alias 'sap_cloudintegrationcertificate' is being used or not.

      I am new to BTP/SAP Cloud Integration and would really appreciate some help.

       

      Regards,

      Manoj Somkuwar

      Author's profile photo Mandy Krimmel
      Mandy Krimmel
      Blog Post Author

      Hello Manoj,

      this is unfortunately not so easy to answer as you need to check in detail the security flow steps and adapters used in the integration scenarios. Important is if signer/validator; encryptor/decryptor is used and which transport-level security is used.

      A very good description is available in the help documentation: Basic Security Artifact Renewal Processes | SAP Help Portal

      Best regards

      Mandy

      Author's profile photo Sankara Bavirisetti
      Sankara Bavirisetti

      Thanks, Mandy for your response. I reviewed all involved key stores in SAP HCI – DS tenant, which is irrelevant to my case, and I got a clue on client certificate expiry. Its a generic e-mail trigger from SAP to cloud customers its related SAP JAM   we are not using JAM anywhere and got confirmation from SAP Could support also.

      Thanks , Sankar

      Author's profile photo Frank Treichel
      Frank Treichel

      Hello Mandy,

      where can I find the "Keystore Monitor"?

      In the SAP BTP Neo Cockpit - Subaccount “Cloud Platform Integration Partner" I can only find the "Keystore Services” but without the possibility to download the new key pair.

      I've the role ‘Global Account Administrator’ and SAP wrote: “We have prepared a new key pair for you that is ready to be downloaded”.

      Best Regards

      Frank

       

       

      Author's profile photo Mandy Krimmel
      Mandy Krimmel
      Blog Post Author

      Hello Frank,

      this is a monitor specifically required for and offered by Cloud Integration. It is part of the operation  WebUI for Cloud Integration, not part of the BTP Cockpit.

      Best regards

      Mandy

      Author's profile photo Frank Treichel
      Frank Treichel

      Hello Mandy,

      thanks for your answer, but it doesn't help me. Maybe it's trivial, but where can I find the "WebUI for Cloud Integration"?

      • https://launchpad.support.sap.com/ ?
      • https://pwp.sap.com/sappartneredgelaunchpad ?
      • <tenant-ID>-tmn.hci.eu2.hana.ondemand.com ? (Status 404 Not found)

      B.R.

      Frank

      Author's profile photo Mandy Krimmel
      Mandy Krimmel
      Blog Post Author

      <tenant>/itspaces, see Verifying Access for Users - SAP Help Portal

      Best regards

      Mandy

      Author's profile photo Frank Treichel
      Frank Treichel

      Hello Mandy,

      thanks, but

      https://<tenant name xxxx>-tmn.hci.eu2.hana.ondemand.com/itspaces

      doesn't work in Chrome, Firefox, IE:

      "403 Forbidden"

      I'll send an incident at category LOD-HCI-PI-OPS like your hint in blog:

      https://blogs.sap.com/2017/06/19/cloud-integration-keystore-monitor-now-available-for-tenant-administrator/

      Best Regards

      Frank

      Author's profile photo Mandy Krimmel
      Mandy Krimmel
      Blog Post Author

      403 means you have not the right roles assigned. Please check your roles assignment Verifying Access for Users - SAP Help Portal or ask the admin to check. SAP Ops cannot help with this

      BR

      Mandy

      Author's profile photo Frank Treichel
      Frank Treichel

      Hello Mandy,

      the problem is solved:

      the AuthGroup.Administrator role was to add.

      #2543001 - How to grant access to SAP Cloud Integration tenant [NEO environment]

       

      B.R.

      Frank

      Author's profile photo Kannan Sudhanthiradevi
      Kannan Sudhanthiradevi

      Hi Mandy,

      We have got alert to renew the X.509 certificate for our tenant .But, based on our existing iflows , we are using User role authorization (ESBMessaging.send).Still , do we need to take care of renewal of keys which has been provided by SAP. Please clarify.Thanks

      Author's profile photo Mandy Krimmel
      Mandy Krimmel
      Blog Post Author

      Hello,

      you need to check if you are using this certificate in outbound calls for authentication. Role-Based authorization is used on CPI inbound side.

      Best regards

      Mandy

      Author's profile photo Kannan Sudhanthiradevi
      Kannan Sudhanthiradevi

      Hi Mandy,

      Thank you for your reply. Yes. We are using Role-Based authorization on CPI inbound side(Replication from S4H to SFSF). We are not using the certificate (sap_cloudintegrationcertificate) in our iflows.

      But, I would like to check whether we need to take care of renewal of keys provided by SAP even though if we are using Role-Based authorization.

       

      Author's profile photo Mandy Krimmel
      Mandy Krimmel
      Blog Post Author

      Hello,

      do you have a tenant in CF (Cloud Foundry) or in Neo? If your tenant is running in CF and you use client certificates for inbound authentication then yes, you definitely need to renew as sap_cloudintegrationcertificate is mandatory in this use case (Cloud Integration on CF – How to Setup Secure HTTP Inbound Connection with Client Certificates | SAP Blogs). In Neo this dependency does not apply for the inbound authentication.

      But in both cases you have to check for outbound communication and security flow steps. Are you using client certificate based outbound communication? Three scenarios may need the sap_cloudintegrationcertificate:

      • you use this alias in some  security flow steps (PKCS7 XML signer), then you definitely need to renew it
      • You directly configure this alias in one of the outbound channels for client certificate based authentication. This you said, is not the case.
      • you do not configure any alias for client certificate outbound communication -> in this case sap_cloudintegrationcertificate may be used without you knowing as any fitting key from the keystore is use

      In general I would recommend to renew it to be on the save side.

      Best regards

      Mandy

      Author's profile photo Jens Schwendemann
      Jens Schwendemann

      Hi Mandy,

      in the vicinity of this problem area: It is really a pain in the neck to identify the scope (see your chapter on "Identify all Backend Systems to be Updated"

      Is there or is there planned a "where used list" for the differen points? That would really help a great deal. In my ideal world something like this would be possible:

      • Go to Keystore in CI
      • Chose a Keypair (SAP managed or custom managed)
      • Click on "where used" (this would be a new feature)
      • I get a where used list for the keypair like so
        • iFlow "abc"
          • Adapter
            • Type = OData
            • Private Key Alias = <my selected alias from above>
          • PKCS7 decryptor
            • ...
        • iFlow "xyz"
          • WS-Security
            • ...

      Would that be possible or is it maybe even planned? In the meantime, what would be our second best option?

       

      Many thanks and kind regards

      Jens

      Author's profile photo Mandy Krimmel
      Mandy Krimmel
      Blog Post Author

      Hello Jens,

      yes, there is a where-used feature planned which will offer the list of adapter channels and steps a certain key alias is used in.

      Best regards

      Mandy

      Author's profile photo Kannan Sudhanthiradevi
      Kannan Sudhanthiradevi

      Hi Mandy,

      Noted with Thanks. Our tenant in Neo.

      As per your recommendation , i will share the certificates with sender  and activate the keys in our tenant. Thanks a lot for your clarification.