OpenIDConnect Single Sign-on (OIDC, OAuth2, SSO)
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
- Mendix 8.18+ (Mendix 9 compatible)
- JARs (included):
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
- In your identity provider, provision a new OpenID client application. You will receive a ClientID and Client Secret.
- You will also need either the OIDC configuration endpoint (for example: https://accounts.google.com/.well-known/openid-configuration)
- Register the callback urls:
Note: if your IDP does not support a custom URL scheme as a callback URL, that’s ok. Simply change the setting Provider supports custom URL schemes to false.
Note: Swap out makeitnative for your own custom URL scheme when you build your own native app! Be sure to set the MobileURLScheme constant to match.
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.
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='
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.
- 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