Overview

Use this module to implement single sign-on with your OIDC-compliant identity provider. Supports responsive and native mobile applications. Tested against Google, Salesforce, Apple, Okta, Ping, and Microsoft, this module manages the end-to-end SSO workflow when working with an OIDC identity provider. Simply provide configuration details, decide how you'd like to provision users, and log in!

NOTE: this module is provided with community support. 

If you prefer to use a platform supported module, please use “OIDC SSO”, which can be used for apps on Mendix 9 onwards. Both modules have similar but not the same features. Please look at release notes and documentation to make the best choice for your app.

Documentation

Description

OpenIDConnect (OIDC) client module. Allows your app to become an OIDC client, and lets your users log in via Single Sign-on (SSO). Built primarily in standard Mendix components (minimal Java) to allow for easy customization and ongoing development. OpenIDConnect is an extension of OAuth2.

Works with web/responsive and native mobile applications. 

Typical usage scenario

Authenticate and authorize your users in your application using corporate credentials hosted by your identity provider. Optionally, use the token you receive to make API calls on behalf of your user.

Features and limitations

- Supports SSO login with one or multiple OIDC/OAuth-compatible identity providers using the Auth Code flow

- Stores an access token for each user that can be used to make API calls on their behalf. Includes helper microflows (GET, POST, PUT, PATCH, DELETE) to easily leverage a token and automate the token refresh process.

- Supports web and native mobile apps

- Works with the Mendix DeepLink module

Dependencies

• Mendix 9.8.1+
• Encryption
• CommunityCommons
• NanoflowCommons
• NativeMobileResources
• JARs (included):
  • java-jwt
  • jwks-rsa
  • commons-codec
  • jackson-annotations
  • jackson-core
  • jackson-databind

Installation

1.  Add this module into your app

2.  Ensure you have added CommunityCommons, NanoflowCommons, NativeMobileResources, and Encryption from the app store as well.

3.  Assign your Admin user role the Administrator module role.

4.  Enable anonymous users if you haven't already. Assign your Anonymous user role the Anonymous module role.

5.  Assign your regular user role(s) to the Users module role.

6.  Add Snip_Configuration (OpenID Setup) to a page in your responsive navigation profile

7.  The Make it Native app has deep link functionality buillt-in, and this module uses its URL scheme by default. When you build your own app, it will also need to include deep link functionality. Change the URLScheme constant to match your chosen URL scheme.

8.  Use the snippets starting with "Snip_Login" on your Anonymous user role home pages.

9.  Be sure to set an encryption key in the Encryption module. The constant to set is called EncryptionKey and should be a random value 16 characters long.

10.  Do a batch layout-replace for all the layouts used in pages in this module that end in "REPLACEME" to replace those usages with layouts from your own project.

11. Optionally, add a menu item or button that calls the nanoflow ACT_Logout to perform a logout from this app and your identity provider.

OIDC Provider Configuration

1. In your identity provider, provision a new OpenID client WEB application. You want a web application that uses the auth code flow, even for native mobile Mendix apps. You will receive a ClientID and Client Secret.
2. You will also need either the OIDC configuration endpoint (for example: https://accounts.google.com/.well-known/openid-configuration)
3. Register the callback urls:
   1. http://yourappurl/oauth/v2/callback

OIDC Client (this app) Configuration

1. Start your app, log in as an admin, and access the OpenID Setup page.

2. Add a new client configuration with the ClientID, ClientSecret, and endpoints provided by your OpenIDConnect provider. If you have the automatic configuration url, enter it and click "Import Configuration" to automatically fill the other endpoints.

3. Select your scopes. The stand set are "openid, profile, email". If you need refresh tokens for your users, you'll also want the "offline" scope. Add other scopes as needed.

4. Select your provisioning flow. By default, this module will use a standard OpenID claims to provision users in your app. Also included is a flow that users the standard UserInfo endpoint in OIDC, which is useful in the case that your identity provider uses "thin tokens". Also included is a salesforce-specific example. You may need to make changes in order to implement provisioning logic fits your business needs. To do so, read the section on Custom User Provisioning.

Custom User Provisioning

Review the microflow CUSTOM_UserProvisioning. This is where should go to change the way that users are provisioned in your app. Here you receive the OAuth token. Use that data to find/create and return an Administration.Account object for the user. You can find examples included in the "User Provisioning Examples" folder.

This module support multiple identity providers. Since each provider might provide user data in a slightly different way, you may want to use multiple provisioning flows. See the microflow UserProvisioning_Sample for a sample and details on how to do this.

DO NOT CHANGE THIS MODULE except for CUSTOM_UserProvisioning. Make a single call from this microflow to your own module where you implement the provisioning flow you need. This way, it will be easy to install new versions of this module over time without overwriting your changes.

Deep Links

To use this module in conjunction with the DeepLink module, you'll need to set the LoginLocation constant of the DeepLink module to '/oauth/v2/login?cont='

Logging Out 

A standard logout action will end your Mendix session, but will not end your SSO session. To perform an SSO logout (also known as SLO), use the nanoflow ACT_Logout, which will redirect your user to the identity provider’s “end session endpoint” if configured.

Troubleshooting

• If you have an error stating “Navigating to a native page is not supported on nanoflows”, this is caused by a lack of a Native Navigation Profile in your app. To fix it, you can either:
•  
• - delete the offending “open page” activity in ACT_OpenLoginInWebView
• - add a native profile to your app

Known Issues

None