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

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.

32KB

SSO Integration Form Template SAML V6 DLSEC SENSITIVE WHEN COMPLETED.xlsx

Open

Suggested Steps

Use the following approach to configure Azure for Crisisworks.

Initial set-up in Azure

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

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

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

• Microsoft: Configure SAML-based SSO for enterprise applications

• AWS / Cognito: SAML user pool IdP authentication flow