When you deploy an application to SAP Cloud Platform 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. This means that the user can sign on to their app using this IdP instead of having their user credentials stored separately in the Mendix app. This means that they can have a single sign-on (SSO) experience with their application.
A Mendix application is role-based. Using the SAP Cloud Platform cockpit, you can assign the roles within the app to roles within your SAP subaccount. The roles in the SAP subaccount can then be assigned to individual users via the selected IdP (Trust Configuration).
In this document, you will see how to use the XSUAA Connector for SAP Cloud Platform to provide SSO in an app which has two roles: Supervisor and Inspector.
This how-to will teach you how to do the following:
- Add the XSUAA Connector to your project
- Configure the XSUAA connector within your app
- Configure security in your SAP subaccount and space to allow users to access the app using SSO
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 project to at least Prototype/demo to use SAP Authentication; for more information see Project Security and for instructions on setting security levels, see How To Create a Secure App
Setup the app with the following two User roles in Project … > 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: How To Set Up the Navigation Structure
3 Getting the XSUAA Connector for SAP Cloud Platform Module
The SAP app may already have the XSUAA Connector for SAP Cloud Platform installed. Look in Project… > App Store modules for the module SapAuthentication. This is the XSUAA connector.
If the XSUAA Connector for SAP Cloud Platform is not already in your project, download it from the App Store. It can be found here: XSUAA Connector for SAP Cloud Platform.
For more information, see How to Use App Store Content in Studio Pro.
4 Using the Connector
In this section, you will learn how to implement the XSUAA connector in your Mendix app.
SAP Authentication will not work if the Project 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 Project Explorer, select Project … > Settings and open the Runtime tab.
- For the After Startup microflow, select the microflow App Store Modules > SapAuthentication > USE_ME > ASu_StartXSUAA.
4.2 Changing the Login Page to Allow XSUAA SSO
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 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 Project > Show Project 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:
<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):
<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:
4.2.2 Redirecting Your Application to XSUAA Without Showing the Login Page
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 Cloud Platform.
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 project directory of your project and then open the theme folder.
Change the contents of login.html to the following:
<!doctype html> <html> <head> <script> window.location.assign("/xsauaalogin/") </script> </head> </html>
5 Configuring the SAP Cloud Platform 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 Cloud Platform cockpit.
Before configuring the IdP, you must first deploy your app to SAP Cloud Platform. This will expose the user roles in the app to the security configuration tools in the SAP Cloud Platform cockpit.
This section describes actions which are carried out using the SAP Cloud Platform cockpit. This document uses the current navigation through the SAP Cloud Platform cockpit but this is outside the Mendix environment and may be changed. SAP Cloud Platform documentation is in the SAP Help Portal.
The diagram below shows the relationship between the security structures in your Mendix app (blue), the SAP Cloud Platform 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.
When your app is deployed to SAP Cloud Platform, 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 Cloud Platform 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:
5.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 Cloud Platform 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.
In the SAP Cloud Platform 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.
5.4 Role Collection
The Role Collection (E) is defined not for the app deployed to SAP Cloud Platform, 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 Cloud Platform 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(s) which you want to include in this Role Collection.
The new role collection can now be seen in the SAP Cloud Platform cockpit for this Subaccount, with the Role(s) which it includes.
5.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.
5.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:
5.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.
You can picture the authentication as shown below: