Configure OAuth 2.0 for SAP ByDesign OData Services

[knutheusermann]

SAP Business ByDesign OData services support two authentication protocols: Basic Authentication (user/password) and OAuth 2.0 SAML Bearer authentication.

Combining frontend single sign-on and principal propagation using OAuth means you can extend SAP Business ByDesign (ByD) by SAP Cloud Platform HTML5 applications and automatically benefit from the role-based authorization management of ByD. As result you gain a great flexibility to extend ByD at low development costs to secure data stored in ByD.

This blog posts provides an example to configure single sign-on and principal propagation using OAuth 2.0 SAML Bearer authentication between an HTML5 Application running on the SAP Cloud Platform (SCP) and SAP Business ByDesign (ByD) using OData services.

 

Example scenario:

Let’s assume we have an HTML5 Application running on the SAP Cloud Platform (SCP) to display and browse your company address book and allow employees to change their workplace address information. The HTML5 application is connected to SAP Business ByDesign as cloud ERP backend with all relevant employee data stored.

Users shall be able to use the same logon credentials for the SCP HTML5 application as well as for SAP Business ByDesign using frontend single sign-on, and user propagation shall be used for any OData requests between the SCP application and ByD.

In my example I’m using the following system setup:

• SAP Business ByDesign (referred to as “ByD”)


• SAP Cloud Platform Identity Authentication as Identity provider (referred to as “IDP”)


• SAP Cloud Platform sub-account to develop and run the HTML5 application "demoemployee" (referred to as “SCP”)

In my blog post Extend SAP ByDesign using SAP Cloud Platform HTML5 Applications I explained how to setup an HTML5 Application running on the SAP Cloud Platform to extend SAP Business ByDesign.

Now we will adapt this setup in 3 steps to apply frontend Single Sign-On and principal propagation using OAuth 2.0 SAML Bearer authentication:

1. Setup frontend Single Sign-On for the SCP HTML5 Application


2. Setup frontend Single Sign-On for SAP Business ByDesign


3. Configure principal propagation between the SAP Cloud Platform HTML5 Application and SAP Business ByDesign using OAuth 2.0 SAML Bearer Authentication

 

Step 1: Setup Single Sign-On for the SCP HTML5 Application

As first step we setup frontend single sign-on to use SAP Cloud Platform Identity Authentication as Identity provider for the HTML5 demo application.

SCP: Capture all relevant information to configure the IDP and later on OAuth:

1. Open the SAP Cloud Platform Cockpit and navigate to Security >> Trust and edit the
   Local Service Provider settings
   
   
   
   • Change the Configuration Type to “Custom”
   
   
   • If no signing key is available click on “Generate Key Pair” and save
   
   
   
   


2. Note the Local Provider Name


3. Copy the Signing Certificate and create a .cer-file (e.g. with file name “SCP_subaccount_signing_certificate.cer”) with exactly the following content:
   -----BEGIN CERTIFICATE-----
   <cut&past Signing Certificate here>
   -----END CERTIFICATE-----


4. Click on “Get Metadata” and save the Service Provider Metadata (e.g. file name “SCP_subaccount_SP_metadata.xml”)

IDP: Add the SCP as application to the identity provider list of applications:

1. Open the SAP Cloud Platform Identity Authentication Administration Console and navigate to Applications & Resources >> Applications


2. Add an application and name it according your SCP sub-account name


3. Open the SAML 2.0 Configuration and upload the Service Provider Metadata of your SAP Cloud Platform sub-account; save


4. Open Name ID Attribute and select "E-Mail"; save


5. Open Default Name ID Format and select "E-Mail" as well; save


6. Open Assertion Attributes and note the SAML Assertion Attribute Names (could be for example “first_name”, “last_name” and “mail”)

IDP: Capture the IDP metadata from the SAP Cloud Platform Identity Authentication tenant:

1. Open the SAP Cloud Platform Identity Authentication Administration Console and navigate to Applications & Resources >> Tenant Settings


2. Open SAML 2.0 Configuration, click on “Download Metadata File” and save the IDP Metadata File (e.g. file name “IDP_metadata.xml”)

SCP: Add the SAP Cloud Platform Identity Authentication tenant as trusted identity provider:

1. Open the SAP Cloud Platform Cockpit and navigate to Security >> Trust and switch to sheet Application Identity Provider


2. Click on “Add Trusted Identity Provider” and upload the IDP Metadata File; save


3. Switch to tab “Attributes” and enter Assertion-Based Attributes using the SAML Assertion Attribute Names provided by the IDP and the principal attribute names “email”, “firstname” and “lastname”, for example:
   
   
   
   • mail : email
   
   
   • first_name : firstname
   
   
   • last_name : lastname
   
   
   
   

Result:

You can test single sign-on for your SCP HTML5 Application: Capture the Application URL of your SCP HTML5 application and open the URL in an incognito browser window. The browser should redirect you to the IDP logon screen for authentication and you should be able to successfully login to the SCP HTML5 application.

 

Step 2: Setup Single Sign-On for SAP Business ByDesign

In step 2 we setup frontend single sign-on to use SAP Cloud Platform Identity Authentication as Identity provider for SAP Business ByDesign.

ByD: Configure Single Sign-on:

1. Open the ByD work center Application and User Management >> common task Configure Single Sign-On


2. On tab “My System” note the Local Provider Name and click on “SP Metadata” to download and save the Service Provider Metadata (e.g. file name “ByD_SP_metadata.xml”)


3. Switch to tab “Identity Provider”, create a “New Identity Provider” and upload the IDP Metadata File downloaded step 1


4. Edit the Supported Name ID Formats and add “E-Mail Address” as default name ID format and save (Note: ByD supports SSO name ID format e-mail with release 1808; make sure you maintained your e-mail address in your ByD employee contact data in field “E-Mail”)


5. Click button “Activate Single Sign-On”

IDP: Add the ByD tenant as application on the identity provider:

1. Open the SAP Cloud Platform Identity Authentication Administration Console and navigate to Applications & Resources >> Applications


2. Add an application and name it according your ByD tenant name


3. Open the SAML 2.0 Configuration and upload the Service Provider Metadata of your ByD tenant; save


4. Open Name ID Attribute and select "E-Mail"; save


5. Open Default Name ID Format and select "E-Mail"; save

Result:

You can login to the ByD tenant using single sign-on: Open the SSO-URL of your ByD tenant in an incognito browser window (for example "https://myXXXXXX-sso.sapbydesign.com"). The browser should redirect you to the IDP logon screen for authentication and you should be able to successfully login to ByD.

Some remarks:

Per default ByD uses the name ID format “unspecified” for user mapping. ByD maps the name ID of SAML-assertions on the ByD user alias.

Additionally ByD support the name ID format “emailAddress“. In this case ByD maps the name ID of the SAM-assertion on the ByD user e-mail address that is specified in the ByD employee contact data.

 

Step 3: Configure OAuth 2.0 SAML Bearer Authentication

In step 1 and 2 we configured frontend single sign-on for SAP ByDesign and the SAP Cloud Platform application. Now we configure principal propagation such that the same user is used for OData access between the SCP application and ByD as well.

ByD: Configure an OAuth 2.0 Identity Provider

1. Open the ByD work center Application and User Management >> common task Configure OAuth 2.0 Identity Providers


2. Create new OAuth 2.0 provider:
   
   
   
   • Issuing Entity Name: Enter the SCP Local Provider Name noted in step 1
   
   
   • Primary Signing Certificate: Browse and upload the SCP Signing Certificate .cer-file created in step 1
   
   
   • Check indicator “Email Address”
   
   
   
   

ByD: Add an OAuth2.0 Client Registration

1. Open the ByD work center view Application and User Management - OAuth2.0 Client Registration


2. Create new OAuth2.0 Client Registration
   
   
   
   • Client ID: Note the Client ID generated by the system
   
   
   • Client Secret: Enter a password and note the Client Secret
   
   
   • Description:  Enter some description
   
   
   • Issuer Name: Select the OAuth 2.0 Identity provider created above
   
   
   • Scope: Selecting scope ID “UIWC:CC_HOME” should be sufficient for most use cases
   
   
   
   

SCP: Create a Destination with OAuth 2.0 SAML Bearer authentication

1. Open the SAP Cloud Platform Cockpit, navigate to Connectivity >> Destinations and create a new destination:
   
   
   
   • Name: Enter a destination name
   
   
   • Type: "HTTP"
   
   
   • Description: Enter a destination description
   
   
   • URL: Enter the URL of your ByD OData service, for example “https://myXXXXXX.sapbydesign.com/sap/byd/odata/cust/v1/khemployee/”
   
   
   • Proxy Type: "Internet"
   
   
   • Authentication: "OAuth2SAMLBearerAssertion"
   
   
   • Audience: Enter the ByD Local Provider Name noted in step 2
   
   
   • Client Key: Enter the ByD Client ID noted in step 3
   
   
   • Token Service URL: Enter the ByD token service URL, for example “https://myXXXXXX.sapbydesign.com/sap/bc/sec/oauth2/token” (replace the hostname with your ByD tenant hostname)
   
   
   • Token Service User: Enter the ByD Client ID noted in step 3
   
   
   • Token Service Password: Enter the ByD Client Secret noted in step 3
   
   
   
   

Enter the Additional Properties:

1. 
   
   
   
   • authnContextClassRef : "urn:none"
   
   
   • nameIdFormat : "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress"
   
   
   • scope : Enter the Scope of the ByD OAuth client registration, e.g. "UIWC:CC_HOME"
   
   
   • userIdSource : "email"
   
   
   
   


2. Open SAP Cloud Platform Cockpit and navigate to HTML5 Applications: Open the HTML5 application and edit the destination mapping: enter your new OAuth destination as “Mapped Subaccount Destination”.

Result:

The SCP HTML5 Application now uses user propagation for accessing ByD using the OData services. Open the Application URL of your HTML5 application in an incognito browser window: The browser should redirect you to the IDP logon screen for authentication (frontend single sign-on configured in step 1) and the role-based authorizations of your mapped ByD user should apply in the HTML5 application for read and write access to ByD (user propagation configured in step 3).

 

Remarks and additional information

In my example above I used a single SCP sub-account to develop and use the HTML5 appication.

In a productively used scenario I would rather suggest to separate provisioning and consumption of the SCP application, which adds one more SCP sub-account to the system setup:

• SAP Business ByDesign


• SAP Cloud Platform Identity Authentication as Identity provider


• SAP Cloud Platform provider sub-account to develop and deploy the HTML5 application


• SAP Cloud Platform consumer sub-account to use the HTML5 application

In this setup the SAP Cloud Platform consumer sub-account subscribes to the HTML5 application provided by the SAP Cloud Platform provider sub-account using SAP Cloud Platform Cockpit >> Application >> Subscription.

In the subscription you get the Application URL and you have the possibility to map required destinations as described in step 3.
Furthemore frontend single sign-on and OAuth 2.0 SAML Bearer Authentication has to be configured in the SAP Cloud Platform consumer sub-account.

Related information using OAuth 2.0 in SAP Business ByDesign and SAP Cloud for Customer:

• SAP Business ByDesign Help Center: search for "OAuth 2.0 Quick Guide" or “Front-End Single Sign-On“


• SAP Help / SAP Cloud Platform: search for “Authorization and Trust Management“


• SAP Community:
  Single Log-Out (SLO) with SAP Business ByDesign
  Single-Sign On (SSO) with SAP Business ByDesign
  Configuring OAuth 2.0 between SAP Hybris Cloud for Customer and SAP Cloud Platform


• GitHub: SAP Cloud for Customer OData API Developer's Guide (incl. a sample Java implementation of an OAuth SAML bearer client)

[former_member492434]

Hey Knut,

thanks for the great tutorial!

I have a question related to that: Given a scenario in which not every user of the SCP HTML5 app has a user in ByD, would it also be possible to use a technical user in ByD instead of a business user when doing HTTP Basic Auth?

Regards,

Patrick

[knutheusermann]

Hi Patrick,

ByD Soap services and OData for data sources can be consumed using technical users with basic authentication or client certificates. OData for business objects (the API I'm using in my example above) requires a ByD business user for authentication.

Best regards,
Knut

 

[former_member547195]

Hi Knut,

 

Thanks for the great information on how the setup within the SAP Cloud Platform.

 

I have a question is that other than this great example of setting up in SAP products, by chance you have any example of how the OAuth 2.0 can be setup with other applications or even interface, like Microsoft Office and etc.?

 

Regards
MC

[knutheusermann]

Hi MC,

I don’t have such an example myself, but maybe you find the example you are looking for in the communities of SAP Cloud Platform Identity Authentication or SAP Cloud Platform Security.

Best regards,
Knut

[former_member8971]

Hi Knut

Thank you for a great blog on the topic of configuring OAuth2.0.

We have the exact same scenario, an HTLM5 app in SCP that connects to Odata structure in SAP ByD.

We have SSO setup for SAP By Design via Azure and login with our email address.

Should we still follow this blog or do you have a link to another blog that describes how to set this up?

 

I would be very grateful for any feedback.

Regards,

Caroline

[former_member8971]

A

[former_member492434]

Hi Knut,

thanks, I managed to set this all up successfully and it works great with all my OData services.

However, I am trying to create CustomerInvoiceRequests and have so far done this using the Web Service SOAP API Manage Customer Invoice Requests. Yet, it seems that with SOAP I cannot use OAuth authentication, is that correct? I always get 401 Unauthorized when I try to send the same header as I would with OAuth.

Now I was trying to work around this by performing the request using OData, but according to your comment here (and my experiments), it doesn't seem to be possible to create customer invoice requests using Odata.

Do you have any other suggestions as to how I can proceed?

Thanks and cheers,

Patrick

[Srivas]

Hi Patrick,

 

For implementing Manage Customer Invoice Requests you do not require OAuth, as this is a SOAP process.

For this you need to configure Communication Arrangement (Application and Work Center > Input and Output Management)

OData is used for REST.

 

Cheers

Srivas

 

[former_member492434]

Hi Srivas,

Thanks for your response.

I am aware that I don't need to use OAuth, yet I would like to. I would prefer not setting up a communication arrangement and use that for all users but rather use business users for managing the customer invoice requests so that the change history includes their names and not a technical user.

Cheers,

Patrick

[cf-michael]

Hi Knut,

Your blog is the most useful resource for connectivity with ByDesign!  Given this article, can I conclude that if a Company opts for an SSO-only authentication using an external IdP, that integration scenarios (using BO-based Custom OData services) which previously used Basic Authentication, have no other recourse but to transition to an OAuth 2.0 authentication?

I suspect so, but I would appreciate clarity on the matter.

Best Regards,

Michael

[nosta]

Hi Caroline,

did you manage to setup azure with OAuth and ByD? If yes, do you have any hints on how to do it?

[former_member803239]

Dear Knut

We find that BYD has a default OAuth 2.0 Identity Provider

named "odataconsole.hana.ondemand.com" ,

can we also use it ?

 

BR
Chen

[knutheusermann]

Hi Chen,

this OAuth 2.0 Identity Provider is owned by SAP and used exclusively for the OData Console to test OData services (the "Test"-button in work center view "OData Service").  As a customer you cannot use this OAuth 2.0 Identity Provider unfortunately.

However, this feature incl. the OData Console is mostly used by C4C. For ByD, I would recommend testing OData services as described in blog post SAP Business ByDesign – OData API Examples.

[may_thitsaoo]

Dear knut.heusermann

 

We are using OData services with Basic Authentication.
When we test the service in SOAPUI and Postman, no problem.
But when we try in Excel VBA, it keeps getting "An unknown error occurred while processing the certificate.".
We are not sure what kind of certificate it is referring.
Do you have any advice on this?

Thank you.

Regards,
May

[MarkvanDooren]

Hi Philipp,

 

Did you manage to get azure with OAuth and ByD working?

 

Kind regards,

Mark

[nosta]

Hi Mark,

send me a mail via philipp.koehler@all4cloudgroup.com

Best regards,
Philipp

[lynap]

Hi all,

Does anybody knows if ByD supports OAuth 2 flow "Client Credential"?

Thanks,

Ly-Na

[jorge_velasquez]

Hi!

Is it possible to use IDP from other providers?

Is it possible to configure this from invidual users?

Regards

[former_member848075]

Hi,

Can someone tell me what that error message means?
{ "error": "invalid_grant", "error_description": "The provided authorization grant is invalid. Exception was: Attribute 'Recipient' of element 'SubjectConfirmationData' is invalid. For more information consult the kernel traces or the OAuth 2.0 trouble shooting SAP note 1688545." }

We receive this error message when we use this link: https://my430xxx.businessbydesign.cloud.sap/sap/bc/sec/oauth2/token

We have had no issues with the old URL https://my340xxx.sapbydesign.com/sap/bc/sec/oauth2/token
so far.

Are there any changes?