IdP Instructions

Content

2. How to Configure SAML 2.0 for OutSystems IdP Connector Application

3. IdP Configuration Examples (Okta, OneLogin & PingOne)

IdP Connector is a generic federated identity provider (IdP) connector. It allows your OutSystems applications to integrate with single sign-on (SSO) provided by most of the commercial IdP companies.

With this integration when the users access an OutSystems application, 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 OutSystems application of the verified identity for the user who is logging in, and the user is redirected back to the portal website.

This image illustrates the following steps:

The user attempts to reach a hosted OutSystems application

OutSystems generates a SAML authentication request

OutSystems sends a redirect to the user's browser

SSO decodes the SAML request and authenticates the user

SSO generates a SAML response that contains the authenticated user's username. In accordance with the SAML 2.0 specification, this response is digitally signed with the partner's public and private DSA/RSA keys

SSO encodes the SAML response and the RelayState parameter and returns that information to the user's browser.

OutSystems Idp Connector verifies the SAML response using the partner's public key

The user has been redirected to the destination URL

The user is logged in to OutSystems application

2. How to Configure SAML 2.0 for OutSystems IdP Connector Application

Configure your application to use IdP Connector.

1.1

Change NoPermission screen on Common Flow

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 require 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 behaviour and instead of redirect the user to the Login screen redirect it to the Identity Provider.

a) Create a site property to activate/deactivate IdP
b) Change NoPermission -> Preparation to redirect the user to the URL provided by IdP_SSO_URL action
Note: if the system contains multiple tenants, the tenant switch has to have been done before calling IdP_SSO_URL.

1.2

(Single-Logout: optional) Change LoginInfo web block on Common Flow

In a standard OutSystems application there is a Common Flow also responsible for handling Logout operation.
By default the Logout will invalidate the session on the OS application server, but with a 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, in order to achieve that, it's necessary to change the Logout default behaviour.

If your IdP Server allows a Logout initiated by the SP (IdP Connector), then configure the field 'IdP server Single Logout URL' which should be provided by your IdP Server (this IdP Connector will generate the SAML messages to perform a Single-Logout).

NB: Your application cannot call the system actions User_Logout or Logout. IdP connector is the one responsable for that call.

a) Change Logininfo -> Preparation to redirect the user to the URL provided by IdP Server
a1) 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

Configure IdP Connector accordingly to your Identity Provider

What you will need to configure SAML SSO are:
   - the URL of the SAML Identity Provider (IdP) handling user sign-in requests
   - the fingerprint of the SAML certificate that the IdP Server uses to sign the SAML assertions sent to this IdP Connector (SP)
   - the issuer sent by IdPServer in SAML messages (IdPServer issuer)
   - the SP (IdPConnector) issuer sent in SAML messages from this connector

Optional (only when required):
   - IdpServer Single-Logout URL (if IdP Server support Single Logout initiated by SP through SAML messages)
   - PFX/PKCS12/JKS (JKS java stack only) keystore with the key to sign messages sent from SP and to decrypt assertions if the IdP SSO server is configured to encrypt the assertions
   - Keystore password to ready the keys in it
   - The Site property 'Session_Cookie': this variable holds the cookie name that has the SessionId on the IdPConnector OS server. Usually 'ASP.NET_SessionId' on .Net stack and 'OSSESSIONID' on Java stack

(In order to access the confguration screen the user need to have IdP_Administrator privileges. Managed in Users Application)

Configure your IdPServer to use the IdP Connector.

Configure IdPServer accordingly to your IdP Connector

What you will need to configure in IdPServer are:
   - the URL of the SAML SP (IdP Connector) handling user sign-in responses: its the URL of 'SSO' entry point in Auth flow
   - the SP issuer, used in SAML messages from IdP Connector
   - (optional) the public certificate (FROM SP Key Store). Used to IdPServer encrypt assertions and also checks the signature of SAML messages sent from the IdPConnector
   - (optional) the URL of the SAML SP (IdP Connector) handling Single-Logout Response messages sent from IdPServer: its the URL of 'SLOResponse' entry point in Auth flow
   - (optional) the URL of the SAML SP (IdP Connector) handling Single-Logout Request messages sent from IdPServer (ex: admin Logout): its the URL of 'SLORequest' entry point in Auth flow

3. IdP Configuration Examples

Okta example

Create a free Okta account (Okta for Developers)

Access Admin Dashboard by cliking on 'Admin' button

Click on 'Applications' tab then click on 'Add Application' button

Click on 'Create New App' button then select 'SAML 2.0' option

Define App name and click 'Next'

Configure the following SAML settings

- Single sign on URL: URL of the outsystems environement to handle the SAML response (http://YOUR_SERVER/IdP/SSO.aspx)
- Audience URI (SP Entity ID): URL of the outsystems environement to handle the SAML response (http://YOUR_SERVER/IdP/SSO.aspx)
- Assertion Signature: Unsigned
- Signature Algorithm: RSA-SHA1
- Digest Algorithm: SHA1

Click on 'Next' button and then 'Finish'

Finally click on 'View Setup Instructions' and configure IdP connector

OneLogin example

Create a free onelogin account

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 'Configuration' tab and configure the following properties

- ACS (Consumer) URL Validator: URL of the outsystems environement to handle the SAML response (http://YOUR_SERVER/IdP/SSO.aspx)
- ACS (Consumer) URL: URL of the outsystems environement to handle the SAML response (http://YOUR_SERVER/IdP/SSO.aspx)

Click on 'SSO' tab and configure the following properties

- SAML Signature Algorithm: SHA-1

Finally configure IdP connector with the provided information

PingOne example

Create a free Ping Identity account

Click on 'Applications' tab then click on 'Add App'lication 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 environement to handle the SAML response (http://YOUR_SERVER/IdP/SSO.aspx)
- Entity ID: URL of the outsystems environement to handle the SAML response (http://YOUR_SERVER/IdP/SSO.aspx)
- Signing Algorithm: RSA_SHA1

Click on 'Continue to Next Step' and then 'Save & Publish'

Finally configure IdP connector with the provided information