Skip to Content
Technical Articles
Author's profile photo Piotr Tesny

SAP Jam App Integration with OAuth2SAMLBearerAssertion flow.

This blog is about SAP Jam App Integration with OAuth2SAMLBearerAssertion flow implemented with SAP BTP Destination service.

SAP Jam assets can be embedded by a third party application and SAP Jam can be embedding third party application assets as well.

Disclaimer:

  • SAP Jam is no longer available as a service with SAP BTP.
  • SAP WorkZone is the successor and it is built upon SAP Jam engine.
  • SAP Jam application integration capabilities are an excellent integration playground for whoever is keen to understand the internal workings of the OAuth2SAMLBearerAssertion flow together with SAP BTP Destination service.

Good to know:

  • Quoting after the SAP Jam Developer Guide/Configure a Third-Party OData API integration. There is no specific guide for a third-party OData API integration. You must consult the application’s documentation for instructions on how to proceed. However, these document links are provided:

Putting it all together

The Third-Party OData API integration explains what it takes to make an external application ready for integration with SAP Jam Collaboration.

However, in order to enable a 3rd party application’s access to SAP Jam assets, you  also need to perform the following access and authorization configuration steps in SAP Jam:

  • If your organisation’s network requires the use of self-signed or unrecognised TLS or SSL certificates, you must Add a Trusted Certificate Authority.
  • If you want to display the external application’s business records in SAP Jam, you must Configure SAP Jam as a SAML Local Identity Provider. This step ensures that users can view only the content from the external application that they have been authorised to view when that material is displayed in SAP Jam.
  • If you want to display SAP Jam content in the external application, you must:
    • Add an OAuth Client. This configuration provides the external application with authorised access to the SAP Jam API.
    • Add a SAML Trusted IDP. This step ensures that users can view only the content from SAP Jam that they have been authorised to view when that material is displayed in the external application.

     

SAP JAM OAuth2.0 configuration story board.

 

Here goes the story board with all the required configuration steps at a glance. Please click on it in order to magnify it.

Actually all the manual configuration steps on the SAP JAM side could be likely automated with for instance an iRPA bot.

SAML Local Identity Provider.

This configures the signing private key/certificate pair used by SAP Jam to generate SAML assertions as depicted below:

Issuer: 
https://jamsalesdemo2.sapjam.com/company/info/I5y3xxxxxxxxxxxxx 
Contains the unique identifier for SAML assertions issued by 
SAP Jam Signing Private Key (Base64)* below:
Private key used to sign the SAML assertions generated 
by SAP Jam X509 Certificate (Base64)*

-----BEGIN RSA PRIVATE KEY-----
MIIEogIBAAKCAQEA7lU3jdCg7KJjG31vP4uyDx6L+jzG/yI2QZuSTLtdhPR/AV3x
7ohXMGGilQKm0AitRLGFQ/aWNkJxANdbG51XL6kdbhFXu3cRM7Zt0j1YuAuMvTXD
bxdUg87rkiIaCjQcv6zQWPeeg2o5/VmyTOlrnosi+FA2Lge8nbXhEpZOdDalL6E8
..... (truncated).................
lyIqVLGxRhMVIw6xLdT6194kqhuRykeu3DcyKdVMdyK7VeNGs096Pk+JZKErDNco
VWw4KBmh/rtudButXO7+NyHDtUQJ50+W7OK3Gp+0Y8GG7A1uFHU=
-----END RSA PRIVATE KEY-----


X.509 certificate used to verify the signature of SAML 
assertions generated by SAP Jam 


-----BEGIN CERTIFICATE-----
MIIDpzCCAo+gAwIBAgIQJ5uq7dhGlBBkOJKHeSeIyTANBgkqhkiG9w0BAQsFADB3
MU0wSwYDVQQDDERodHRwczovL2phbXNhbGVzZGVtbzIuc2FwamFtLmNvbS9jb21w
YW55L2luZm8vSTV5M3c2bFU0Y2NPYUk2UlQwbEhFZzELMAkGA1UECwwCVEQxDDAK
..... (truncated).................
QOBHuA3D4zMs392O0oGMPpaaAIWEWSTdgU1+0uUJkBxqhSpSIBRJokk6d+66nk5H
m3vh4vzIkKaA8ZHT6k/DrpZpTnvqcpySKDSPmd0EbfvbpAEEygSv8HAOhj+vOdzA
z3RLa49HMueHotFl4STSXCPyzbGJZySeIXyY
-----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 jam_saml_idp.key -in jam_saml_idp.cer -out jam_saml_idp.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 jam_saml_idp.pfx file into a string for instance:
$ cat jam_saml_idp.pfx | base64

 MIIJ6QIBAzCCCa8GCSqGSIb3DQEHAaCCCaAEggmcMIIJmDCCBE8GCSqGSIb3DQEH
 ............(truncated)............................
 SUwIwYJKoZIhvcNAQkVMRYEFHZ5s0a18OthZsFneRNGzeyXHBXlMDEwITAJBgUrD
 gMCGgUABBQoy4rfqR4tO9Q2SFrHF4v0um//WwQIQx+ZVam++bgCAggA

 

From now on you can follow the steps c,d and e below (described in more details here), namely:

c.  Using here the DestinationService APIs add jam_saml_idp.pfx certificate keystore encoded as a string to the secure vault .

d. Create here a new destination to the Quovadis-JAM OAuth application with our jam_saml_idp.pfx keystore.

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

 

Find Quovadis-JAM-SAML-IDP destination:
{
  "owner": {
    "SubaccountId": "xxxxxxx-4d96-4bc0-a4fd-xxxxxxxxx",
    "InstanceId": null
  },
  "destinationConfiguration": {
    "Name": "Quovadis-JAM-SAML-IDP",
    "Type": "HTTP",
    "URL": "https://jamsalesdemo2.sapjam.com/api/v1/OData/Self",
    "Authentication": "OAuth2SAMLBearerAssertion",
    "ProxyType": "Internet",
    "KeyStorePassword": "<password>",
    "tokenServiceURLType": "Dedicated",
    "audience": "www.cubetree.com",
    "companyId": "SFPART058654",
    "authnContextClassRef": "urn:oasis:names:tc:SAML:2.0:ac:classes:PreviousSession",
    "apiKey": "<apiKey>",
    "KeyStoreLocation": "jam_saml_idp.pfx",
    "clientKey": "<apiKey>",
    "nameIdFormat": "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified",
    "nameQualifier": "www.successfactors.com",
    "SystemUser": "sfadmin",
    "tokenServiceURL": "https://jamsalesdemo2.sapjam.com/api/v1/auth/token"
  },
  "certificates": [
    {
      "Name": "jam_saml_idp.pfx",
      "Content": "MIIJ6QIBAzCCCa8GCSqGSIb3DQEHAaCCCaAEggmcMIIJmDCCBE8GCSqGSIb3DQEHBqCCBEAwggQ8AgEAMIIENQYJKoZIhvcNEiEZrlpZ7InokXjD2dUNKzxO0QeGPsBw2wYCQDpoA+uNA0bRHTpyFao+Oom5cCS+lD+yMSUwIwYJKoZIhvcNAQkVMRYEFHZ5s0a18OthZsFneRNGzeyXHBXlMDEwITAJBgUrDgMCGgUABBQoy4rfqR4tO9Q2SFrHF4v0um//WwQIQx+ZVam++bgCAggA",
      "Type": "CERTIFICATE"
    }
  ],
  "authTokens": [
    {
      "type": "bearer",
      "value": "QYoCNNWFsITGgX0ggJZtqx7Egh1oxxxxxxxxxxxxx",
      "http_header": {
        "key": "Authorization",
        "value": "Bearer QYoCNNWFsITGgX0ggJZtqx7Egh1oxxxxxxxxxxxxx"
      },
      "expires_in": "0"
    }
  ]
}

 

Consuming the remote ODATA endpoint.

The above OAuth access token can then be used to easily make calls to the OData API for instance using curl:

Find destination API call  retrieves an OAuth access token from https://jamsalesdemo2.sapjam.com

Then, you may use the following curl command to get the profile of the user authenticated by this OAuth access token in a JSON format:

$ curl https://jamsalesdemo2.sapjam.com/api/v1/OData/Self -H 
"Authorization: OAuth QYoCNNWFsITGgX0ggJZtqx7Egh1od9BUe8xYYYY" 
-H "Accept: application/json"
{
"d": {
"results": {
"__metadata": {
"uri": "Members('LwLXVuYewcjb0pbyu0HLCE')",
"type": "SAPJam.Member"
},
"Id": "xxxxxxxxxxxxxxxxx",
"FirstName": "Aanya",
"LastName": "Sing",
"Nickname": null,
"Title": "Administrative Support",
"Email": "sfadmin@bestrun.com",
"FullName": "Aanya Sing",
"Role": "company",
"IsFollowing": false,
"WebURL": "https://jamsalesdemo2.sapjam.com/profile/wall/LwLXVuYewcxxxx",
"IsAway": false,
"PersonGuid": null,
"JobDescription": null,
"Messages": {
"__deferred": {
"uri": "Members('xxxxxxx')/Messages"
}
},
"FeedEntries": {
"__deferred": {
"uri": "Members('xxxxxxx')/FeedEntries"
}
},
"ProfilePhoto": {
"__deferred": {
"uri": "Members('xxxxxxxx')/ProfilePhoto"
}
}
"QrImage": {
"__deferred": {
"uri": "Members('LwLXVuYewcjb0pbyu0HLCE')/QrImage"
}
},
"Expertises": {
"__deferred": {
"uri": "Members('xxxxxxxxxx')/Expertises"
}
}
}
}
}

Conclusion.

Given the rich API capabilities of SAP BTP Destination service I was able to fully automate all the steps related to the management of the destination itself.

In other words there is no longer need to access SAP BTP cockpit to manage destinations, certificates and so on. That’s important because it enforces the security of the entire solution and simplifies all the housekeeping and maintenance activities in one place (SAP API Management).

Please have a closer look at the API Management portal with the screenshot of the policy that securely implements OAuth2.0 access to my destination service APIs and then the APIs sandbox.

Last but not least, the exposed API Management endpoint with all the API verbs can be used from any programming language or LCNC framework like SAP Appgyver or Mendix.

 

 

 

__________

 

Additional resources.

 

SAP Jam Collaboration Developer Guide and its pdf version.

 

SAP Jam API

The SAP Jam Collaboration OData API allows you to integrate SAP Jam Collaboration features into your business critical applications, and it allows you to integrate data from your business critical applications into SAP Jam.

This part of the SAP Jam Collaboration Developer Guide provides the following sections of API Documentation:

  • Please see the SAP Jam API Reference at the following location: https://developer.sapjam.com/ODataDocs/ui
  • SAP Jam OData API Tutorial: This tutorial is designed to give you a good understanding of SAP Jam Collaboration‘s OData API implementation and to help you to quickly get up to speed using the SAP Jam API.
  • Authentication and Authorization API: Client applications using the SAP Jam REST or OData APIs have two options for providing authorization and authentication for their users: an OAuth1.0a 3-Legged workflow, or SAML assertions from a trusted identity provider. The OAuth1.0a workflow is best for client applications without access to a SAML identity provider (IDP), although it requires some interaction with the end user. The SAML assertions from a trusted IDP configured in the SAP Jam Admin console by your company administrator. Additionally, there is the possibility of single-use tokens, although this approach is better suited to granting immediate, short-term access to single pages.
  • SAP Jam REST API: The SAP Jam Collaboration REST API has mostly been ported to the OData API; however, one set of REST API calls remain: the REST Social Reports API calls. The Social Reports REST API calls allow you to generate and retrieve reports on social activity in SAP Jam.

 

Assigned tags

      Be the first to leave a comment
      You must be Logged on to comment or reply to a post.