SSO Azure requirements

modules/ROOT/pages/platform/api/authentication.adoc

@@ -6,13 +6,14 @@ The Aura API uses OAuth 2.0 for API authentication.
 
 == Creating credentials
 
-[NOTE]
-====
-Enterprise users have unrestricted access to creating API credentials.
+AuraDB Virtual Dedicated Cloud users, and AuraDS Enterprise users have unrestricted access to creating API credentials.
 However, users with Free and Professional instances must have entered billing information or be a member of a marketplace project before they can create API credentials.
-====
+API credentials are linked to the user account, inheriting its capabilities and roles.
+The API credentials never expire unless you delete them.
 
-. Navigate to the https://console.neo4j.io/#account[Neo4j Aura console Account Details page] in your browser.
+To create credentials:
+
+. Navigate to the https://console.neo4j.io/#account[Neo4j Aura Console Account Details page] in your browser.
 . Select the *Create* button in the *Aura API Credentials* section.
 . Enter a *Client name*, and select *Create*.
 . Securely save the *Client ID* and *Client Secret* you are given in the resulting modal; you will need these for the next step.
@@ -63,7 +64,7 @@ Authentication to the token endpoint uses HTTP Basic Authentication, where the c
 |===
 |Parameter |Value
 
-|grant_type
+|`grant_type`
 |`client_credentials`
 |===
 
@@ -112,7 +113,7 @@ response = requests.request(
 print(response.json())
 ----
 
-<1> `client_id` and `client_secret` must be set to the values obtained from the Aura console.
+<1> `client_id` and `client_secret` must be set to the values obtained from the Aura Console.
 =====
 ====
 
@@ -123,12 +124,14 @@ print(response.json())
 ----
 {
   "access_token": "<token>", <1>
-  "expires_in": 3600,
+  "expires_in": 3600, <2>
   "token_type": "bearer"
 }
 ----
 
 <1> The `access_token` returned here is what you will provide as the Bearer Token in the `Authorization` header of Aura API requests.
+<2> The value of `expires_in` is the token expiration time in seconds. 
+Once the token expires, the application must request a new one.
 
 ==== HTTP response codes
 
@@ -157,7 +160,17 @@ print(response.json())
 |The request body is missing.
 |===
 
+=== Excessive token requests
+
+Excessive token requests may cause inefficiencies or rate-limiting. 
+You can optimize your API usage by following these steps:
+
+* *Retrieve the token once per hour:* As tokens remain valid for an hour, reduce the frequency of token requests and reuse the same token for multiple API calls.
+
+* *Implement token caching:* Store the token securely within your system to reuse it for subsequent requests during its validity period, minimizing unnecessary calls to the endpoint.
+
 === Token expiration
 
-If you attempt to send a request to the Aura API, authenticated using an expired access token, you will receive a 403 Forbidden response.
-You will need to obtain a new token to continue using the API.
+Access tokens are temporary and expire after one hour.
+If you send a request to the Aura API using an expired token, you will receive a `403 Forbidden` response. 
+To continue using the API, you must obtain a new token using the Aura API credentials.

modules/ROOT/pages/platform/api/overview.adoc

@@ -2,7 +2,10 @@
 = Overview
 :description: This page introduces the Aura API.
 
-The Aura API allows you to programmatically perform actions on your Aura instances without the need to log in to the console.
+label:AuraDB-Virtual-Dedicated-Cloud[]
+label:AuraDS-Enterprise[]
+
+The Aura API allows you to programmatically perform actions on your Aura instances without the need to log in to the Console.
 
 A complete list of the available endpoints can be seen and tested in the link:{neo4j-docs-base-uri}/aura/platform/api/specification/[API Specification].
 
@@ -34,13 +37,15 @@ The following example shows how to use the base URL and versioning to make a req
 
 == Retries
 
-In the event of `5xx` server error responses, you may consider retrying the request after a delay if it is safe to do so. The response may include a `Retry-After` header with a suggestion of a suitable minimum delay before attempting to retry.
+In the event of `5xx` server error responses, you may consider retrying the request after a delay if it is safe to do so.
+The response may include a `Retry-After` header with a suggestion of a suitable minimum delay before attempting to retry.
 
-Rate limiting is set to 125 requests per minute.
+The global rate limit for all requests is 125 requests per minute.
 
-You should consider your use of the Rate Limit before attempting to retry, and we recommend using an exponential backoff delay with a limited number of retries before giving up.
+You should consider your use of the rate limit before attempting to retry, and it is recommended that you use an exponential backoff delay with a limited number of retries before giving up.
 
-A request is only guaranteed to be safe to retry if it uses an idempotent HTTP method, such as `GET`. If for example, you attempt to retry a request for creating an instance, you may end up with duplicate instances and end up being charged extra as a result.
+A request is only guaranteed to be safe to retry if it uses an idempotent HTTP method, such as `GET`.
+If, for example, you retry a request for creating an instance, you may end up with duplicate instances and end up being charged extra as a result.
 
 In the case of `429 Too Many Requests`, we would recommend slowing down the rate of all requests sent from your client application and consider retrying with a suitable minimum delay and backoff strategy.
 
@@ -52,4 +57,4 @@ An `X-Request-Id` response header is returned with each request and can be used
 
 The value of this header contains a unique ID that can be used to track the journey of a request.
 
-If you run into any issues with a particular request, you can https://support.neo4j.com/[raise a support ticket] and provide the `X-Request-Id`.
+If you run into any issues with a particular request, you can https://support.neo4j.com/[raise a support ticket] and provide the `X-Request-Id`.

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.
+
+
+