Bring your own trust!

This is a follow-up article to the following mini series of blogs on the OAuth2SAMLBearerAssertion Flow with SAP BTP Destination Service. Disclaimer: Please note all the code snippets below are provided “as is”. All the x509 certificates, bearer access and refresh tokens and the likes have been redacted.

Abstract.

The focus of this instalment is to describe how to fully automate the implementation and the deployment of the OAuth2SAMLBearerAssertion flow with SAP BTP Destination service APIs, including when using your own x.509 trust with the destination.

 

Scenario A. Using the generic (default) Destination Service trust   That’s the scenario covered in my original post: OAuth2SAMLBearerAssertion Flow with the SAP BTP Destination Service. SuccessFactors. Leveraging the Destination Service x.509 trust service simplifies the implementation of the entire OAuth2SAMLBearerAssertion flow, making it sort of out-of-the-box. However there is one caveat to it, namely the trust (=the public X509 certificate key) has to be manually downloaded from the DestinationService GUI on the SAP BTP side. Update as of June 2021. The above statement is, to some extent, no longer true as SAP BTP destination service has added a new REST API endpoint allowing you to download the generic SAML IdP metadata (that precisely contains the x.509 certificate) , namely /saml2Metadata.  Let’s see what it takes to use a custom X509 certificate key pair with the destination service.

Scenario B. Using the SuccessFactors generated X.509 key pair   Indeed, Destination Service certificate APIs allow to manage your own key-stores with certificates and have them assigned to destinations programmatically. Let’s see how this can be done with a custom trust (certificate) generated by a SFSF tenant (Admin Center/Manage OAuth2 Client Applications)

 

Putting it all together.

a. Steps on the SFSF tenant side:

1. Goto Admin Center/Tools/Manage OAuth2 Client Applications
2. Register/add new client application.
3. Generate x509 certificate. Only the CN field is mandatory. The value you enter as CN will become the name of the issuer in the signed saml assertion
4. Download the generated key pair into a local text file. You will need it later.
5. Register the application.

Good to know:

• the SFSF-generated key pair is in PKCS8 format and base64 encoded
• both the encrypted private key and the public x509 certificate of the key pair are already flattened into single line strings

 

b. Next step is to convert the key pair into a keystore file format that will be accepted by the DestinationService.

 

Good to know:

• I have only tested either .pfx and .p12 PKCS12 keystore formats so far. These are the most popular containers of the certificate key pairs (private+public keys).
• Supported certificate file extensions are: “.jks”, “.crt”, “.cer”, “.der”, “.p12”, and “.pfx”. However please note regardless of the keystore format you must provide both the private and the public x.509 certificate in the key pair container.
• Destination service certificates API requires the name of the keystore with one of the above extensions and the content of keystore file encoded into a base64-encoded string.
• The name of the keystore file is  important as it is used as a hint towards the base64-encoded content.
• I did not find it very intuitive and was initially expecting to be able to pass my private and public keys [as base64-encoded single line strings] into the API without the need of creating a keystore file. Nonetheless, despite this caveat, the API allows you to fully automate the process of uploading/updating/removing of the certificates and not having to do it manually from the Destination Service GUI.

Steps to create a key pair container :

• prepare the private and public keys in a normalised PEM format.
  • base64-decode the PKCS8 private key into a string and then format the string into a Private Key PEM format (not exceeding 64 characters per single line),
  • Save it locally into a file:

    Quovadis-SAP-pkcs8.pem​
    
    
    here goes a truncated private key content.
    please note each line does not exceed 64 characters
    
    ----BEGIN PRIVATE KEY-----
    MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQCxYAtn2l+j12U6
    pDOpCmbzfKV8VhrbXAO6JepTchc/tWgZgKMf/yeUigpyeIiL60Mc4Q4jdcR40I+6
    1LZYqkvSl6FrWU3T4tC4OJQzsMZeHW1FtxyplWs/xWEzGGE6q8Ve6Sdv1Nro7IEC
    xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
    xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
    xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
    XGbjKUhAq24wXglEq0+FhBaeUEjmoccpuPVXAKWhAoGAPSmr/83IP1mcmVxy2OIC
    c4SxqKy7MhOwWLagp2t8MXjtYbs9PMyqtUzdqJBPpqGYhyj+TZkVJ1djyLeDNVbv
    9Ivbez4r++c73GnBw3hBBpfdJb7uNHWj7ULV7ARdkhCQIA44zY8PE1kLsrEH8pfz
    OtpPzIFKF+JBkqFx0rTCQBA=
    -----END PRIVATE KEY-----

• • base64-decode the X.509 public key into a string and then format the string into a X.509 PEM format (not exceeding 64 characters per single line).
  • Save it locally into a file:

    Quovadis-SAP-x509.pem
    
    here goes a truncated public key content:
    please note each line does not exceed 64 characters
    
    -----BEGIN CERTIFICATE-----
    MIIDKDCCAhCgAwIBAgIEFPqAZzANBgkqhkiG9w0BAQQFADBWMQswCQYDVQQGEwJV
    SzEJMAcGA1UECBMAMQkwBwYDVQQHEwAxDDAKBgNVBAoTA1NBUDEMMAoGA1UECxMD
    R1BPMRUwEwYDVQQDEwxxdW92YWRpcy9zYXAwHhcNMjEwMzI3MjM0NTM5WhcNNDgw
    xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
    xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
    xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
    K4qO3rczlZgy5u3XhJrojcXa2+Q7GsyDl7k0egzXQxqklxsRbq09A96bbrqS+CjG
    Gi7CzwO6o1aExIHd5r6/A8moQjr1R0rlARrlTx5VF9IoyM7K1l5Vb5hQYn78M4dP
    dM1gsr5JLapT4c9XlKpv3HEcV8rTDZ+hS0ZwRSR6M5a+JZqKX+o3OlVx5D0=
    -----END CERTIFICATE-----

     

• create a PKCS12-formatted .pfx or .p12 keystore.
  • run the below openssl command to create a PKCS12-formatted pfx keystore as depicted below:

$ openssl pkcs12 -export -inkey Quovadis-SAP-pkcs8.pem \
-in Quovadis-SAP-x509.pem -out Quovadis-SAP.pfx
Enter Export Password:
Verifying - Enter Export Password:

----------------------------------------------------------
Please make note of the password as you will need it later
in the destination definition.

• • base64-encode the Quovadis-SAP.pfx file into a string for instance:

MIIJaQIBAzCCCS8GCSqGSIb3DQEHAaCCCSAEggkcMIIJGDCCA88GCSqGSIb3DQEHBqCCA8AwggO8AgEAMIIDtQYJKoZIhvcNAQcBMBwGCiqGSIb3DQEMAQYwDgQI7lMw3L7cdssCAggAgIIDiDzxvv/WOYSgcwyCPZpmQoIRxc2m37ehcjNV7b51euH9+FxlGCOLB0czpqeRULGA+jFWp68KBm8Ze3vpjMB5XggXoi52bcy6kHpoT3BwmO43IZdAb7rahYRIti5daPvgs9xj2JVWuqonLcWKUzw89dhmQ0GPs57X6vpEtprMd2NcMVnSDGq173v6pUnwKS6AJ2YiqOwQPGasx2g44lNEpvrTsY85qIX094l4eJ4A8MsO1Nau3YT

########################## truncated #################################

HRtfx/RglD005qV14LmaAaYd6r5GOeYdV0YC5xHkBbWU9sh7aE5mDF/AVW2w22ji1UYHYp7qjkDImou7sbXpQMHyNrdcw/kPqsIRuP1wQLxcxegQqD9UMr3mhw8a4S6I/mqMP4rJcUGak6R35U+/9uSdZkbwIqSUIssEZ2d9vjAjtjcL5VlwcMEn7b1QR2qEdYuSPXcnskBHWFcskv0cICS3dUesSxm6/Psn4pbMpMYf+ydrOehkrAProaGftb9nNhFdThJEy2eW+9Jv9SLRX+05zYMYmUlBGArFHRUMKTYUNlf6vi4uTGL5K9lVHtJfllPxzSOBZ8GR9juzwfLd5/YrfN8zeP+j5UFBNZOOf1TXV7HRUGpC90UpTJsI4TN54+uXZBoC2xwX84I6QrPqFgeT4FIDKG0KIAo9thayo5VYa9OPuNy9fkLvQHfi0M80kNrUZKzOuGMxr7qQCwGdiRCwAC/LTn6GIQuB+NHRxYPXLiCZVYX1RBNPAIywasn4C77hjj02gNEqFFQlu1dgmcsw6s3nQyOzvs0lK3H4RYB0PWefD+N45FQoF98oTElMCMGCSqGSIb3DQEJFTEWBBRcuLmsoF0w3oYj1xllxSC9hRneWzAxMCEwCQYFKw4DAhoFAAQUPTi8wCiDIYWXJdI0tqd2XLbXSnsECAnnFfE3b2EgAgIIAA==

 

Good to know: In order to base64-decode the keys you may use the command line or any online tool of your choice. the steps above could be automated with 3rd party APIs.

c. From now on you may use the certificate file encoded string with the DestinationService APIs.

Steps:

1. GET subaccountCertificates API call:
obtain the list of all uploaded certificates (key pairs) present 
in your DestinationService instance.

https://destination-configuration.cfapps.eu10.hana.ondemand.com/destination-configuration/v1/subaccountCertificates

2. POST subaccountCertificates API call:
add a new keystore to the Destination service vault.

https://destination-configuration.cfapps.eu10.hana.ondemand.com/destination-configuration/v1/subaccountCertificates

3. you may again run the GET certificate or GET certificates 
API to make sure yours has been recorded.

 

 

Good to know:

• Alternatively you might upload the .pfx keystore file into the DestinationService instance from the Destination Service UI.

d. Now it is time to create a new destination to the Quovadis-SAP OAuth application with our Quovadis-SAP.pfx keystore.

Steps:

• Prepare the json structure of the Quovadis-SAP destination.
• To make it more efficient we can reuse the json structure from the previously set up Quovadis-SFSF destination or any other destination you may have already defined.
• We will need to add new “KeyStorePassword” and the “KeyStoreLocation” properties and of course amend the apiKey, the clientKey and the user.

 

{
  "Name": "Quovadis-SAP",
  "Type": "HTTP",
  "URL": "https://apisalesdemo2.successfactors.eu/odata/v2/User/$metadata",
  "Authentication": "OAuth2SAMLBearerAssertion",
  "ProxyType": "Internet",
  "KeyStorePassword": "<your key store password>",
  "tokenServiceURLType": "Dedicated",
  "audience": "www.successfactors.com",
  "companyId": "<SFSF tenant companyId>",
  "authnContextClassRef": "urn:oasis:names:tc:SAML:2.0:ac:classes:PreviousSession",
  "apiKey": "<Quovadis-SAP apiKey>",
  "KeyStoreLocation": "quovadis-sap.pfx",
  "clientKey": "<Quovadis-SAP apiKey>",
  "nameIdFormat": "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified",
  "SystemUser": "<your test user>",
  "tokenServiceURL": "<SFSF tenant>/oauth/token"
}

• add your destination definition using the subaccountDestinations API calls as depicted below:

 

1. GET subaccountDestinations API call:
obtain the list of all destinations present in your DestinationService instance.

https://destination-configuration.cfapps.eu10.hana.ondemand.com/destination-configuration/v1/subaccountDestinations

2. POST subaccountDestinations API call:
add our new Quovadis-SAP destination to the Destination service instance.

https://destination-configuration.cfapps.eu10.hana.ondemand.com/destination-configuration/v1/subaccountDestinations

3. you may again run the GET destination to retrieve the newly 
created Quovadis-SAP destination 

https://destination-configuration.cfapps.eu10.hana.ondemand.com/destination-configuration/v1/subaccountDestinations/Quovadis-SAP

 

e. Use (=Find) the Quovadis-SAP destination to acquire the bearer access token as demonstrated below:

Find destination API call:

https://destination-configuration.cfapps.eu10.hana.ondemand.com/
destination-configuration/v1/destinations/Quovadis-SAP

 

Conclusion

The destination service is evolving constantly and the newly added /saml2Metadata endpoint is a “living” proof of it. Nowadays, full automation is possible whether using the default trust or whether you decide to bring your own trust As usual, looking forward to your comments or questions…

 

__________

Appendix

Scenario A

As aforementioned, SAP BTP destination service features a newly added REST API endpoint allowing you to download the generic SAML IdP metadata (that precisely contains the x.509 certificate) , namely /saml2Metadata. 

https://destination-configuration.cfapps.<region>.hana.ondemand.com/destination-configuration/v1/saml2Metadata

{
  "idpMetadata": "PG5zMzpFbnRpdHlEZXNjcmlwdG9yCiAgICAgICAgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvMDkveG1sZHNpZyMiCiAgICAgICAgeG1sbnM6bnMyPSJodHRwOi8vd3d3LnczLm9yZy8yMDAxLzA0L3htbGVuYyMiCiAgICAgICAgeG1sbnM6bnM0PEZXNjcmlwdG9yPgogICAgPC9uczM6SURQU1NPRGVzY3JpcHRvcj4KPC9uczM6RW50aXR5RGVzY3JpcHRvcj4="
}

The  resulting idpMetadata string is a base64-encoded  generic IDP XML metadata. It does contain the x509 certificate but is not configured for any specific scenario (i.e. CF to CF, CF to Neo etc.) which might require additional properties. For convenience, it the can be decoded into plain XML with any saml assertion decoder  and then  formatted with pretty print as follows:

<?xml version="1.0"?>
<ns3:EntityDescriptor xmlns="http://www.w3.org/2000/09/xmldsig#" xmlns:ns2="http://www.w3.org/2001/04/xmlenc#" xmlns:ns4="urn:oasis:names:tc:SAML:2.0:assertion" xmlns:ns3="urn:oasis:names:tc:SAML:2.0:metadata">
  <script/>
  <ns3:SPSSODescriptor AuthnRequestsSigned="true" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
    <ns3:KeyDescriptor use="signing">
      <KeyInfo>
        <X509Data>
          <X509Certificate> MIIFiDCCA3CgAwIBAgIKl4jx5h0R3MSTdzANBgkqhkiG9w0BAQ0FADCBgjFLMEkG A1UEAwxCY2ZhcHBzLmFwMjEuaGFuYS5vbmRlbWFuZC5jb20vYWZiYWM0ZGUtOWQx D85Qu75kaZW44MwyUDaiWBfvV2MH3dT7MxaLaQ== </X509Certificate>
        </X509Data>
      </KeyInfo>
    </ns3:KeyDescriptor>
  </ns3:SPSSODescriptor>
  <ns3:IDPSSODescriptor WantAuthnRequestsSigned="true" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
    <ns3:KeyDescriptor use="signing">
      <KeyInfo>
        <X509Data>
          <X509Certificate> MIIFiDCCA3CgAwIBAgIKl4jx5h0R3MSTdzANBgkqhkiG9w0BAQ0FADCBgjFLMEkG A1UEAwxCY2ZhcHBzLmFwMjEuaGFuYS5vbmRlbWFuZC5jb20vYWZiYWM0ZGUtOWQx D85Qu75kaZW44MwyUDaiWBfvV2MH3dT7MxaLaQ== </X509Certificate>
        </X509Data>
      </KeyInfo>
    </ns3:KeyDescriptor>
  </ns3:IDPSSODescriptor>
</ns3:EntityDescriptor>

 

__________

Additional resources.

SAP Business API Hub sandbox environment. Before you can configure the API hub sandbox environment you will need to have created an instance of the destination service. Please refer to the following article on the details for the sandbox environment configuration with SAP API Business Hub.