SCIM Lambda Jobs for GitHub & Entra ID

Introduction

This runbook covers the technical processes for SCIM Lambda maintenance, secrets management, and operational best practices on the MoJ Master (root) AWS account, underpinning the SSO integration.

How it works:

Entra ID: Synchronisation is handled by an AWS Lambda function written in Python. This Lambda authenticates to Microsoft Entra ID using secure credentials (tenant ID, client ID, client secret) to fetch group and user information, and then updates AWS Identity Center to match the state in Entra ID.
GitHub: Synchronisation is managed by an AWS Lambda function written in JavaScript. This Lambda fetches all GitHub organisation teams and members using the GitHub API, and retrieves users and groups from AWS IAM Identity Center via the AWS Identity Store API. It compares both data sets and determines which users, groups, or memberships need to be created or deleted in AWS to match GitHub. The Lambda then applies these changes in AWS.

If you’re looking for user-facing SSO guidance, check out the Modernisation Platform Single Sign-On User Guide.

1. Identifying Relevant Lambda Functions & Dependencies

1.1 Lambda Functions Overview

Function Name	Source Module	Purpose	Trigger Schedule	Secret Name In Secrets Manager
aws-sso-scim-github	moj-terraform-scim-github	SCIM provisioning for GitHub	Every 6 hours (cron)	aws_saml
entra-id-scim-lambda	moj-terraform-scim-entra-id	SCIM provisioning for Entra ID	Every 2 hours (rate)	entra_id_aws_connectivity_details

EntraID App Registrations: Two EntraID App Registrations are in use:

justicedigital-panda-awsidentitycenter-scim: which stores client secret aws-entraid-identity-center-scim used for the EntraID SCIM Lambda job.
justicedigital-panda-awsidentitycenter: which stores client secret aws-sso-entraid-integration (used by Auth0 to authenticate to Entra ID) Auth0 tenant enables Single Sign-On for AWS by federating user identities from Entra ID through Auth0 and ultimately into AWS Identity Center. The secret azure_entraid_oidc in AWS Secrets Manager stores credentials for the Ministry of Justice–owned OAuth app used for AWS SSO.

SCIM jobs are defined in:

Instantiated via: aws-root-account/management-account/terraform/sso-scim.tf

1.2 Key Dependencies

AWS Services: Lambda, CloudWatch/EventBridge, IAM, Secrets Manager, KMS
Terraform Modules: moj-terraform-scim-github, moj-terraform-scim-entra-id
Secrets: GitHub tokens, Azure secrets, client IDs and other provider credentials (all managed via AWS Secrets Manager)
IAM Roles: Permissions for Lambdas to fetch/rotate secrets and perform SCIM operations

2. Secrets Management

2.1 How Secrets Are Consumed

Sensitive credentials (GitHub tokens, Azure client secrets, etc.) required for SCIM integrations are stored in AWS Secrets Manager.
These secrets are referenced in sso-scim.tf as sensitive local variables, and injected into the respective Terraform modules (moj-terraform-scim-github, moj-terraform-scim-entra-id).
Within the modules, secrets are passed as environment variables to Lambda.

Example (in sso-scim.tf):

module "scim" {
  source                = "github.com/ministryofjustice/moj-terraform-scim-github"
  github_token          = sensitive(local.sso.aws_saml.github_token)
  ...
}
module "entraid_scim" {
  source                = "github.com/ministryofjustice/moj-terraform-scim-entra-id"
  azure_client_secret   = sensitive(local.azure.client_secret)
  ...
}

2.2 Rotation

When an Entra ID secret requires renewal, an email notification is sent from IDAM (IDAM@justice.gov.uk) to the relevant application owners. The GitHub SCIM token is controlled by the MP Bot Account.

For full rotation procedures, including manual steps and validating successful rotation, refer to the Rotating Secrets Runbook.

3. Operational Best Practices

Monitor Lambda execution via CloudWatch Logs and set up alerts for failures.
Review secret rotation schedules and ensure secrets are rotated before expiry.
Restrict IAM permissions for Lambda functions to only what is necessary for SCIM operations and secret access.

4. Troubleshooting

Lambda failures: Check CloudWatch Logs for error messages. Common issues include expired secrets or insufficient IAM permissions.
SCIM sync issues: Ensure the correct secret values are present in AWS Secrets Manager and that the Lambda environment variables are up to date.
Secret rotation problems: After updating a secret, always run the management-account-apply.yml workflow to propagate changes.
Azure AD/Entra ID issues: If users or groups are not syncing, verify the app registration, secret validity, and permissions in Azure Portal.
GitHub sync issues: Check that the GitHub token has not expired or been revoked, and that the correct permissions are granted.

5. Manual Execution

Although these processes are automated to run on a schedule, you may sometimes need to run them manually. It is safe to run the Lambda functions manually via the AWS Console.

Steps:

SSO into the MOJ Master account as a ModernisationPlatformEngineer.
Navigate to the “Lambda” service.
Ensure your region is set to eu-west-2 (London).
Navigate to “Functions” in the sidebar.
Select the relevant function (e.g., aws-sso-scim-github or entra-id-scim-lambda).
Select the Test tab.
Select Edit saved event.
Event name should already be set as RunJobManually.
Press the Test button to trigger the SCIM job.
After a couple of minutes, the job should complete and display the logs of the run. Use the logs to confirm which users have been added or updated.

To validate check AWS Identity Centre (or the relevant target system) to ensure the expected users have gained the expected access to AWS Accounts and Applications.

This page was last reviewed on 12 November 2025. It needs to be reviewed again on 12 May 2026 by the page owner #modernisation-platform .