SSO Azure requirements

modules/ROOT/pages/security/single-sign-on.adoc

@@ -6,9 +6,19 @@ label:AuraDB-Virtual-Dedicated-Cloud[]
 label:AuraDB-Business-Critical[]
 label:AuraDS-Enterprise[]
 
+== Introduction to SSO
+
+Single Sign-On (SSO) enables you to use your organization’s identity provider (IDP) to authenticate users so they can access the Aura console and Aura instances.
+
+Aura supports SSO authentication and authorization using https://learn.microsoft.com/en-us/entra/identity-platform/v2-protocols-oidc[Microsoft Entra] and link:https://developer.okta.com/docs/guides/oin-sso-overview/[Okta] as identity providers, implementing the OpenID Connect (OIDC) protocol.
+
+As the service provider, Neo4j Aura redirects authentication requests to the configured identity provider (IDP) using the OpenID Connect (OIDC) protocol. 
+When a user attempts to log in, Aura generates a redirect URL with authentication parameters and sends the user to the IDP for authentication. 
+Upon successful login, the IDP redirects the user back to Aura with a secure token, allowing Aura to establish an authenticated session.
+
 == SSO levels
 
-Organization admins can configure SSO at the organization-level and project-level.
+`Organization admins` and `Organization owner` roles can configure SSO at the organization-level and project-level.
 SSO is a log-in method. 
 Access, roles, and permissions are dictated by role-based access control (RBAC).
 
@@ -25,20 +35,35 @@ It *does not* give access to edit the project settings, for example to edit the
 Log-in methods are different for each SSO level.
 Administrators can configure a combination of one or more of the log-in methods.
 
-*Organization-level supports:*
+*Supported log-in methods at the organization-level:*
 
 * Email/password
 * Okta
 * Microsoft Entra ID
 * Google SSO (not Google Workspace SSO)
 
-*Project-level supports:*
+*Supported log-in methods at the project-level:*
 
 * User/password
 * Okta
 * Microsoft Entra ID
 
-At the project-level admins cannot disable user/password, but at the organization-level admins can disable email/password and Google SSO as long as there is at least one other custom SSO provider configured.
+At the project-level, admins cannot disable user/password. 
+However, at the organization-level, admins can disable email/password and Google SSO as long as at least one other custom SSO provider is configured.
+
+== Pilot testing
+
+*Organization-level testing*
+
+Keep the Email/password log-in method enabled, so that if SSO fails, you can still access the Aura console and adjust the configuration.
+
+Login to the Aura console with SSO.
+
+*Project level-testing*
+
+Keep the User/password login enabled, so that if SSO fails, you can still access the Aura console and adjust the configuration.
+
+Create a new instance in the project with SSO and login.
 
 == Setup requirements
 
@@ -47,38 +72,99 @@ Accessing Aura with SSO requires:
 * Authorization Code Flow
 * A publicly accessible IdP server
 
+Aura requires the Authorization Code Flow, an OAuth2 authentication method that involves redirecting users to an Identity Provider (IdP) for login.
+
 To create an SSO Configuration, either a Discovery URI or a combination of Issuer, Authorization Endpoint, Token Endpoint, and JWKS URI is required.
 
 == Create a new SSO configuration
 
-From the *Organization settings*, go to *Single Sign-On* to set up a new SSO configuration.
+. From the *Organization settings*, go to *Single Sign-On* to set up a new SSO configuration.
 
-The checkboxes *Use as a log in for the Organization* and *Use as login method for instances with projects in this Org* define whether SSO should be only on Organization level, only on Project level, or both.
+. The checkboxes *Use as a log in for the Organization* and *Use as login method for instances with projects in this Org* define whether SSO should be only on organization-level, only on project-level, or both. 
+Selecting both checkboxes means the SSO setup applies to both the organization-level and project-level.
 
-The required basic SSO configuration information can be retrieved from the IdP.
+. The required basic SSO configuration information can be retrieved from the IdP.
 Entering the Discovery URI pre-fills the fields below.
 If this is not known these fields can be completed manually.
 
 .SSO configuration
 [.shadow]
 image::sso.png[A screenshot of the SSO configuration,640,480]
 
+== Log-in link
+
+After setting up SSO, the `Organization sso login` link can be found in the organization summary page in the Aura console.
+
 == Role mapping
 
-Role mapping applies to all new instances in the selected project.
+Role mapping applies to all new instances created within the selected project.
 To configure role mapping for an individual instance, contact support.
 
 == Individual instance-level
 
 Support can assist with SSO configurations at instance-level including:
 
 * Role mapping specific to a database instance
-* Custom groups claim besides `groups`
+* link:https://auth0.com/docs/secure/tokens/json-web-tokens/create-custom-claims[Create custom claims] besides `groups`
 * Updating SSO on already running instances
 
-If you require support assistance, visit link:https://support.neo4j.com/[Customer Support] and raise a support ticket including the following information:
+== Support
 
+If you require support assistance, visit link:https://support.neo4j.com/[Customer Support] and raise a support ticket including the following information:
 
 . The _Project ID_ of the projects you want to use SSO for. Click on the project settings to copy the ID.
 
 . The name of your IdP
+
+== Azure config
+
+=== Azure SSO configuration
+
+. In the *Azure Portal*, go to *App Registrations* and then *New Registration*.
+
+. Add a name for the new app registration and select *Register*. 
+Skip redirect URI’s for now.
+
+. On the app overview page, take note of the Application (client) ID.
+
+. Select the *Client Credentials* link to open the client credentials page.
+
+. Create a new secret and *copy the Value field*, it won’t be visible after leaving the page.
+
+. Go back to the *App Overview* page and open the *App Endpoints* and take note of the OpenID Connection metadata document URI
+
+. Under *Authentication* in the left-hand navigation, setup redirect URLs:
+
+.. Adding a new Web platform 
+.. Enter `https://login.neo4j.com/login/callback` as the redirect URI.
+
+=== Create an Azure SSO config in the Aura console
+
+. Go to *Organization Settings*
+
+. Select if you want the SSO config to be applied to organization logins, to specific projects within the organization, or both
+
+. For IdP Type select *Azure Active Directory*
+
+. For Client ID enter the *Application (client) ID* from the Azure app
+
+. For Client Secret enter the client secret value (not secret id) from the secret you created in the Azure app
+
+. For Discovery URI enter the *OpenID Connect metadata document URI*
+
+. Configure any additional settings as needed
+
+. Select *Create*
+
+== FAQ
+
+*Can users get roles added to them in Aura console via SSO and a group to role mapping?*
+
+No, users must be granted the role on the org via Aura console invites and access management like with any other organization.
+
+*Why am I unable to connect to the instance after completing the SSO login, the connection is showing as unconnected?*
+
+Ensure that the email field is provided on your user in Entra. If it already is, contact support for further assistance.
+
+
+