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 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).

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

circle-exclamation

Suggested Steps

Use the following approach to configure Azure for Crisisworks.

Initial set-up in Azure

circle-info

The following steps are a guide. Exact navigation may vary by Azure portal version.

circle-info

Note: Enterprise deployments have different URLs than below — the general form is auth.* and app.*, where * is the base domain for your app.

  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 ConfigurationEdit, 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 & ClaimsEdit

    • 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

    circle-info

    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

    circle-info

    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 groupsAdd user/group

    • Assign the Azure AD groups or users who should have access to Crisisworks

  6. Provide the configured values to Crisisworks

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

Last updated

Was this helpful?