# Configuring Azure / Entra ID for SSO (SAML) ## Overview Crisisworks supports SAML 2.0 as an SSO protocol for organisations using Azure / Entra ID. SAML is recommended over OIDC for Azure integrations as it avoids known compatibility issues with Azure's cross-origin code redemption enforcement (PKCE), and it avoids manual secret renewals by using its metadata URL. ### Key concepts The SAML flow works as follows — when your user signs into Crisisworks, they are redirected to Azure for authentication. Azure then posts a signed SAML assertion back to Crisisworks, which maps the assertion attributes to the internal user account by email address. * Azure provides Authentication ("AuthN") as the Identity Provider (IdP) * Crisisworks manages Authorisation ("AuthZ") — via positions and events * Crisisworks is multi-tenant; your SSO integration covers only your internal users * External users will use their own SSO integration, or Crisisworks' internal username/password and MFA For a non-technical overview, please read the [SSO Integration Overview](/security-and-support/technical-reference/integrations/sso-integration.md) article. ### SAML 2.0 Crisisworks uses AWS Cognito as its SSO broker. Cognito acts as the SAML Service Provider (SP) and Azure acts as the Identity Provider (IdP). ```mermaid sequenceDiagram participant U as User (Browser) participant CW as Crisisworks Frontend / App participant C as Crisisworks (Cognito SP) participant A as Azure IdP (Entra ID) U->>CW: Access protected UI / "Sign in" CW->>C: Redirect to Cognito /authorize (with configured IdP = Azure SAML) C->>A: Redirect to Azure SSO endpoint (SAMLRequest, RelayState) A->>U: Azure login UI (or existing SSO session) U->>A: User authenticates A->>U: HTTP POST with signed SAMLResponse to ACS URL U->>C: Browser posts SAMLResponse to Cognito ACS URL C->>C: Validate signature, map attributes to Cognito user C->>CW: Redirect user to app with JWT tokens (Cognito-issued) U->>CW: Carry token in subsequent requests ``` ## Configuring Azure (Entra ID) The following guides Azure admins through the SAML setup and provides the information needed by Datalink. ### Key information Below is a mapping of the required fields in our SSO Integration Form and guidance on how to obtain them. | Form Field | Description / Why Needed | Where to Configure or Obtain in Azure | | --------------------- | ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | | Provider type | Indicate you're using SAML | — | | Provider name | A friendly name for your IdP (e.g. "Azure-SAML-Corp") | You choose this — used for internal documentation / mapping | | IdP Metadata URL | Cognito uses this URL to fetch and automatically refresh Azure's SAML endpoints and signing certificate | Available in the Enterprise App → Single sign-on screen → SAML Signing Certificate → **App Federation Metadata URL** | | Identifiers (domains) | Email domains for which Azure is authoritative | You provide these | | Attribute mappings | Maps SAML assertion attributes to Crisisworks user fields | Configured in Azure Attributes & Claims | ### SSO Configuration Form {% hint style="warning" %} **Tip:** Use the Crisisworks SSO Integration Form to capture all the details in one place. When complete, this form will contain sensitive information — take care to transmit the form to Datalink securely and store it appropriately in your records. {% endhint %} {% file src="/files/Zb8akUxQLZgzQvCrHojc" %} ## Suggested Steps Use the following approach to configure Azure for Crisisworks. ### Initial set-up in Azure {% hint style="info" %} The following steps are a guide. Exact navigation may vary by Azure portal version. {% endhint %} {% hint style="info" %} **Note:** Enterprise deployments have different URLs than below — the general form is `auth.*` and `app.*`, where `*` is the base domain for your app. {% endhint %} 1. Create an Enterprise Application in Entra ID * Go to *Azure Portal → Entra ID → Enterprise applications → New application* * Select **"Create your own application"** * Choose a name (e.g. `Crisisworks SAML`) * Select **"Integrate any other application you don't find in the gallery"** * Click **Create** 2. Configure SAML single sign-on * Open the new app → left sidebar → **Single sign-on** → select **SAML** * Under **Basic SAML Configuration** → **Edit**, set: * **Identifier (Entity ID):** `urn:amazon:cognito:sp:ap-southeast-2_ZQAGo8QUO` * **Reply URL (ACS URL):** `https://auth.cw.crisisworks.com/saml2/idpresponse` * **Sign on URL:** leave blank * **Logout URL:** `https://app.cw.crisisworks.com/user/signout` * Save 3. Configure attribute claims * Still on Single sign-on → **Attributes & Claims** → **Edit** * Confirm or add the following claims: | Claim name | Source attribute | | -------------------------------------------------------------------- | ---------------- | | `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress` | `user.mail` | | `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname` | `user.givenname` | | `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname` | `user.surname` |

If user.mail is not populated in your directory, use user.userprincipalname for the email claim.

4. Copy the App Federation Metadata URL * Still on Single sign-on → under **SAML Signing Certificate** * Copy the **"App Federation Metadata URL"** * This URL is what you provide to Datalink — Cognito will fetch and automatically refresh the metadata from it, including picking up new signing certificates when they are rotated

Use the metadata URL rather than downloading and uploading the XML file. When configured with a URL, Cognito automatically re-fetches the metadata as Azure rotates its signing certificate, eliminating the need for manual certificate updates.

5. Assign users or groups * Left sidebar → **Users and groups** → **Add user/group** * Assign the Azure AD groups or users who should have access to Crisisworks 6. Provide the configured values to Crisisworks * Supply the App Federation Metadata URL, your Entity ID, and the list of authorised email domains via the [Crisisworks Configuration Form](#sso-configuration-form) ### Initial set-up in Crisisworks Datalink configure your identity provider in Crisisworks: * We create a SAML IdP in Cognito using your App Federation Metadata URL * We configure attribute mappings from SAML claims to Crisisworks user fields * We map your domains and configure routing ### Testing and validation * You (or a pilot user) attempt login for users in your domain * On success, the browser should redirect to Azure, authenticate, then return to Crisisworks * We verify that correct user attributes (first name, last name, email) flowed through * We test negative cases (domain not in your list, expired certificate, malformed assertion) * Next we test signing into the mobile apps — iOS and Android ### Go-live / rollout * Once tests are successful, we enable SSO for the full user base * Monitor logs / errors in the first days ### Certificate rotation SAML signing certificates issued by Azure expire (default is 3 years). Because Crisisworks configures the IdP using the **App Federation Metadata URL**, Cognito automatically re-fetches the metadata periodically and picks up new certificates as Azure publishes them — no manual intervention is required. This is a key operational advantage over OIDC, where client secrets must be manually rotated. ## Testing / Verification Checklist
✅Step
Testing success
Use a test user with an email in your domain
Attempt login via Crisisworks SSO "Login with Azure" using the Crisisworks web app
Confirm the redirect to Azure, authentication prompt, and return to Crisisworks
Confirm user attributes (first name, last name, email) appear correctly
Attempt the same SSO login via the Crisisworks mobile app
Error & edge-case testing
Try login from an email outside your domain (should fall back to default login or error)
Try logging in with username and password from Crisisworks (should fail if SSO-only)
Go-live cut-over
Switch your user population from legacy login to SSO
Monitor first 24–48 hours for anomalous login failure spikes
## Further References & Resources * [Microsoft: *SAML authentication with Entra ID*](https://learn.microsoft.com/en-us/entra/architecture/auth-saml) * [Microsoft: *Configure SAML-based SSO for enterprise applications*](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/configure-saml-single-sign-on) * [AWS / Cognito: *SAML user pool IdP authentication flow*](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-saml-idp-authentication.html) --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.cw.crisisworks.com/security-and-support/technical-reference/integrations/sso-integration/configuring-azure-entra-id-for-saml-sso.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.