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[]
 
+
+Single Sign-On (SSO) enables organization owners and admins 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 IdPs, implementing the OpenID Connect (OIDC) protocol.
+
+As the service provider, Neo4j Aura redirects authentication requests to the configured IdP using the OpenID Connect (OIDC) protocol. 
+Aura also supports authenticating with Google as the identity provider.
+When a user attempts to log in, Aura generates a redirect URL with authentication parameters and sends the user to the IdP for authentication. 
+After successful authentication, 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.
+Users with either the `Organization admin` or the `Organization owner` role can configure SSO at both the organization-level and project-level.
 SSO is a log-in method. 
 Access, roles, and permissions are dictated by role-based access control (RBAC).
 
@@ -17,28 +27,29 @@ Access, roles, and permissions are dictated by role-based access control (RBAC).
 * *Project-level:*  Impacts new database instances created within that project.
 It ensures users logging in with SSO have access to the database instances within the project.
 It depends on RBAC if the user can access and view or modify data within the instances themselves.
-For this level, the role mapping may be used to grant users different levels of access based on a role in their identity provider (IdP).
+For this level, the role mapping may be used to grant users different levels of access based on a role in their IdP.
 It *does not* give access to edit the project settings, for example to edit the project name, network access, or to edit the instance settings such as to rename an instance, or pause and resume.
 
 == Log-in methods
 
 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.
 
 == Setup requirements
 
@@ -47,38 +58,109 @@ 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 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. 
 
-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 configuration
+
+=== 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 configuration in the Aura console
+
+. Go to *Organization Settings*
+
+. Select if you want the SSO configuration to be applied to organization logins, to specific projects within the organization, or both.
+
+. For IdP Type select *Microsoft Entra ID*
+
+. 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*
+
+== Pilot testing
+
+*Organization-level testing*
+
+Keep the Email/password or Google 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 database.
+Create a new instance in the project with SSO and login.
+
+== 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 Microsoft Entra ID. 
+If it already is, contact support for further assistance.