To set up a Federated Authentication in your OutSystems applications, using the SAML protocol to connect to external identity providers you can take advantage of the IdP Forge component, a generic federated identity provider (IdP) connector. IdP allows your OutSystems applications to integrate with Single Sign-On (SSO) provided by most of the commercial Identity Provider companies.
Since Platform Server Release Jul.2019 CP2 (August 23rd, 2019) you can configure a SAML 2.0 authentication for the whole environment directly in the Users application. Check the documentation on how to Configure SAML 2.0 Authentication.
With this integration, when the users access an OutSystems application (Service Provider - SP), they are redirected to a web page (known as the enterprise's login manager) where they are prompted to enter their enterprise user name and password. Upon verification of the user’s login, the enterprise identity provider informs the OutSystems application of the verified identity of the user who is logging in, and the user is redirected back to the portal website.
To successfully establish the connection between the IdP component and the Identity providers you'll need to change the authentication flow and configure both parties to redirect the user to the Login of the Identity Provider. In this article, we'll guide you through the needed setup.
In a standard OutSystems application there is a Common Flow responsible for handling authentication and exception.
One of the scenarios is when a user tries to access a resource that requires the user is authenticated, and the user is not authenticated yet.
In that case, the application raises a Security exception that will be handled in Common flow and then redirects the user to the login screen.
So, the first step to integrate an OutSystems application to change this behavior, and instead of redirect the user to the Login screen, redirect it to the Identity Provider.
Note: if the system contains multiple tenants, the tenant switch has to have been done before calling IdP_SSO_URL.
In a standard OutSystems application the Common Flow is also responsible for handling Logout operation.
By default, the Logout will invalidate the session on the OutSystems application server, but with an IdP SSO scenario many times the logout must be also performed on IdP Server, redirecting the browser to a specific URL on IdP SSO server.
So, to achieve that, it's necessary to change the Logout default behavior.
If your IdP Server allows a Logout initiated by the SP (IdP Connector), configure the field IdP server Single Logout URL which should be provided by your IdP Server (the IdP Connector will generate the SAML messages to perform a Single-Logout).
Note: Your application shouldn't call the User_Logout or Logout system actions. The IdP connector is the one responsible for that call.
Change Preparation of the LoginInfo to redirect the user to the URL provided by IdP Server
If your IdP Server allows a Logout initiated by the SP through SAML messages: call the action IdP_SingleLogout_URL and call the Common\ExternalURL with its output.
To configure the SAML Single Sign-On in the IdP component you must set up the values according to your Identity Provider.
IdP Server Issuer/Entity ID: A URL that uniquely identifies your SAML identity provider (IdP Server). SAML messages sent from IdP server must match this value exactly in the <saml:Issuer> attribute of SAML message.
<saml:Issuer>
IdP server Single Sign-On URL: The URL that IdP Connector should redirect to allow a user to sign in.
Certificate: The X.509 public certificate issued by your identity provider. Used to check the signature of SAML messages from the IdPServer.
SP Issuer/Entity ID: SAML Service Provider Issuer (SP Entity ID) sent in SAML messages from the IdP connector.
Optional (when required):
IdP server Single Logout URL: Identity Provider Server Single Logout URL. Used when the server allows SingleLogout initiated by the SP.
IdPConnector (SP) Keystore: The keystore that contains the private key and the public certificate that IdP connector uses to sign SAML messages sent to IdPServer (also to decrypt assertions if encrypted by IdP server). PFX/PKCS12 is the supported format.
KeyStore password: Keystore password to protect the keys in it.
Session_Cookie (site property): Variable that holds the cookie name that has the SessionId of the IdP connector (usually 'ASP.NET_SessionId')
Note: When updating the certificate, make sure you update it on both ends, in your Identity Provider and in OutSystems, in the IdP component.
Sign in to the Azure Active Directory portal and add the OutSystems Azure AD application from the gallery.
Navigate to Enterprise applications
Click New application.
Search for OutSystems Azure AD.
Select the application and click Add.
Select SAML as the single sign-on method.
In the OutSystems Azure AD application dashboard click the Single sign-on entry.
Select SAML.
Set up Single Sign-On with SAML.
Click the Edit icon on the Basic SAML Configuration section.
Set the required values accordingly.
Identifier (Entity ID): http://YOUR_SERVER/IdP/
http://YOUR_SERVER/IdP/
Reply URL (Assertion Consumer Service URL): https://YOUR_SERVER/IdP/SSO.aspx
https://YOUR_SERVER/IdP/SSO.aspx
You can then configure the IdP connector with the provided information in sections 3 and 4, or upload the Federation Metadata XML file downloaded in the Azure AD application.
Create an Okta trial account.
Go to the Okta website and sign up to create a trial account using your company email address.
You should then receive an email with your account details.
Sign in to your Okta domain.
Access your Okta domain homepage, as described in the email.
Input your username and password and click Sign In.
Add a SAML application to your Okta domain.
OutSystems Okta
Configure the SAML settings for the integration.
Set the Single sign on URL (URL in the OutSystems environment to handle the SAML response):http://YOUR_SERVER/IdP/SSO.aspx
http://YOUR_SERVER/IdP/SSO.aspx
Set the Audience URI (SP Entity ID):http://YOUR_SERVER/IdP/SSO.aspx
Click on the Show Advanced Settings link and set the remaining values
Signature Algorithm: RSA-SHA256
Digest Algorithm: SHA256
Click Next and you'll be asked for some information for feedback purposes. Select the option I'm a software vendor. I'd like to integrate my app with Okta and click Finish to complete the configuration.
Finally, click View Setup Instructions to get the data needed to configure the IdP connector.
You can add the values manually or optionally save the content of the "IDP metadata" in an .XML file and upload it on the IdP configuration page:
Create a free OneLogin account.
Log in to the admin console.
Click on Apps tab then click on Add App button.
Search for SAML and select SAML Test Connector (IdP) option.
Configure Display Name of your application and then click on Save button.
Click on the Configuration tab and configure the following properties.
ACS (Consumer) URL Validator: URL of the OutSystems environment to handle the SAML response (http://YOUR_SERVER/IdP/SSO.aspx)
ACS (Consumer) URL: URL of the OutSystems environment to handle the SAML response (http://YOUR_SERVER/IdP/SSO.aspx)
Click on SSO tab and configure the following properties
Finally, configure the IdP connector with the provided information.
Create a free Ping Identity account.
Click on the Applications tab then click on Add Application button.
Select New SAML Application option.
Configure application name, description, category and click on Continue to Next Step.
On Application Configuration configure the following properties
Assertion Consumer Service (ACS): URL of the OutSystems environment to handle the SAML response (http://YOUR_SERVER/IdP/SSO.aspx)
Entity ID: URL of the OutSystems environment to handle the SAML response (http://YOUR_SERVER/IdP/SSO.aspx)
Signing Algorithm: RSA_SHA256
Click on Continue to Next Step and then Save & Publish.