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 user is then redirected to a web page, known as the enterprise's login manager, where they will be prompted to 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 user is redirected back to the portal website.
The current SAML 2.0 implementation in OutSystems has some limitations that are outlined below. Since the OutSystems platform is being continuously improved, be sure to check this page regularly for an updated list of limitations.
- To implement single logout you must change the logout flow in your OutSystems applications according to the instructions provided in this page.
- The SAML 2.0 support provided by the Users module is currently only applicable to Web applications. To use SAML 2.0 in mobile apps you can use Forge components that address this use case, like IdP Connector and IdP Mobile.
- Though the Users application is multi-tenant, multi-tenancy is not supported when using the Azure AD or SAML 2.0 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:
- Change the Logout flow of your OutSystems applications.
- Configure SAML 2.0 authentication in the Users application.
1. Change the Logout flow of your OutSystems applications
Before you can use SAML 2.0 to authenticate your end-users you will need to change the Logout flow of your OutSystems applications.
By default, the Logout flow will invalidate the session in the OutSystems application server. However, in an IdP SSO scenario most of the times the logout must also be performed on the IdP Server, even though the logout operation may start on the Service Provider side (i.e. in an OutSystems application). This is done by redirecting the user to a specific URL in the IdP Server. In this case, you will need to update each OutSystems application that using Users as its user provider to perform this redirect when logging out a user.
Do the following:
In the Users application, configure the IdP server Single Logout URL field in the Configure Authentication page with the specific logout URL provided by your IdP Server.
In Service Studio, open the home module of your OutSystems application and open the Logout screen action of the LoginInfo web block, available at UI Flows > Common > LoginInfo.
In the next steps you will edit the flow to perform the redirect if the logout URL was specified in the SAML 2.0 configuration settings.
Get the IdP's logout URL using the User_GetUnifiedLogoutUrl server action (available in the Users module) and redirect the user to that URL.
After the User_Logout server action you should also handle the redirect to the IdP’s login URL.
Check the following sample flow for a possible implementation of all the steps above:
2. 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.
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 will be available for 7 days by default. This log retention period can be customized 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 will bypass the configured authentication method, allowing you to login and fix the incorrect settings.
The default users login page is available at the following URL: