XSUAA Connector for SAP Business Technology Platform

Last modified: April 18, 2024

1 Introduction

XSUAA is a service provided by the SAP Business Technology Platform (SAP BTP) that will bind to the Mendix application as soon as the application is deployed within the SAP Business Technology Platform (SAP BTP) using the deployment features in the Mendix Developer Portal.

Out of the box, SAP BTP has the SAP external identify provider (IDP) configured as the default IDP. It is possible to use your own (corporate) IDP as an alternative so that you can automatically give access to all the employees of your organization.

1.1 Typical Use Cases

When you deploy an application to SAP Business Technology Platform (SAP BTP) using the SAP deployment features of the Mendix Developer Portal, it is bound automatically to the XSUAA service. This service allows you to use an external identity provider (IdP) for a Mendix application. In this way, instead of having their user credentials stored separately in the Mendix app, the user can sign on to their app using the IdP and thus have a single sign-on (SSO) experience with their application.

In this diagram, the relationship is shown between groups, roles, and users in relation to the Mendix application and the IdP:

A Mendix application is role-based by default. When deploying a Mendix app to SAP BTP using the deployment features in the Mendix Developer Portal, the SAP BTP application configuration is automatically created (identified in the yellow section of the diagram above). This configuration reflects the roles that are defined in the Mendix app (identified in the blue section of the diagram).

To assign users from the IDP to these roles generated by the model, the account admin needs to add the mapping between the IDP user groups and the role templates (identified in the orange section of the diagram).

1.2 Prerequisites

Before starting this how-to, make sure you have completed the following prerequisites:

Create an SAP app using an SAP app template
Select and deploy the app to an SAP account and subaccount where you have authority to configure security
Set the security level for the app to at least Prototype/demo to use SAP Authentication; for more information see App Security and for instructions on setting security levels, see How To Create a Secure App
Set up the app with the following two User roles in App > Security: Supervisor and Inspector
Ensure the app behaves differently according to the user role, so you can see the effect of setting up the roles in XSUAA. For example, give each role a different starting page as described here: Setting Up Navigation

2 Installation

The SAP app may already have the XSUAA Connector for SAP Business Technology Platform installed. If installed, you can find it in the App > Marketplace modules list for the SapAuthentication module.

If the connector is not already in your app, download it from the XSUAA Connector for SAP Business Technology Platform page in the Mendix Marketplace, and then follow the instructions in Using Marketplace Content to import the connector into your app.

3 Configuration

After you install the connector, you can find it in the App > Marketplace modules list, in the SapAuthentication section. Before you can use the connector, you must first perform the necessary configuration steps.

You need to provide your own xs-security.json file to add custom configuration to your XSUAA connector.

Ensure that the xsuaa service is in the status Services To Be Bound. See the Services Tab section of SAP Business Technology Platform for more information.
Click the three dots … next to the xsuaa service and select Add Binding Configuration.

You then have two options:

3.1 Use the XSUAA Configurator

The XSUAA Configurator provides a user friendly interface to create the JSON required to configure the XSUAA service. It can be uploaded automatically for you, or you can download the file and upload it manually.

The configurator will only create a JSON file from scratch. It does not have access to your existing XSUAA settings on SAP BTP, and you cannot import an existing JSON files.

You cannot change the xsappname in the configurator – this is generated automatically for your app by the Developer Portal.

Click ⚙️ Configurator to open the configurator.
Set up the configuration in the sections shown on the screen.
Click Upload Configuration To Service to upload the configuration automatically. The configuration will be applied when your app is restarted.

Alternatively, click Download Configuration File to save the file locally so that you can review it, or reuse it. You can upload it manually to the XSUAA service using the instructions in the next section.

3.2 Upload Configuration JSON

You can upload your own JSON configuration file, either created from the XSUAA Configurator or handcrafted.

Click Browse… next to the Configurator JSON option.
Choose the file containing the XSUAA configuration you want to use.

The configuration will be applied when your app is restarted.

4 Usage

When XSUAA is enabled on SAP BTP and the XSUAA Connector for SAP Business Technology Platform is part of the Mendix application, an IDP user automatically becomes a Mendix application user. They will be assigned to the roles in the Mendix application based on the scopes they have received from the XSUAA service. The scopes are defined by the mapping between the role templates and the role collections.

When the IDP user is added to the Mendix application, they are given a randomly generated password to prevent the user being logged in using the local credentials. You can control the length of this randomly-generated password using the SapAuthentication.PasswordLength constant. This can also be set via an environment variable. SapAuthentication.PasswordLength should be at least 8, with a maximum value of 12.

For more information about implementing this capability in your app, see the following sections.

SAP Authentication will not work if the App Security is off. See the prerequisites above.

4.1 Adding the OnStartup Microflow to the Application Settings

The app needs to be bound to the SAP XSUAA service. This is achieved by executing a microflow when the app starts. This may have been set up already if XSUAA was included in your app template.

To add the After Startup microflow to your application, follow these steps:

In the App Explorer, select App > Settings and open the Runtime tab.
For the After Startup microflow, select the microflow Marketplace modules > SapAuthentication > USE_ME > ASu_StartXSUAA.

By default, the Mendix login page will not allow the user to enter their SSO credentials. There are two ways of changing the login page:

Add the SSO login button so the user can choose whether to use SSO or native Mendix credentials
Bypass the Mendix login page altogether and just display the XSUAA login page

If you are using the Deep Link module, you will also need to set the LoginLocation constant to /xsauaalogin/login?ret=.

4.2.1 Adding the SSO Login Button to the Login Page

If your app already had XSUAA included, your login.html file may have been modified already.

If login.html does not support XSUAA then you need to add the SSO login button to the landing page. Do this by following these steps:

In the top menu of , select App > Show App Directory in Explorer.
Open the theme folder.
Copy the content of login-with-sso.html to login.html.
Open login.html for editing.

Locate the following lines:

1
2
3
4


<a id="ssoButton" href="/openid/login" class="btn btn-default btn-lg">
    <img src="logo.png" />
    <span class="loginpage-signin">Mendix Account</span>
</a>

Replace those lines with the following lines (or add them below the <a> element in the code above):

1
2
3
4


<a id="ssoButton" href="/xsauaalogin/" class="btn btn-default btn-lg">
    <img src="logo.png" />
    <span class="loginpage-signin">Sign in using XSUAA</span>
</a>

Deploy and run your app. The XSUAA login button will look like this:

An alternative to adding the SSO login button to the landing page of your app is to redirect your app to XSUAA automatically without showing the login page.

Note that this will only work if you are running your app on SAP BTP.

Because users will be automatically redirected to XSUAA after signing out of the application, this could cause them to be signed in again.

To accomplish this, follow these steps:

Open the app directory of your app and then open the theme folder.

Change the contents of login.html to the following:

1
2
3
4
5
6
7
8


<!doctype html>
<html>
    <head>
        <script>
            window.location.assign("/xsauaalogin/")
        </script>
    </head>
</html>

4.3 Configuring the SAP BTP Subaccount

Your app is configured to use an IdP. Now you need to configure the IdP and allocate users to roles. This is performed in the SAP Business Technology Platform cockpit.

Before configuring the IdP, you must first deploy your app to SAP BTP. This will expose the user roles in the app to the security configuration tools in the SAP BTP cockpit.

This section describes actions which are carried out using the SAP BTP cockpit. This document uses the current navigation through the SAP BTP cockpit but this is outside the Mendix environment and may be changed. SAP BTP documentation is in the SAP Help Portal.

The diagram below shows the relationship between the security structures in your Mendix app (blue), the SAP BTP app environment (yellow), SAP User Account and Authentication (orange), and the IdP (green).

Once the user has been authenticated, various attributes (the user’s name, for example) are copied from the IdP User (green) to the User entity within the Mendix application (blue) so that they can be used by the app. However the authorization credentials remain in the IdP and the user cannot access the app by using credentials stored in the app.

4.3.1 Scope

When your app is deployed to SAP BTP, each User Role (A) in the Mendix app is exposed as a Scope (B) in the SAP environment. You can see this mapping by going to your app in the SAP BTP cockpit. Under Security you can view the Scopes. You will see that the four User Roles in the Mendix app are exposed as scopes in the application space:

4.3.2 Role Template

Each Scope is mapped to a single Role Template (C) during deployment. You can see the Role Templates in the Application details of the SAP BTP cockpit. These are also defined during the deployment of the app.

The Attributes of the Role Template are not used by Mendix in linking Mendix Roles to SAP Roles.

4.3.3 Role

In the SAP BTP cockpit, you can view and add additional Roles (D) to the Role Template, or you can stay with the generated default role. Note that new roles added here do not have different roles in your Mendix app. However, adding new roles may allow you to obtain additional analytics through the SAP or IdP logs. Here a new Inspector role (Inspector 2) has been added to the Inspector Role Template.

4.3.4 Role Collection

The Role Collection (E) is defined not for the app deployed to SAP BTP, but in your SAP Subaccount. It is this Role Collection which will be linked to the IdP.

There may be other Role Collections which are being used by other apps deployed in this subaccount and you may, or may not, wish to share authentication between apps. You could, for example, use the same authentication for several related apps running in the same subaccount which have the same app User Roles. Or you may wish to use different authentication for development and production environments.

Here, we add a new Role Collection for the Inspector 2 role in the SAP BTP space roles.

Give the new Role Collection a name and, optionally, a description.
Click on the Name of the Role Collection to allocate roles to the Role Collection.
Add the Role (or Roles) which you want to include in this Role Collection.

The new role collection can now be seen in the SAP BTP cockpit for this Subaccount, with the Role (or Roles) which it includes.

4.3.5 Trust Configuration

Your Subaccount will have one or more Trust Configurations. These are the IdPs which you can use to authenticate your users. The default is the SAP ID Service but you may add other IdPs.

Depending on the IdP, you can either map Users (G) directly to a Role Collection, or map a User Group (F) to a Role Collection. Users are mapped by the IdPs own configuration to the User Group.

4.3.5.1 Map User Directly to a Role Collection

This is the method used by the SAP ID Service, amongst others.

Click on the SAP ID Service in the Trust Configurations.
Enter the username (email) of an SAP user that you want to give access to.
Click Show Assignments to show existing assignments.
Click Add Assignment and choose the Role Collection (in this case Inspector 2) to which you want to grant access.

The selected user now has access to the selected Role Collection and, through that, to the correct User Role in your app.

You can picture the authentication as shown below:

4.3.5.2 Map User Group to a Role Collection

Some IdPs (for example SAML 2.0 IdPs) have the concept of a User Group. In this case there will be two options in the Trust Configuration for the IdP: Role Collection Mappings and Role Collection Assignment.

You can link an individual username to the Role Collection in the same way as described above using the Role Collection Assignment option.

Alternatively, you can link a Role Collection to an existing Group within the IdP. In this case, you need to do the following.

Open Role Collection Mappings for the IdP.
Create a new Role Collection Mapping and map the Role Collection (for example, Inspector 2 Role Collection) to an existing Group (for example, Inspector 2 Group) in the IdP.

Now any user within the IdP which is part of the Inspector 2 Group will have access to the correct role in your Mendix app.