Single sign-on with Entra ID and SCIM provisioning

RestWard supports Microsoft Entra ID (formerly Azure Active Directory) as its single sign-on provider. This guide shows you how to enable SSO for your organization, verify your domain, configure SCIM-based automatic provisioning from Entra ID, and use passkeys for password-free sign-in.

Entra ID is the only SSO provider supported today.

Prerequisites

• Administrator role in your RestWard organization
• A verified domain in RestWard — domain verification anchors SSO and SCIM to legitimate users from your company
• Access to Microsoft Entra ID — you need permissions to create an app registration in your Azure tenant

Part 1: Verify your domain

Before you can enable SSO or SCIM, you must prove you control your company's domain. RestWard requires a DNS TXT record for verification.

Step 1: Add your domain in RestWard

1. In RestWard, go to Verified Domains
2. Click Add Domain
3. Enter your domain (e.g., acme.com)
4. Click Add Domain

The domain appears with Pending verification status.

Step 2: Create the DNS TXT record

1. On the Verified Domains page, find your domain and click Show DNS record

2. You'll see three values:

   • Host: _restward-verify.acme.com
   • Type: TXT
   • Value: restward-verify=abc123...

3. Copy these values and create a matching TXT record at your DNS provider

4. Wait a few minutes for DNS propagation

Step 3: Complete verification

1. Back on the Verified Domains page, click Verify next to your domain
2. RestWard checks for the TXT record and confirms it matches
3. Your domain status changes to Verified (green checkmark)

Troubleshooting: If verification fails, double-check the Host and Value match exactly. DNS changes can take several minutes to propagate.

Part 2: Enable Entra ID SSO

Once your domain is verified, configure SSO so your team members can sign in with their Microsoft credentials.

Step 1: Get the RestWard redirect URI

1. Go to Single Sign-On in RestWard
2. Under Entra ID app registration, you'll see a Redirect URI in a code block
3. Copy this URI — you'll need it for the next step

The redirect URI format is: https://{your-restward-instance}/account/sso-callback

Step 2: Create an app registration in Entra ID

1. Sign in to the Azure portal
2. Go to Microsoft Entra ID > App registrations > New registration
3. Enter a name like "RestWard"
4. Select Single tenant (your organization only)
5. Under Redirect URI, select Web and paste the URI you copied from RestWard
6. Click Register

Step 3: Configure API permissions

1. In your new app registration, go to API permissions
2. Click Add a permission > Microsoft Graph
3. Select Delegated permissions
4. Add these permissions:
   • openid
   • profile
   • email
5. Click Grant admin consent for your organization

Step 4: Create a client secret

1. Go to Certificates & secrets
2. Click New client secret
3. Enter a description (e.g., "RestWard SSO")
4. Select an expiration period (recommended: 6-12 months)
5. Click Add
6. Copy the secret value immediately — you won't see it again after leaving this page

Step 5: Configure SSO in RestWard

1. Back in RestWard on the Single Sign-On page:

   • Tenant ID: From Entra ID > Overview (Directory (tenant) ID)
   • Client ID: From App registrations > Overview (Application (client) ID)
   • Client secret: The value you copied above
   • Enabled: Check to turn on SSO

2. Optional settings:

   • Automatically provision new users on first sign-in (JIT): If enabled (default), members signing in for the first time are automatically added to your organization
   • Default role: The role assigned to auto-provisioned members (defaults to Reader)
   • Activate provisioned members immediately: If enabled (default), auto-provisioned members can sign in right away; if disabled, they wait for admin approval
   • Require single sign-on for this organization: If enabled, members must sign in via SSO (admins retain a break-glass email/password path)

3. Click Save

Security note: The Client secret field clears after saving for security. If you lose it, create a new secret in Entra ID.

Step 6: Test SSO sign-in

1. Sign out of RestWard
2. On the login page, enter your work email
3. Click Use single sign-on (or Sign in with Microsoft ())
4. You'll be redirected to Microsoft for authentication
5. After successful authentication, you're signed in to RestWard

Part 3: Configure SCIM provisioning from Entra ID

SCIM (System for Cross-domain Identity Management) automates member lifecycle management. Your identity provider can create, update, and deactivate members directly in RestWard.

Step 1: Generate a SCIM provisioning token

1. Go to the Provisioning (SCIM) page in RestWard
2. Under Provisioning Tokens, click Generate token
3. Enter a description (e.g., "Entra ID provisioning")
4. Optionally set an expiration date
5. Click Generate

Important: RestWard displays the token once. Copy it immediately — you won't see it again.

6. After generating the token, the Tenant URL (SCIM base URL) appears. Copy this as well.

The SCIM base URL format is: https://{your-restward-instance}/scim/v2

Step 2: Configure SCIM in Entra ID

1. In the Azure portal, go to your RestWard app registration
2. Select Provisioning in the left menu
3. Click Get started
4. Select Automatic for provisioning mode
5. For Tenant URL, paste the SCIM base URL you copied from RestWard
6. For Secret Token, paste the provisioning token you copied
7. Click Test Connection to verify Entra ID can authenticate with RestWard
8. Click Save

Step 3: Configure attribute mappings

1. In Entra ID provisioning, go to Mappings

2. Select Provision Microsoft Entra ID Users

3. Review the default mappings. RestWard supports these SCIM attributes:

   • userName (email address)
   • externalId (unique identifier from your IdP)
   • name.givenName (first name)
   • name.familyName (last name)
   • displayName (full display name)
   • emails (email addresses)
   • active (whether the user is active)
   • groups (group memberships)

4. Ensure these mappings are configured:

   • userPrincipalName → userName
   • givenName → name.givenName
   • surname → name.familyName
   • displayName → displayName
   • mail or userPrincipalName → emails[primary=true].value with type work
   • accountEnabled → active

5. For group provisioning (optional):

   • Enable Provision Microsoft Entra ID Groups
   • Map group attributes appropriately

Step 4: Configure group role mappings (optional)

If you provision groups from Entra ID, you can automatically assign RestWard roles to group members:

1. In RestWard on the Provisioning (SCIM) page, wait for groups to appear in the Group role mappings table
2. For each group, select a role from the Role dropdown:
   • Administrator
   • Contributor
   • Auditor
   • Reader
3. The role assignment takes effect immediately for all members in that group

Step 5: Enable provisioning

1. In Entra ID, set the provisioning Status to On
2. Click Save
3. Provisioning will start automatically and sync users from Entra ID to RestWard

Part 4: Sign in with passkeys

Passkeys provide a secure, password-free way to sign in to RestWard using your device's biometric authentication (fingerprint, face recognition) or PIN.

Adding a passkey

1. Sign in to RestWard
2. Go to Security in the sidebar
3. Click Add a passkey
4. Your browser will request permission to create a passkey
5. Confirm the request
6. Use your device's biometric scanner or PIN to complete authentication
7. Enter a descriptive name (e.g., "MacBook Touch ID" or "iPhone Face ID")
8. Click Save Passkey

Your passkey is now ready to use.

Managing passkeys

On the Security page, you can:

• View all your passkeys with their names, creation dates, and last used timestamps
• Rename a passkey by clicking the pencil icon
• Remove a passkey by clicking the trash icon

Warning: If you remove your only passkey, you'll need to sign in with email and password until you add a new one.

Signing in with a passkey

1. On the RestWard login page, click Sign in with a passkey
2. Select the passkey you want to use
3. Authenticate with your device's biometric or PIN
4. You're signed in

Cloud sync: Passkeys marked as Synced are backed up to your device's cloud account (iCloud for Apple, Google Account for Android). These can be used on new devices when you sign in with the same cloud account.

How deprovisioning works

When you deprovision a user in Entra ID, RestWard handles it based on the SCIM operation:

Deactivating a user (soft delete)

When Entra ID sends a SCIM update with active: false:

• The member's status is set to Suspended in RestWard
• The member cannot sign in to RestWard
• Their membership record is preserved (not deleted)
• Their API keys remain valid (not automatically revoked)
• Any active sessions are invalidated through membership stamp tracking

To reactivate: Mark the user as active in Entra ID. The change syncs automatically on the next provisioning cycle.

Deleting a user (hard delete)

When Entra ID sends a SCIM DELETE request:

• The membership is removed from your RestWard organization
• The member cannot sign in to RestWard
• Their API keys are NOT automatically revoked (they remain valid until their natural expiration or manual revocation)
• Any active sessions are invalidated through membership stamp tracking

Important: API keys are organization-scoped credentials. When a membership is deleted, the API keys created under that membership context are NOT automatically revoked. Admins should manually revoke API keys for deprovisioned users if needed.

Last administrator protection

SCIM provisioning respects your organization's requirement to maintain at least one active administrator:

• If a deactivation or deletion request would leave your organization with no active administrators, the request is blocked
• You must promote another administrator first before deactivating the last one

CLI equivalents

Domain verification

# List domains for an organization
restward domain list --org-id <organization-id>

# Add a domain
restward domain add --org-id <organization-id> --domain acme.com

# Get verification instructions (shows TXT record details)
restward domain verify-instructions --org-id <organization-id> --domain-id <domain-id>

# Verify a domain
restward domain verify --org-id <organization-id> --domain-id <domain-id>

SSO configuration

# Get SSO configuration (includes redirect URI)
restward sso get --org-id <organization-id>

# Enable SSO
restward sso enable --org-id <organization-id> \
  --provider EntraId \
  --client-id <client-id> \
  --tenant-id <tenant-id> \
  --client-secret <client-secret>

# Disable SSO
restward sso disable --org-id <organization-id>

SCIM provisioning

# List SCIM tokens
restward scim token list --org-id <organization-id>

# Create a SCIM token
restward scim token create --org-id <organization-id> \
  --description "Entra ID provisioning"

# Revoke a SCIM token
restward scim token revoke --org-id <organization-id> --token-id <token-id>

# List SCIM group mappings
restward scim group-mapping list --org-id <organization-id>

# Set group role mapping
restward scim group-mapping set-role --org-id <organization-id> \
  --mapping-id <mapping-id> --role Administrator

Troubleshooting

SSO issues

Members get an error when signing in via SSO

• Verify the Redirect URI in your Entra ID app registration exactly matches the URI shown in RestWard (including trailing slashes)
• Ensure the app registration has the required permissions (openid, profile, email) with admin consent granted
• Check that the Client secret hasn't expired

I forgot to copy the Client secret

• In Entra ID, go back to Certificates & secrets and create a new client secret
• Update RestWard with the new secret
• Delete the old secret in Entra ID

JIT provisioning isn't working

• Verify Automatically provision new users on first sign-in (JIT) is enabled
• Ensure your verified domain is set up correctly
• Confirm the member's email domain matches your verified domain

SCIM issues

The tenant URL isn't showing

• You must generate a provisioning token first. The URL is hidden until a token exists for security.

Entra ID can't authenticate

• Verify you used the correct Tenant URL (copy-paste directly from RestWard)
• Verify you used the correct Secret Token (ensure it wasn't truncated when copying)
• Test the connection in Entra ID's provisioning settings

Groups aren't appearing in the mapping table

• Group mappings are populated dynamically as your identity provider provisions groups
• This happens after provisioning is enabled and the first group is created
• Wait a few minutes for the initial sync to complete

My last administrator is being deactivated

• SCIM blocks any attempt to deactivate your organization's last active administrator
• Promote another administrator in RestWard first, then deactivate the user in Entra ID

Passkey issues

"Add a passkey" button is grayed out or missing

• Your browser or device might not support passkeys
• Try using a different browser or device
• You can still use email and password to sign in

Passkey creation failed

• Ensure your device is unlocked
• Don't interrupt the biometric or PIN prompt
• Try creating the passkey again
• If the problem persists, use email and password to sign in and try again later

I can't see my recently created passkey

• Reload the Security page to see the latest passkeys

See also

• Verified domains — In-app help for domain verification
• Single sign-on — In-app help for SSO configuration
• SCIM provisioning — In-app help for SCIM setup
• Passkeys & account security — In-app help for passkey management
• RBAC & multi-tenancy — Understanding roles and organization scoping