Skip to main content
Version: current

MS Entra Integration

This directory contains scripts for integrating with Microsoft Entra ID (formerly Azure Active Directory), including domain federation setup.

Domain Federation Setup​

The create-domain-federation.ps1 script automates the process of:

  1. Creating a custom domain in Microsoft Entra ID
  2. Verifying domain ownership via DNS records
  3. Setting up SAML federation for the domain

Prerequisites​

  • PowerShell Core (pwsh) 7.0 or higher
  • Microsoft Graph PowerShell module installed
  • Appropriate permissions in Microsoft Entra ID

To install the required PowerShell module:

Install-Module Microsoft.Graph -Scope CurrentUser

Configuration​

Before running the script, you need to create a configuration file for your environment:

  1. Create a configuration file named config.<environment>.ps1 in the env directory:

    touch backend/identity/iam/ms-entra/env/config.<environment>.ps1

  2. Add the following content to your configuration file, replacing the values with your own:

    # Microsoft Entra ID tenant ID
    $TenantId = "your-tenant-id"

    # Domain to create and federate
    $DomainName = "yourdomain.com"

    # Base64-encoded X.509 certificate for SAML signing
    $SigningCertificate = "MIIDXTCCAkWgAwIBAgI..."

Notes:

Running the Script​

To run the script:

# Run the script with your environment configuration
./create-domain-federation.ps1 -Environment <environment>

The script will:

  1. Connect to Microsoft Graph API
  2. Check if the domain exists
  3. Create the domain if it doesn't exist
  4. Verify domain ownership (requires DNS record creation)
  5. Set up or update federation configuration
  6. Configure sign-in auto-acceleration for applications

Auto-Acceleration​

The script automatically configures sign-in auto-acceleration, which allows users to skip the Microsoft Entra sign-in page and go directly to your federated identity provider's sign-in page. This improves the user experience for federated authentication.

By default, the script will:

  • Create a Home Realm Discovery policy for auto-acceleration
  • Apply it to applications tagged with "VouchFederated"
  • If no tagged applications are found, apply it to common Microsoft 365 applications

To tag an application for auto-acceleration:

# Get the service principal ID of your application
$appId = "your-application-id"
# Add the VouchFederated tag
Update-MgServicePrincipal -ServicePrincipalId $appId -Tags @("VouchFederated")

Domain Verification​

When the script prompts for domain verification:

  1. Create the TXT DNS record shown in the output
  2. Wait for DNS propagation
  3. Confirm when the record is created
  4. The script will attempt to verify the domain

Troubleshooting​

Incorrect issuer / sign uri​

If your environment configuration has an incorrect setup, i.e. the issuer / sign uri aren't matching the domain, you might encounter the following (totally irrelevant) error:

New-MgDomainFederationConfiguration_CreateExpanded: /home/stijn/Documents/code/vouch/vouch/backend/identity/iam/ms-entra/create-domain-federation.ps1:123
Line |
 123 |          New-MgDomainFederationConfiguration `
     |          ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     | Domain already has Federation Configuration set.  Status: 400 (BadRequest) ErrorCode: Request_BadRequest Date: 2025-04-01T09:52:50  Headers: Cache-Control                 : no-cache Vary                          : Accept-Encoding
     | Strict-Transport-Security     : max-age=31536000 request-id                    : 32856efe-22b0-4540-9de4-c33d7e3e8377 client-request-id             : b282bd9c-516a-4692-a59c-5afb87b85863 x-ms-ags-diagnostic           : {"ServerInfo":{"DataCenter":"West
     | Europe","Slice":"E","Ring":"5","ScaleUnit":"001","RoleInstance":"AM4PEPF00033F3A"}} x-ms-resource-unit            : 1 Date                          : Tue, 01 Apr 2025 09:52:49 GM

In order to fix this problem, you have to:

  1. Update your configuration to align the domain and issuer / sign uri
  2. Remove the existing domain from MS Entra: a. You can do this either in the MS Entra Admin console: https://entra.microsoft.com/#view/Microsoft_AAD_IAM/DomainsManagementMenuBlade/~/CustomDomainNames b. Or with PowerShell: Remove-MgDomain -Id <your-domain>
  3. Re-run the script (and perform domain verification again)

Authentication Issues​

If you encounter authentication issues:

  1. Ensure you have the correct permissions in Microsoft Entra ID
  2. Try running Connect-MgGraph manually to troubleshoot authentication
  3. Check that your tenant ID is correct in the configuration file