moj-terraform-scim-github

This Terraform module configures a Lambda function for provisioning (and deprovisioning) AWS SSO Identity Store users and groups from GitHub.

The Lambda function used to use the SCIM endpoints (hence its name, moj-terraform-scim-github), but now uses the direct Identity Store API. The SCIM API has limitations such as not being able to list more than 50 groups or members (and doesn't support startIndex, so you can't paginate them), whereas the Identity Store API does allow pagination. This allows us to deprovision users and groups using the Identity Store API, which you cannot do easily with the SCIM API.

Usage

module "scim" {
  source                = "github.com/ministryofjustice/moj-terraform-scim-github"
  github_organisation   = "ministryofjustice"
  github_token          = "${var.github_token}"
  sso_aws_region        = "eu-west-2"
  sso_email_suffix      = "@example.com"
  sso_identity_store_id = "${var.sso_tenant_id}"
  not_dry_run           = true
}

Requirements

Name	Version
terraform	>= 1.0
archive	>= 2.4.0
aws	>= 5.0.0
external	>= 2.3.0

Providers

Name	Version
archive	>= 2.4.0
aws	>= 5.0.0
external	>= 2.3.0

Modules

No modules.

Resources

Name	Type
aws_cloudwatch_event_rule.default	resource
aws_cloudwatch_event_target.default	resource
aws_cloudwatch_log_group.default	resource
aws_iam_policy.default	resource
aws_iam_role.default	resource
aws_iam_role_policy_attachment.default	resource
aws_lambda_function.default	resource
aws_lambda_permission.default	resource
archive_file.function	data source
aws_caller_identity.current	data source
aws_iam_policy_document.assume-role	data source
aws_iam_policy_document.default	data source
aws_kms_alias.lambda	data source
external_external.node_modules	data source

Inputs

Name	Description	Type	Default	Required
github_organisation	GitHub organisation to sync SSO groups and members from	string	n/a	yes
github_token	GitHub token to perform API calls. Must have the following scopes: read:org	string	n/a	yes
not_dry_run	Whether this is a dry run Lambda or not	string	false	no
sso_aws_region	Region that AWS SSO is configured in (required for the SCIM URL)	string	n/a	yes
sso_email_suffix	Email suffix to use in AWS SSO. It's arbitrary, but may be useful if syncing more than one GitHub organisation	string	n/a	yes
sso_identity_store_id	AWS SSO Identity Store ID. Available from the AWS SSO Identity Source settings	string	n/a	yes
tags	Tags to apply to resources, where applicable	map(any)	{}	no

Outputs

No outputs.

Running the function locally

To run the function locally add the following line to the end of the index.js file:

(async function() { await module.exports.handler() })()

From the function folder, ensure you have the correct version of node installed and run npm install. Set your AWS root account credentials and then run the fuction with:

GITHUB_ORGANISATION=ministryofjustice GITHUB_TOKEN=<your token> SSO_AWS_REGION=eu-west-2 SSO_EMAIL_SUFFIX='@digital.justice.gov.uk' SSO_IDENTITY_STORE_ID=<the ID from console> node index.js

Replacing with an appropriate GitHub token etc.