Mobile SSO

1 Introduction

The Mobile SSO module allows end-users of your mobile Mendix app to sign in via Single Sign-On (SSO) using the OpenID Connect (OIDC) protocol. As the Mobile SSO module depends on the OIDC SSO module for authentication, your IdP needs to support this protocol.

The following diagram gives an overview of architecture of the module:

The versions of the Mobile SSO module listed below depend on the Mendix versions.

1.1 Typical Usage Scenarios

• B2E app: Your app is aimed at your company’s employees, and you want these employees to sign in to your app using corporate credentials hosted by your identity provider (IdP) that supports the OIDC protocol. In this case, your app may have its own logic to assign user roles, or you may use authorization information from your IdP as provided to your app using an access token.
• B2C app: Your app is aimed at your customers, which could be consumers or employees of the other companies. Consumers may have an identity at a social IdP which uses OIDC, such as Google.

1.2 Features and Limitations

1.2.1 Features

The Mobile SSO module has the following features:

• Supports native mobile apps
• User role assignment from your IdP

1.2.2 Limitations

This module has the following limitations:

• Mendix sessions in the mobile app do not time out.
• Mobile SSO module does not support any other protocol except OIDC.
• IdPs that lack support for Custom callback URLs, such as Facebook, are not supported.
• Private use URI Schemes as per RFC8252, section 7.1 are not used.
• Approximately 5% of sign in attempts for the iOS app are unsuccessful, resulting in an error message indicating failure to sign in. However, a subsequent attempt usually leads to successful sign in.

1.2.3 Adherence to OAuth/OpenID Connect Protocol Specifications

This section clarifies to what extent a Mobile Mendix app using Mobile SSO module adheres to best practices for mobile SSO as per RFC 8252:

• The Mobile SSO module uses an embedded browser for sign in and does not utilize an external browser.
• Native Mendix apps have a back-end counterpart that holds the credentials for client authentication, as shown in the diagram above. This makes the native app a confidential client instead of a public client.

2 Dependencies

The Mobile SSO module requires your app to be using Mendix 9.24 or above.

It requires the following Marketplace modules to be included in your app:

• OIDC SSO
• Native Mobile Resources

3 Installation

This guide provides the step-by-step process of integrating the Mobile Single Sign-On (SSO) module into your Mendix Studio Pro application.

1. Add the Mobile SSO module to your app.

2. Add the necessary dependencies listed above from the Marketplace, if they are not already included in your app.

3. Follow the OIDC SSO documentation to configure the app security settings for the OIDC SSO module.

   From an IdP perspective, Mendix mobile apps behave as single page web apps (SPA), so specific instructions for desktop or mobile apps do not apply.

4. Ensure that you have allocated the following user roles to the Mobile SSO module roles:

   User Role	Mobile SSO Module Role
   Anonymous	MobileSSO.Anonymous
   User	MobileSSO.User

4 Configuration

This section shows you how to configure your app to use Mobile SSO.

4.1 Configuration Settings

Refer to the OIDC SSO documentation for the configuration settings of the OIDC SSO module and ensure the OIDC_Client_Overview page is appropriately set up.

4.2 Configuring Navigation

In the Native mobile (tablet & phone) tab, configure the Role-based home pages. To do this, add the Anonymous role and set the target with the following options:

• Use MobileSSO.Login_Native when you do not want to automatically redirect to the Identity Provider (IdP) login page, especially when only one IdP is configured. This option allows end-users to sign in directly without redirection.
• Use MobileSSO.Login_Native_Automatic if you want end-users to redirect automatically to the IdP sign in page when only one IdP is configured.

4.3 Configuring Custom Login Page

If you want to customize the login page, make sure to add the App events widget in the page and call the MobileSSO.OL_RegisterDeeplink nanoflow. This step helps to integrate the custom login page with Mobile SSO module.

4.4 Configuring Client Information

Follow the General OIDC Providers section of the OIDC SSO documentation for configuring client information.

The following subsections show how to set up IdP for mobile or web and mobile platforms:

4.4.1 Configuring IdP for Mobile

When testing locally, add the makeitnative://oauth/callback URL in the Custom callback URL tab. This configuration also supports signing in with acr_values.

4.4.2 Configuring single IdP for Web and Mobile

If you are building SSO application, you can use the common IdP configuration for both web and mobile platform, ensuring that this IdP configuration is not specific to any particular device.

To do this, follow the steps below:

1. Replace the SUB_GetCallbackURL sub-microflow from the OIDC SSO module with the SUB_GetMobileCallbackURL microflow of the Mobile SSO module in the handleAuthorizationCode and GetAuthorizationURL microflows.
2. In the Mobile SSO module, go to the Configuration in the helpers folder and add the <appname> in the MobileURLScheme constant.

4.5 Single Log Out

A standard sign out action will end an end-user’s Mendix session, but it will not end their SSO session. To perform a single sign out, also known as Single Logout (SLO), use the nanoflow ACT_NativeLogout. This nanoflow redirects end-user to the end session endpoint of the IdP if it is configured. To do this, add a menu item or button to call the nanoflow ACT_NativeLogout.

4.6 Building Native Mobile App

When you are building the native mobile app using Build Native Mobile App option, make sure to follow the steps below:

1. Turn on Deep Link.
2. After turning on the Deep Link, add the same appname from <appname>://oauth/callback to the App Scheme. For more information, see the Configuring Client Information section above.

4.7 Configuring IdP

The following subsections show how to configure your Entra ID or Okta IdP:

4.7.1 Configuring IdP for Entra ID

1. On the Microsoft Entra ID portal, select App Registrations.

2. Click New registration, provide required information, and click Register.

3. In the Authentication tab, select No to disable the option to Allow public client flows as this module only supports confidential client flows.

   

4. Add the following JSON representations to the Manifest of the application:

   1. For the application that has been deployed using Build Native Mobile App

      "replyUrlsWithType": [
       {
          "type": "Web",
          "url": "<appname>://oauth/callback"
       }
      ],
      

      Use the same <appname> which you used in the Custom callback URL tab of the configuration and while building the application using Build Native Mobile App. For more information, see the Configuring Client Information and Building Native Mobile App sections above.

      

   2. For local testing, use the JSON below in the Manifest of the application:

      {
          "url": "<https://<IP_address>>/oauth/v2/callback",
          "type": "Web"
      },
      {
          "url": "makeitnative://oauth/callback",
          "type": "Web"
      }
      

      Make sure to add makeitnative://oauth/callback to the Custom callback URL tab of the configuration. For more information, see the Configuring Client Information section above.

5. Save the Manifest file.

6. In Entra ID, click the Certificates & secrets tab of the application and create New client secret. You can use this Value in the Client Secret field on the OIDC_Client_Overview page of the OIDC SSO module.

7. Click Overview tab of the application and copy Application (client) ID. Use this copied value in the Client ID field on the OIDC_Client_Overview page of the OIDC SSO module.

8. Import the configuration in the page and add the required scopes such as, openid, profile, and email.

9. Save the configuration and you can sign in into the application using Azure SSO.

4.7.2 Configuring IdP for Okta

1. Go to the Okta portal and click Create a new app integration.

2. Select OIDC-OpenID Connect option for the Sign-in method.

3. Select Native Application for the Application type and click Next.

   

4. In the Sign-in redirect URIs of the LOGIN field, add the following application URI:

   1. For the application that has been deployed using Build Native Mobile App: <appname>://oauth/callback

      Use the same appname which you used in the Custom callback URL tab of the configuration and while building the application using Build Native Mobile App. For more information, see the Configuring Client Information and Building Native Mobile App App sections above.

      

   2. For local testing: http://<IP_address>/oauth/v2/callback and makeitnative://oauth/callback

      Make sure to add makeitnative://oauth/callback to the Custom callback URL tab of the configuration. For more information, see the Configuring Client Information section above.

      

5. Save the configuration and use the Client Secret, Client ID, and Automatic Configuration URL to import the configuration in the OIDC_Client_Overview page of the OIDC SSO module.

6. Add the required scopes such as, openid, profile, and email.

7. Save the configuration and you can login into the application using Okta SSO.

5 Testing and Troubleshooting

5.1 IdP Integration

After adding the IdP details to the web page, the IdP sign in tab is visible on the mobile screen.

5.2 Login and User Landing

Click IdP login to redirect to the IdP sign in page. After successful authentication, you will be directed to the user landing page, indicating successful integration of the Mobile SSO module.