Configuring Azure / Entra ID for SSO

Overview

Crisisworks uses OAuth2 and OIDC to achieve a Single Sign-On (SSO) for users matching your authorised domains.

Key concepts

At a high level, SSO works like this — when your users signs into Crisisworks, our OAuth2 service redirects the user to your Azure auth service, and then it converts the Azure authentication result into a Crisisworks user by mapping against a user's email address.

• Azure provides Authentication ("AuthN")

• Crisisworks manages Authorisation ("AuthZ") — via positions and events

• Crisisworks is multi-tenant and your SSO integration will cover only your internal users.

• Your Crisisworks site will need to support external users, who will use their own SSO integration (if configured), or Crisisworks' internal username/password and MFA.

For more non-technical overview, please read the SSO Integration Overview article.

Open ID Connect (OIDC)

Crisisworks is built using an open standard known as "OAuth2", and uses OIDC to integrate to Azure.

1. Your Azure service acts as an identity provider ("IdP") — that means when someone logs in, they’ll be redirected to Azure to authenticate using your corporate credentials.

2. Crisisworks acts as a “relying party” / “service provider” — after successful login, Azure issues a token (ID token / access token) containing user attributes. Crisisworks' OAuth2 service then maps those attributes to our internal user directory, issues its own tokens, and grants access to our systems.

The following diagram shows the technical OAuth2/OIDC handshake.

Configuring Azure (Entra ID)

The following guides Azure admins to set up the integration and provide the appropriate information to Datalink.

Prerequisites

Your OIDC service should have the following configuration.

• Supports client_secret_post client authentication.

• Only uses HTTPS for OIDC endpoints such as openid_configuration, userInfo, and jwks_uri.

• Only uses TCP ports 80 and 443 for OIDC endpoints.

• Only signs ID tokens with HMAC-SHA, ECDSA, or RSA algorithms.

• Publishes a key ID kid claim at its jwks_uri and includes a kid claim in its tokens.

• Presents a non-expired public key with a valid root CA trust chain.

This configuration is common for Microsoft Azure Entra ID environments.

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 OIDC	—
Provider name	A friendly name for your IdP (e.g. “Azure-Corp”)	You choose this — used for internal documentation / mapping
Issuer URL	OIDC issuer (used for discovery & token validation)	Typically https://login.microsoftonline.com/{tenant}/v2.0 or your custom domain.
Client ID	The Application (client) ID from Azure	After you register the Azure app in Entra ID
Client secret	The client credential (secret) Azure issues	In App registrations → Certificates & secrets
Authorized scopes	The OIDC scopes your application requests (we require openid, email, profile)	In the app registration’s “Expose an API” or “API permissions” settings; or in your request to Azure.
Identifiers (domains)	The email domains for which your Azure instance is authoritative	You provide these; Azure doesn’t “enforce” routing for domains but this is for Crisisworks to know how to route
Attribute mappings (given_name, family_name, email, username and others)	Map claims from Azure to our internal user attributes	Use Azure app “Token configuration” or “Manifest” to add optional claims if needed
Optional: Secret expiry, rotation plan	If your secret expires, we need lead time to rotate	You decide expiry (e.g. 1 year, 2 years) and share process

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 so care should be taken to transmit for form to Datalink and store the form in your records.

23KB

SSO Integration Form Template V3 DLSEC SENSITIVE.xlsx

Open

Suggested Steps

Use the following approach to configure Azure for Crisisworks.

Initial set-up in Azure

Check your Azure manual for exact steps

1. Register an application in Azure / Entra ID

   • Go to Azure Portal → Entra ID → App registrations → New registration

   • Choose a name,

   • Select single-tenant

   • Set "SPA" (Single Page Application) as the app type

   • Set the Redirect URI to https://auth.cw.crisisworks.com/oauth2/idpresponse

   • Set the Front-channel logout URL to https://app.cw.crisisworks.com/user/signout

2. Generate a client secret (or certificate)

   • Go to Certificates & secrets → New client secret (set expiry)

   • Copy the value (one-time view) — this is your Client Secret

3. Configure API permissions / scopes

   • Add delegated permissions: openid, email, profile

4. Add optional claims / token configuration

   • Select both ID token and Access token to allow the implicit flow

   • Required attributes: email , given_name, family_name

   • Optional attributes: verified_primary_email (email verification flag) and xms_edov (domain verification flag)

5. Provide the configured values to Crisisworks

   • Issuer URL, Client ID, Client Secret, scopes, and the list of domains and attribute mappings via the Crisisworks Configuration Form

Initial set-up in Crisisworks

Datalink configure your identity provider in Crisisworks

• We set up your OIDC provider in Cognito using those values

• We map your domains and configure routing

Testing and validation

• You (or a pilot user) attempt login for users in your domain

• On success, a user’s browser should redirect to Azure, login, then return to Crisisworks

• We verify that correct user attributes (first name, last name, email, username) flowed through

• We test negative cases (domain not in your list, expired secret, token signature errors)

• Next we test signing into the mobile apps — iOS and Android.

Go-live / rollout

• Once tests are successful, we enable SSO for full user base

• Monitor logs / errors in the first days

Rotation and Troubleshooting

If the Client ID or secret require periodic rotation, this will be calendarised and Datalink will contact the nominated technical contact 30 days ahead of expiry.

From a tech support perspective, Datalink will no longer be able to troubleshoot failed login attempts for SSO users nor guide them to password resets, so a shared support approach will be organised and Datalink will refer the user to the support contact if the issue is related to signing into Azure.

Testing / Verification Checklist

SSO Testing 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, prompt, and return to Crisisworks
	Confirm user attributes (first name, last name, email) appear correctly
	Attempt the same SSO login via the Crisisworks 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, and should work if supported as a fallback)
	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: OpenID Connect (OIDC) on the Microsoft identity platform

• Microsoft: Configure OIDC SSO for custom applications in Entra ID

• Microsoft: Quickstart for registering an app in Entra ID

• AWS / Cognito: OIDC user pool IdP authentication flow

• Community: integration of Azure Entra ID with Cognito guides