You can integrate OutSystems in your Federated Authentication system using the SAML 2.0 protocol to connect to an external Identity Provider (IdP), allowing for single sign-on (SSO) and single logout operations.
The general authentication workflow is the following:
- A non-logged in user tries to access an OutSystems application, known in SAML as the Service Provider (SP).
- The browser redirects the user to a web page, known as the enterprise's login manager, where they must enter their enterprise username and password.
- Upon verification of the user’s login, the enterprise Identity Provider informs OutSystems application of the verified identity for the user who is logging in, and the browser redirects the user back to the portal website.
The current SAML 2.0 implementation in OutSystems has some limitations outlined below. Since the OutSystems platform is being continuously improved, be sure to check this page regularly for an updated list of limitations.
- The SAML 2.0 support provided by the Users module is only applicable to Traditional Web Apps and Reactive Web Apps. To use SAML 2.0 in Mobile apps you can use Forge components that address those use cases, like IdP Connector and IdP Mobile.
Note: The Forge components mentioned above are not supported by OutSystems and are maintained by the Forge community.
To implement single logout you may need to change the authentication flows of your OutSystems application. Check below for details.
Though the Users application is multi-tenant, multi-tenancy is not supported when using SAML 2.0, Azure AD or OKTA authentication methods.
If you have some logic that must run at each login, or if your IdP has some particular configuration not supported by the Users application, consider cloning the Users module of the Users application and extend it to fulfill your specific requirements.
Using SAML in your OutSystems applications
To configure SAML 2.0 end user authentication you need to take the following steps:
- Configure SAML 2.0 authentication in the Users application.
- Check if your application authentication flows (login/logout) already support SAML 2.0. If not, you must change these flows according to the provided instructions.
Configure SAML 2.0 authentication in the Users application
Make sure you gather all the required information from your Identity Provider beforehand to be able to configure SAML 2.0 authentication in the Users application.
Do the following:
- In the Users application, click "Configure Authentication" in the sidebar.
SAML 2.0in the Authentication drop-down list.
Provide the required configuration values according to the Identity Provider you will be using.
Tip: To speed up configuration, and if your Identity Provider (IdP) has this feature, you can export a Service Provider (SP) metadata XML file in the Users application to import it in your IdP.
Similarly, you can import a Federation metadata XML file containing the IdP Server Settings in the Users application if your IdP has the option to export this metadata file.
Check the authentication flows of your OutSystems applications
Depending on the version of OutSystems UI Web (for Traditional Web Apps) or OutSystems UI Reactive Templates (for Reactive Web Apps) that was installed in your development environment when you created your application, you may need to update the login/logout flows of your app so that they are compatible with SAML 2.0 authentication.
For more information, check the following topics according to your application type:
- For Reactive Web Apps check Updating the login/logout flows of your Reactive Web App to support SAML 2.0.
- For Traditional Web Apps check Updating the logout flow of your Traditional Web App to support SAML 2.0.
Mapping Identity Provider Server Groups to OutSystems Groups
If you configure the Groups claim in the "Configure Authentication" screen of the Users application, when a user login occurs OutSystems tries to match each group name received from the external Identity Provider (Azure AD, OKTA, or another SAML-based provider) with the groups configured in the platform.
When there is a match, the Users application associates the user logging in to the existing OutSystems group. If there's no match, OutSystems first creates a new group with the same name as the Identity Provider Server group and then associates the user to that group.
Known limitation: In Azure AD, group names received from the Identity Provider Server consist only of a GUID identifier. This means that to have a match between Azure AD groups and OutSystems groups you must name the OutSystems groups using these GUID values.
Troubleshooting SAML authentication issues
Accessing message logs
The SAML Message Logs page is very useful when troubleshooting SAML configuration or authentication issues. It's available from the right sidebar by clicking "SAML Message Logs".
These logs are available for 7 days by default. You can customize this retention period using the
DeleteSAMLLogsOlderThen multi-tenant Site Property of the Users module.
To customize the value of this site property, do the following:
- Open Service Center, navigate to Factory > Modules and open the Users module.
- Open the Tenants tab and click the "Users" link to navigate to the Users tenant detail page.
- In the Site Properties tab, click the link to edit the
DeleteSAMLLogsOlderThenproperty and enter the new value for the site property.
Accessing the Users application when locked out
If your authentication configuration is incorrect and preventing you from logging in using SAML you can still login with an administrator account (it must be a user with the UserManager role) by navigating to the default users login page. This bypasses the configured authentication method, allowing you to login and fix the incorrect settings.
The default users login page is available at the following URL: