Explaining the Authentication Flow of SAP Build Work Zone

As outlined in this unit's introduction, SAP Build Work Zone runs as a service on SAP BTP. Therefore, it relies on the identity provider (IdP) trust configuration on the subaccount level. Also, the Digital Workplace Service (DWS) layer leverages dedicated authentication related settings, which must be considered. This lesson explores the authentication-related aspects across the SAP Build Work Zone product architecture, including how the different elements are connected.

For SAP Build Work Zone, IAS must at least be used in proxy mode when connecting to another SAP or third party. IdP isn’t supported. Directly connecting a corporate identity provider to the SAP BTP subaccount doesn’t work for SAP Build Work Zone or SAP SuccessFactors Work Zone. The manual trust configuration on the BTP subaccount with IAS (based on SAML2) is supported. However, the recommended trust setup with IAS is using the automated, establish trust feature (OpenID Connect).

This is the prerequisite for the direct integration of SAP Build Work Zone with IAS. The subaccount-level trust is no longer used for the login to SAP Build Work Zone itself once this direct integration with IAS is set up. However, the shared trust setup on the subaccount level is still required.

Regardless of the selected configuration mode of IAS and a potentially connected corporate IdP, the information configured for this trust setup is important. It directly impacts the user attributes available across the SAP Build Work Zone experience or setup, namely:Subaccount → Security → Users list (if the Create Shadow Users During Logon option is enabled).

• Subaccount → Connectivity → Destinations (for example, the userIdSource property)
• Attributes for Principal Propagation to on-premise back end systems (using destinations and SAP Cloud Connector)
• Attributes shown in the user avatar in SAP Build Work Zone shell header

In addition to the SAP BTP subaccount level trust, another trust configuration is required for the Digital Workplace Service component running as an iframe in SAP Build Work Zone. This trust is also an Identity Authentication SAML2-based trust. This setup is configured purely as a fallback mechanism. More details can be found in this guide's next section, Authentication Flow.

When a user accesses any link for SAP Build Work Zone, the trust between the subaccount and IAS (and optionally the connected IdPs) is leveraged. In contrast, the authentication for the Digital Workplace Service (DWS) iframe is achieved through a single_use_token. This is generated through an API call using the 'JAM' destination, leveraging OAuth2SAMLBearerAssertion as an authentication mechanism. This process is transparent to the user of SAP Build Work Zone, advanced edition or SAP SuccessFactors Work Zone, and doesn't require any additional login screen or other form of user interaction. It happens in the background.

To recap, here's the anatomy of the SAP Build Work Zone product to understand the role of the DWS iframe.

When examining this flow, the following elements must be considered:

SAP BTP Platform Level

In the "JAM" destination, the following two properties must be considered specifically. By default, they're created as follows:

• nameIdFormat = urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
• userIdSource = user_uuid

While other attributes can be used for the userIdSource, the nameIdFormat remains as 'unspecified'. The exception is using the e-mail address as the unique identifier. In that case, the 'JAM' destination properties is adjusted as follows:

• nameIdFormat = urn:oasis:names:tc:SAML:1.1:nameid-format: emailAddress
• userIdSource = e-mail

Identity Provider Level

The userIdSource property in the "JAM" destination is referring to the assertion attributes configured in Identity Authentication or the connected IdP. The attributes are pushed to SAP BTP via the SAML2 assertion or the OIDC token attributes.

Digital Workplace Service (DWS) Level

For the single_use_token API call to be successful, the "JAM" destination properties must match the configured SAML Trusted IdP, which is configured automatically during the SAP Build Work Zone or SAP SuccessFactors Work Zone onboarding wizard. By default, it's referring to the SCIM.userName attribute in the user record, but can alternatively connect to either SCIM.externalId or the SCIM.emails.value to find a unique user. If emails.value is leveraged, the nameIdFormat property in the "JAM" destination and the trusted IdP on DWS level must be adjusted accordingly. The following code is an extract of the DWS user profile maintained through the user management (SCIM) API, specifically outlining the fields that can be leveraged for this authentication flow.

Code Snippet

Copy codeSwitch to dark mode

1234567891011
[…]
"userName": "", 
"externalId": "", 
"emails": [ 
{
"value": "", 
"primary": true
}
], 
[…]

Note

If the API call to create this single_use_token fails, the Digital Workplace Service (DWS)<> Identity Authentication (IAS) trust based on SAML2 is leveraged. In this case, the Subject Name Identifier configured in Identity Authentication for the Digital Workplace Service (not the one for the SAP BTP subaccount) must match the SCIM.userName in the user record.

As a result, the DWS layer automatically has two trusted IdPs available after completing the initial setup. They must not be changed or disabled.

To summarize, here are the two authentication flows connected to those IdPs and related configuration settings:

Standard authentication flow

• Subject Name Identifier = Login Name (or whatever else required): Which is what is used on the SAP BTP subaccount to create the "shadow user", and what you leverage for principal propagation for the SAP Cloud Connector integration setup
• Assertion attribute must include the IAS UUID:
  • … This assertion attribute (not the SNI) is used as the UserIdSource in the JAM destination for retrieving the single_use_token and other calls (for example, search, notification bell, and so on.)
  • … You can also configure a different attribute to be used across the setup, it just needs to be consistent:
    • SAML Trusted IDP in SAP Build Work Zone = SCIM userName/externalID & NameIdFormat
    • IAS assertion attribute = Matching what is selected
    • JAM destination = Matching userIdSource & NameIdFormat

Fallback authentication flow

Subject Name Identifier = IAS UUID:

• … Other assertion attributes aren’t required or relevant.
• This SAML Trust is only used as the fallback for the Digital Workplace Service (DWS). Therefore, the SNI for this application has to match the SCIM userName of the users in SAP Build Work Zone.