Microsoft Entra ID

Add a custom subdomain

In the Azure portal, navigate to Default Directory > Custom domain names > Add custom domain and enter your subdomain (e.g., your-domain.example.com).

Follow the DNS verification steps if you haven't already verified this domain.

Promote the subdomain (subdomains only)

By default, a subdomain inherits federation settings from its parent domain. Promote it so it can carry its own federation configuration:

az rest \
  --method POST \
  --url "https://graph.microsoft.com/v1.0/domains/your-domain.example.com/promote"

Expected response:

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Edm.Boolean",
  "value": true
}

Create the federation configuration

Save the following as federation_config.json, replacing the placeholder values:

{
  "@odata.type": "microsoft.graph.internalDomainFederation",
  "issuerUri": "https://sandbox.hawcx.com/v1/saml/metadata?project_id=your-project-id",
  "passiveSignInUri": "https://sandbox.hawcx.com/v1/saml/sso?project_id=your-project-id",
  "metadataExchangeUri": "https://sandbox.hawcx.com/v1/saml/metadata?project_id=your-project-id",
  "signingCertificate": "your-signing-certificate",
  "preferredAuthenticationProtocol": "saml",
  "federatedIdpMfaBehavior": "acceptIfMfaDoneByFederatedIdp"
}

The federatedIdpMfaBehavior setting tells Entra to accept MFA performed by Hawcx rather than requiring a second MFA challenge.

Apply the federation configuration

Post the configuration to the Microsoft Graph API:

az rest \
  --method POST \
  --url "https://graph.microsoft.com/v1.0/domains/your-domain.example.com/federationConfiguration" \
  --body "@federation_config.json" \
  --headers "Content-Type=application/json"

Verify federation is active

Confirm the domain is now federated:

az rest \
  --method GET \
  --url "https://graph.microsoft.com/v1.0/domains/your-domain.example.com"

Look for this field in the response:

"authenticationType": "Federated"

If you see "Managed" instead, the federation configuration was not applied. Double-check the domain name and re-run the POST command.

Create the enterprise application

1. Go to entra.microsoft.com
2. Navigate to Applications > Enterprise applications
3. Click New application
4. Click Create your own application
5. Name it (e.g., "Hawcx SSO")
6. Select Integrate any other application you don't find in the gallery (Non-gallery)
7. Click Create

Assign users or groups

In the enterprise application, go to Users and groups and assign the users or groups that should authenticate through Hawcx.

You can assign individual users or a security group that contains your SSO users.

Configure SCIM provisioning

1. In the enterprise application, go to Provisioning
2. Click Get started
3. Under Admin Credentials, enter:

4. Click Test Connection. You should see: "The supplied credentials are authorized to enable provisioning"
5. Click Save

Configure attribute mappings

Navigate to Provisioning > Mappings > Provision Azure Active Directory Users and set up the following mappings:

Start provisioning

You have two options:

Automatic sync starts a background cycle that provisions all assigned users within 20 to 40 minutes. Go to Provisioning > Overview and click Start provisioning.

Provision on demand lets you provision specific users immediately. Go to Provisioning > Provision on demand, select the users, and click Provision. This is useful for initial testing before enabling the full sync.