SAML 2.0 SSO Setup in OutSystems: Azure AD, Okta, and Generic Providers

Open your browser and go to **forge.outsystems.com**. Search for **IdP** (by OutSystems). Click **Install** → select your environment → confirm installation. Once installed, open **Service Studio** → click **Open Application** → open **IdP** application. Publish the IdP module if prompted (1-Click Publish button, top center). After publishing, go to your environment URL and navigate to `/IdP/IdPPortal` to confirm the IdP portal loads without errors.

In the IdP Portal (`/IdP/IdPPortal`), click the **SP Metadata** tab. Click **Download SP Metadata XML**. This XML file contains: - **Entity ID** (your OutSystems SP identifier, e.g., `https://myenv.outsystems.net/IdP`) - **ACS URL** (Assertion Consumer Service URL — where the IdP posts the SAML response) - **Signing certificate** (public key OutSystems uses to verify signed assertions) Save this file — you will upload it to Azure AD or Okta in the next step.

**For Azure AD:** 1. Go to **Azure Portal** → Azure Active Directory → Enterprise applications → New application → **Create your own application** → name it (e.g., `OutSystems SAML SSO`) → select 'Integrate any other application you don't find in the gallery' → Create. 2. Go to **Single sign-on** → select **SAML**. 3. Click **Upload metadata file** → upload the SP Metadata XML from step 2. 4. Azure auto-populates Entity ID and Reply URL (ACS). Verify they match your SP Metadata. 5. Under **Attributes & Claims**: map `user.mail` → `Email`, `user.displayname` → `Name`, `user.userprincipalname` → `Username` (or match your OutSystems user attribute configuration). 6. Download the **Federation Metadata XML** — you will import this into the IdP component. **For Okta:** 1. Go to Okta Admin → Applications → Create App Integration → SAML 2.0. 2. Set Single sign-on URL = your ACS URL from SP Metadata. 3. Set Audience URI = your Entity ID. 4. Add attribute statements: email → user.email, name → user.displayName. 5. On the Sign On tab, click **View SAML setup instructions** and copy the IdP metadata URL.

Return to the OutSystems IdP Portal (`/IdP/IdPPortal`). Click **IdP Connectors** → **Add IdP Connector**. Fill in: - **Name**: Azure AD (or Okta) - **Type**: SAML 2.0 - **Metadata**: paste the IdP Metadata URL (Azure: federation metadata URL) OR upload the downloaded XML - **Username Attribute**: the SAML attribute name that maps to OutSystems username (e.g., `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress` for Azure AD) - **Email Attribute**: same value for Azure AD default config - **Auto-provision Users**: Yes (creates OutSystems user on first login) Save. The portal shows a summary with the IdP Entity ID, Single Sign-On URL, and certificate fingerprint.

1/* Azure AD — common attribute claim URIs */
2Username: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
3Email:    http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
4Name:     http://schemas.microsoft.com/identity/claims/displayname
5
6/* Okta — attribute names are shorter and configurable */
7Username: email
8Email:    email
9Name:     name

In **Service Studio**, open your application module. Navigate to **Data tab → Site Properties**. Look for a Site Property named `IdP.Connector` (created by the IdP component dependency). Set its **Default Value** to the name of your IdP Connector created in step 4. Alternatively, go to **Service Center** → Factory → Modules → your module → Site Properties → set `IdP.Connector` to your connector name per environment (Dev, QA, Production can have different IdPs). In your login screen Client Action (or in the Users module configuration), replace the standard login logic with a redirect to the IdP SSO URL: Action flow: Start → Navigate to GetLoginUrl() result → End The IdP Forge component exposes a `GetLoginUrl` Server Action — call this and redirect the user to its output URL to initiate the SAML flow.

1/* Server Action flow to initiate SSO */
2/* Logic tab → Server Actions → YourLoginAction */
3
4Start
5→ GetLoginUrl (IdP component action)
6   Input: RelayState = EncodeUrl(ReturnURL)
7→ Assign SSOUrl = GetLoginUrl.LoginUrl
8→ Navigate External: SSOUrl
9→ End

To automatically grant OutSystems Roles based on IdP group membership, configure group-to-role mapping in the IdP Portal. 1. In Azure AD, add a Group Claims attribute to your SAML app: Attributes & Claims → Add a group claim → select Security groups → set Source attribute to `sAMAccountName` or `Group ID`. 2. In the OutSystems IdP Portal → IdP Connectors → your connector → **Role Mapping** tab → Add mapping: - Attribute Name: `groups` (or the claim name Azure AD sends) - Attribute Value: the group GUID or sAMAccountName - OutSystems Role: `Manager` (select from dropdown) 3. Repeat for each group-role mapping. Now users in the Azure AD `Managers` group automatically receive the `Manager` OutSystems Role on login.

**Common errors and fixes:** **'Invalid SAML Response' or blank page after IdP redirect:** Use SAML-tracer to capture the response. Decode the SAMLResponse base64 field. Check that the Recipient URL in the response matches your ACS URL exactly (including trailing slash). **'User not found' after SAML authentication:** The username attribute in the assertion doesn't match any OutSystems user and auto-provisioning is disabled. Enable Auto-provision in the IdP Connector or create the user manually first. **'Signature validation failed':** The IdP's signing certificate has changed (common after certificate rotation). Re-download the IdP metadata and re-import it into the IdP Connector. **Clock skew errors:** SAML assertions include NotBefore/NotOnOrAfter timestamps. If the OutSystems server clock is more than 5 minutes out of sync with the IdP clock, assertions are rejected. Sync NTP on the OutSystems server.