Update single sign on documentation

source/concepts/environments/single-sign-on.html.md.erb

@@ -1,7 +1,7 @@
 ---
 owner_slack: "#modernisation-platform"
 title: Single Sign On
-last_reviewed_on: 2024-06-28
+last_reviewed_on: 2024-11-14
 review_in: 6 months
 ---
 
@@ -18,29 +18,92 @@ review_in: 6 months
 
 ## Introduction
 
-We don't want to have to do identity management (joiners, movers, leavers) in the Modernisation Platform. To avoid this we use AWS single sign on (SSO), with AuthO (authentication and authorization as a service) and our GitHub Organisation Teams to manage access to environments.
+To enhance security and streamline access, we are moving towards a unified identity system across the Ministry of Justice (MoJ). Currently, AWS access is managed through AWS Identity Center using GitHub as our primary identity provider via Auth0. However, we’re also enabling Microsoft Entra ID for SSO, allowing you to access AWS resources with your `justice.gov.uk` credentials.
 
-## Diagram
+This transition aligns with our goal of simplifying identity management and security across platforms. Both GitHub and Entra ID authentication will remain available for now, with plans to fully transition to Entra ID in the future.
 
-![Single Sign On](../../images/single-sign-on.png "Single Sign On")
+---
+
+## Authentication Method 1: GitHub SSO (Current Method)
+
+**Overview**  
+GitHub SSO is currently managed through Auth0, which acts as our authentication provider and manages user identity using GitHub credentials.
+
+SSO workflow diagram can be found [here](../../images/single-sign-on.png)
+
+### Workflow
+
+1. **SSO Login**:  
+   Users access the SSO login portal at [https://moj.awsapps.com/start](https://moj.awsapps.com/start), hosted by AWS Identity Center.
+
+2. **Auth0 as Identity Provider**:  
+   AWS SSO redirects users to an Auth0 SSO login page. Auth0 is configured to use GitHub as the identity provider, prompting users to log in with their GitHub credentials.
+
+3. **SAML Authentication**:  
+   If authentication is successful, Auth0 sends a SAML response to AWS SSO, which verifies it and grants the user access to the AWS SSO portal.
+
+   - [The SAML Assertion Consumer Service (ACS)](<https://mojoauth.com/glossary/saml-assertion-consumer-service/#:~:text=A%20SAML%20Assertion%20Consumer%20Service,the%20identity%20provider%20(IdP).>) URL is used to identify where the service provider accepts SAML assertions.
+
+4. **System for Cross-Domain Identity Management (SCIM) Sync**:
+
+- AWS SSO provides support for SCIM v2.0 standard. SCIM keeps your AWS SSO identities in sync with identities from your IdP (GitHub).
+- A [scheduled Lambda job (index.js)](https://github.com/ministryofjustice/moj-terraform-scim-github) is used for SCIM provisioning from GitHub. A Node.js script uses the the GitHub API package Octokit to sync GitHub Groups and Users to AWS SSO. It does this by calling the AWS SSO SCIM endpoint.
+- SCIM will populate AWS SSO Groups and Users with the GitHub data.
+
+5. **Permission Sets**:
+
+- A permission set is a collection of administrator-defined policies that AWS SSO uses to determine a user’s effective permissions to access a given AWS account. The root permissions sets are managed in the [sso-admin-permission-sets.tf](https://github.com/ministryofjustice/aws-root-account/blob/main/management-account/terraform/sso-admin-permission-sets.tf) file whilst Modernisation Platform-specific permission sets are managed in [sso-permission-sets.tf](https://github.com/ministryofjustice/modernisation-platform/blob/main/terraform/single-sign-on/sso-permission-sets.tf).
+- The permission set is [mapped](https://github.com/ministryofjustice/modernisation-platform/blob/main/terraform/environments/bootstrap/single-sign-on/main.tf#L56) using Terraform to the associated AWS account as part of the baseline workflow..
+
+---
+
+## Authentication Method 2: Microsoft Entra ID SSO
 
-## Workflow
+**Overview**  
+Microsoft Entra ID enables users to access AWS with `justice.gov.uk` credentials, aiming to provide a more integrated and secure authentication experience.
 
-### 1. SSO Auth0 GitHub authentication
+### Workflow
 
- - Users access the SSO login portal via the link [https://moj.awsapps.com/start](https://moj.awsapps.com/start). This URL is hosted via the AWS SSO component.
- - AWS SSO is configured to use Auth0 as an application and sets the associated Application ACS URL. Auth0 will be the primary authentication endpoint providing the SSO with GitHub via SAML 2.0.
-    - The SAML Assertion Consumer Service (ACS) URL is [used to identify where the service provider accepts SAML assertions](https://mojoauth.com/glossary/saml-assertion-consumer-service/#:~:text=A%20SAML%20Assertion%20Consumer%20Service,the%20identity%20provider%20(IdP).).
- - AWS SSO redirects users to an Auth0 SSO URL login page. Auth0 is configured to used GitHub as its IdP (Identity Provider) and prompts users to authenticate using their GitHub credentials. If authentication is successful (or if the user is already authenticated on Auth0, this step will be skipped) Auth0 sends an encoded SAML response to the browser.
- - The browser sends the SAML response (SAML Assertion) to AWS SSO (service provider for verification). Once verified, the user is able to login to the AWS SSO portal.
+1. **SSO Login**:  
+   Users can access the AWS SSO login portal at [https://moj.awsapps.com/start](https://moj.awsapps.com/start), where they can choose to authenticate via Entra ID.
 
-### 2. System for Cross-domain Identity Management (SCIM) SSO
+2. **Entra ID Authentication**:  
+   Entra ID manages authentication using MoJ’s `justice.gov.uk` credentials, supporting MoJ’s unified identity strategy.
 
- - AWS SSO provides support for SCIM v2.0 standard. SCIM keeps your AWS SSO identities in sync with identities from your IdP (GitHub).
- - A [scheduled Lambda job (index.js)](https://github.com/ministryofjustice/moj-terraform-scim-github) is used for SCIM provisioning from GitHub. A Node.js script uses the the GitHub API package Octokit to sync GitHub Groups and Users to AWS SSO. It does this by calling the AWS SSO SCIM endpoint.
- - SCIM will populate  AWS SSO Groups and Users with the GitHub data.
+3. **Automatic Group Syncing**:  
+   AWS Identity Center supports SCIM to sync Entra ID groups and users automatically, ensuring that permissions reflect current Entra ID group memberships.
 
-### 3. SSO Permission Sets
+4. **Permission Sets**:  
+   Permission sets for Entra ID are defined in AWS Identity Center, mapping Entra ID groups to AWS accounts, making it easier to manage consistent permissions across environments.
 
- - A permission set is a collection of administrator-defined policies that AWS SSO uses to determine a user's effective permissions to access a given AWS account. The root permissions sets are managed in the [sso-admin-permission-sets.tf](https://github.com/ministryofjustice/aws-root-account/blob/main/management-account/terraform/sso-admin-permission-sets.tf) file whilst Modernisation Platform-specific permission sets are managed in [sso-permission-sets.tf](https://github.com/ministryofjustice/modernisation-platform/blob/main/terraform/single-sign-on/sso-permission-sets.tf).
- - The permission set is [mapped](https://github.com/ministryofjustice/modernisation-platform/blob/main/terraform/environments/bootstrap/single-sign-on/main.tf#L56) using Terraform to the associated AWS account as part of the baseline workflow.
+---
+
+## For Modernisation Platform Customers
+
+### Using Entra ID for AWS Access Management
+
+If you are a Modernisation Platform customer, you can configure Entra ID groups to manage access:
+
+1. **Create a Group in Entra ID**
+
+   - Log in to the Azure Portal, navigate to Entra ID > Manage > Groups, and create a group for your team with the naming prefix `azure-aws-sso-<yourteam>`.
+   - Add users with `justice.gov.uk` emails and set yourself as the group owner to manage memberships.
+
+2. **Automatic Syncing with AWS Identity Center**
+
+   - Entra ID groups will automatically sync with AWS Identity Center, ensuring that any changes in group membership reflect in AWS access permissions.
+
+3. **Updating Environment Files**
+   - In the Modernisation Platform, update the `sso-group` field in your environment files to use the Entra ID group name. This allows AWS Identity Center to recognize and sync permissions automatically.
+
+---
+
+## Frequently Asked Questions
+
+- **Do I need to switch to Entra ID now?**  
+  No action is required at this time. Both GitHub and Entra ID options will remain available, and you can continue using GitHub for access if preferred.
+
+- **What if I have questions?**  
+  For assistance, please reach out to #ask-modernisation-platform on Slack.
+
+---