Microsoft Entra

​

SAML configuration

To configure Microsoft Entra (formerly Azure AD) as the identity provider, follow these steps to create an Enterprise Application in your Azure console.

To add an enterprise application to your tenant:

1. Sign in to the Microsoft Entra admin center as at least a Cloud Application Administrator.
2. Browse to Identity > Applications > Enterprise applications > All applications.
3. Select New application.
4. Select Create your own application.
5. Enter a name e.g ‘Common Fate’
6. Select Integrate any other application you don’t find in the gallery (Non-gallery)
7. Click Create

You will now be on the application overview page.

1. Select Single sign-on

2. Select SAML

3. In Basic SAML Configuration set Identifier (Entity ID) to the first_time_setup_config.saml_sso_entity_id from the deployment outputs

4. In Basic SAML Configuration set Reply URL (Assertion Consumer Service URL) to the first_time_setup_config.saml_sso_acs_url from the deployment outputs

5. In Attributes & Claims set emailaddress to user.mail

6. Finally, copy the App Federation Metadata Url and save the configuration

7. Add the following variables to your Terraform deployment

   saml_provider_name    = "Entra"
   saml_metadata_is_file = false
   saml_metadata_source  = <App Federation Metadata Url**>**
   

8. Run a deployment

   terraform apply
   

​

SCIM user and group provisioning

1. To configure SCIM you will need to create a secret token for API authentication, use a strong token generator to generate a secret, then save it to SSM Parameter Store.

   You can use the AWS CLI to create a secret in the region you are deploying to, we recommend naming these "/<namespace>/<stage>/<secret name>"

   aws ssm put-parameter \
       --name "/common-fate/prod/scim-secret" \
       --value "mySecretValue" \
       --type "SecureString"
   

   Retrieve the ARN

   aws ssm get-parameter \
       --name "/common-fate/prod/scim-secret" --query Parameter.ARN
   

2. Add the following into your main.tf file

   scim_token_ps_arn     = <scim secret parameter store ARN>
   scim_source           = "Entra"
   

3. Run a deployment

   terraform apply
   

4. Sign in to the Microsoft Entra Admin Center as at least a Cloud Application Administrator.

5. Browse to Identity > Applications > Enterprise applications > Search for your application e.g Common Fate

6. Select Users and groups

7. Assign Groups to the application, You should assign all the Groups for which you would like to create Access Policies for with Common Fate

8. You can optionally assign individual users to the application as well

9. Select Provisioning

10. Select Manage > Provisioning

11. Set Provisioning Mode to Automatic

12. Under Admin Credentials set tenant URL to https://<your app URL>/api/v1/scim/Entra

13. Under Admin Credentials set Secret Token to your secret generated previously

14. Under Mappings go to the Provision Azure Active Directory Users settings and replace the mailNickname to externalId mapping: it must be objectId to externalId.

    

15. Click Test Connection you should get a success message

16. Navigate back to Provisioning > Overview

17. Select Start Provisioning

18. Optionally: Provision yourself on demand the login to the Common Fate web application.

At this point the Application is fully deployed and ready to be configured, users and groups will start to sync automatically, you can provision on demand at any time if need be.

​

Resetting

If you’ve misconfigured the Entra SCIM integration, you can reset the integration using Common Fate. This is useful in case you’ve missed step (14) above to set the objectId mapping up.

In order to reset the Entra SCIM integration, you’ll first need to give yourself permission to trigger the reset.

First, obtain your Common Fate user ID by running:

cf identity get

You should see an output similar to the below:

> cf identity get
Chris Norman <chris@commonfate.io> (CF::User::"usr_2ZFBBf4gOevAXQi9aAfK2tYUeFa")

Your user ID is shown in brackets at the end of the CLI output. It should look something like usr_2ZFBBf4gOevAXQi9aAfK2tYUeFa.

Then, add a Cedar policy which grants access to the CF::Control::Integration::Reset::ResetService::Action::"ResetEntraUsers" action:

permit(
  principal == CF::User::"<YOUR_USER_ID_HERE>", // replace with your user ID, e.g. CF::User::"usr_2ZFBBf4gOevAXQi9aAfK2tYUeFa"
  action ==
    CF::Control::Integration::Reset::ResetService::Action::"ResetEntraUsers",
  resource
);

Next, disable SCIM user provisioning in Entra ID for the Common Fate application.

Then, verify in Microsoft Entra that objectId is mapped to externalId:

'objectId' should be mapped to 'externalId'. You can follow the 'SCIM user and group provisioning' section above for more details.

Now, run a dry-run of the reset:

cf integration reset entra --dry-run=true

Common Fate will show you a preview of the entities which will be removed.

After you’ve confirmed the entities, proceed by running the reset:

cf integration reset entra --dry-run=false

Now, enable SCIM user provisioning again in Common Fate. You’ll need to wait up to 5 minutes for the initial SCIM sync to complete.

You may need to click the Restart button. Ensure that the your administrative page looks like the screenshot below to force a full sync.

After the SCIM process is complete, visit the Resources page inside of Common Fate and verify that Entra::User resources are present in your deployment. Your Entra user resources should have an ID which looks similar to the screenshot below.

Finally, revoke your permissions to reset SCIM by removing the Cedar policy you applied earlier for the CF::Control::Integration::Reset::ResetService::Action::"ResetEntraUsers" action.

// remove this policy from your Cedar policy sets.
-permit(
-  principal == CF::User::"<YOUR_USER_ID_HERE>", // replace with your user ID, e.g. CF::User::"usr_2ZFBBf4gOevAXQi9aAfK2tYUeFa"
-  action ==
-    CF::Control::Integration::Reset::ResetService::Action::"ResetEntraUsers",
-  resource
-);