pr review comments

Author: phil198

modules/ROOT/pages/authentication-authorization/auth-providers.adoc

@@ -9,7 +9,11 @@ Authentication and authorization can be controlled on a user-level using Cypher
 In order to make use of Auth Providers, you need to set the `dbms.security.require_local_user` configuration setting to `true`.
 This setting mandates that only users with a corresponding Auth Provider in the database can authenticate and authorize.
 
-Auth Providers give you a way to link externally-defined users (e.g. in a 3rd party ID provider like OIDC or LDAP) to the Neo4j internal User model. The internal model can define things such as roles (authorization), `SUSPENDED` status, `HOME DATABASE`, and metadata such as the unique displayed name of the user. For consistency you can also define `native` (password-based) auth using the Auth Provider syntax, including native-only users (i.e. users who can only authenticate with a password).
+Auth Providers give you a way to link externally-defined users (e.g. in a 3rd party ID provider like OIDC or LDAP) to the Neo4j internal User model.
+
+The internal model can define things such as roles (authorization), `SUSPENDED` status, `HOME DATABASE`, and metadata such as the unique displayed name of the user.
+
+For consistency you can also define `native` (password-based) auth using the Auth Provider syntax, including native-only users (i.e. users who can only authenticate with a password).
 
 == Use Cases
 . Provisioning different auth providers (including native username/password auth) for different users.

modules/ROOT/pages/authentication-authorization/index.adoc

@@ -94,7 +94,7 @@ This is in contrast to a suspended user.
 This is a user who has been assigned the admin role.
 
 [[term-auth-provider]]Auth Provider::
-A map attached to a database user which defines which authentication and authorization config to use for that user.
+Properties attached to a user which define which authentication and authorization config to use for that user.
 
 [[term-authentication]]authentication::
 The process of verifying the identity of a user,

modules/ROOT/pages/authentication-authorization/manage-users.adoc

@@ -160,8 +160,8 @@ CREATE USER name [IF NOT EXISTS]
 SET AUTH [PROVIDER] 'provider' "{"
     {
         SET ID 'id' // a unique identifier of the user in an external system
-        \| SET [PLAINTEXT \| ENCRYPTED] PASSWORD 'password'
-        \| SET PASSWORD CHANGE [NOT] REQUIRED
+        \| SET [PLAINTEXT \| ENCRYPTED] PASSWORD 'password' // PASSWORD clauses are only applicable to the 'native' provider
+        \| SET PASSWORD CHANGE [NOT] REQUIRED // PASSWORD clauses are only applicable to the 'native' provider
     }
 "}"
 ----
@@ -210,8 +210,8 @@ CREATE OR REPLACE USER name
 SET AUTH [PROVIDER] 'provider' "{"
     {
         SET ID 'id' // a unique identifier of the user in an external system
-        \| SET [PLAINTEXT \| ENCRYPTED] PASSWORD 'password'
-        \| SET PASSWORD CHANGE [NOT] REQUIRED
+        \| SET [PLAINTEXT \| ENCRYPTED] PASSWORD 'password' // PASSWORD clauses are only applicable to the 'native' provider
+        \| SET PASSWORD CHANGE [NOT] REQUIRED // PASSWORD clauses are only applicable to the 'native' provider
     }
 "}"
 ----
@@ -297,8 +297,8 @@ ALTER USER name [IF EXISTS]
 SET AUTH [PROVIDER] 'provider' "{"
     {
         SET ID 'id' // a unique identifier of the user in an external system
-        \| SET [PLAINTEXT \| ENCRYPTED] PASSWORD 'password'
-        \| SET PASSWORD CHANGE [NOT] REQUIRED
+        \| SET [PLAINTEXT \| ENCRYPTED] PASSWORD 'password' // PASSWORD clauses are only applicable to the 'native' provider
+        \| SET PASSWORD CHANGE [NOT] REQUIRED // PASSWORD clauses are only applicable to the 'native' provider
     }
 "}"
 ----
@@ -551,7 +551,7 @@ SHOW USERS
 |===
 
 When first starting a Neo4j DBMS, there is always a single default user `neo4j` with administrative privileges.
-It is possible to set the initial password using xref:configuration/set-initial-password[`neo4j-admin dbms set-initial-password <password>`], otherwise it is necessary to change the password after the first login.
+It is possible to set the initial password using xref:configuration/set-initial-password.adoc[`neo4j-admin dbms set-initial-password <password>`], otherwise it is necessary to change the password after the first login.
 
 .Show user
 ======
@@ -620,8 +620,8 @@ For both `CREATE` and `CREATE OR REPLACE`, `<key><value>` pairs for the `SET AUT
 SET AUTH [PROVIDER] 'provider' "{"
     {
         SET ID 'id' // a unique identifier of the user in an external system
-        \| SET [PLAINTEXT \| ENCRYPTED] PASSWORD 'password'
-        \| SET PASSWORD CHANGE [NOT] REQUIRED
+        \| SET [PLAINTEXT \| ENCRYPTED] PASSWORD 'password' // PASSWORD clauses are only applicable to the 'native' provider
+        \| SET PASSWORD CHANGE [NOT] REQUIRED // PASSWORD clauses are only applicable to the 'native' provider
     }
 "}"
 ----
@@ -829,8 +829,8 @@ ALTER USER name [IF EXISTS]
 SET AUTH [PROVIDER] 'provider' "{"
     {
         SET ID 'id' // a unique identifier of the user in an external system
-        \| SET [PLAINTEXT \| ENCRYPTED] PASSWORD 'password'
-        \| SET PASSWORD CHANGE [NOT] REQUIRED
+        \| SET [PLAINTEXT \| ENCRYPTED] PASSWORD 'password' // PASSWORD clauses are only applicable to the 'native' provider
+        \| SET PASSWORD CHANGE [NOT] REQUIRED // PASSWORD clauses are only applicable to the 'native' provider
     }
 "}"
 ----

modules/ROOT/pages/tutorial/tutorial-sso-configuration.adoc

@@ -334,7 +334,7 @@ For example to create a user `jake` who can authenticate and authorize using Ent
 ----
 CREATE USER jake
 SET HOME DATABASE 'jakesHomeDb'
-SET AUTH 'oidc-okta' {SET ID 'jakesUniqueEntraUserId'} // `jakesUniqueEntraUserId` must match the value of the claim that you configured via dbms.security.oidc.azure.claims.username
+SET AUTH 'oidc-azure' {SET ID 'jakesUniqueAzureUserId'} // `jakesUniqueAzureUserId` must match the value of the claim that you configured via dbms.security.oidc.azure.claims.username
 ----
 
 See xref:authentication-authorization/sso-integration.adoc#auth-sso-auth-providers[SSO integration] for further examples.
@@ -375,9 +375,14 @@ dbms.security.oidc.google.config=token_type_principal=id_token;token_type_authen
 
 There are then two ways to create the user in the database (which is required to give the users roles from native authorization):
 
-. Using Auth Providers
-xref:authentication-authorization/auth-providers.adoc[Auth Providers] allow us to specify auth providers at the user-level which is useful in this scenario.
-This approach allows us to have an `admin` user who can authenticate natively, and can then create less privileged users who may only authenticate using `oidc-google` and will receive the roles granted to them using `native` authorization.
+. Using Auth Providers.
+xref:authentication-authorization/auth-providers.adoc[Auth Providers] allow us to specify authentication and authorization providers at the user-level which is useful in this scenario.
+This approach relies on the existence of an `admin` user who can authenticate natively, and can themselves create less privileged users who may only authenticate using `oidc-google` and who will receive the roles granted to them using `native` authorization.
+
+[NOTE]
+====
+An admin user with the name `neo4j` is created by default when the database is xref:configuration/set-initial-password.adoc[first started].
+====
 
 .. Change the configuration to allow `native` authentication (for use only by the `admin` user):
 
@@ -387,7 +392,7 @@ dbms.security.authentication_providers=oidc-google, native
 ----
 
 .. Set the `dbms.security.require_local_user` configuration setting to `true` in the _neo4j.conf_ file.
-This will switch to User Auth Providers mode whereby users can only authenticate and authorize if they have a corresponding Auth Provider in the database.
+This will switch to __User Auth Providers__ mode whereby users can only authenticate and authorize if they have a corresponding Auth Provider in the database.
 
 [source, properties]
 ----
@@ -411,9 +416,9 @@ SET AUTH 'oidc-google' {SET ID 'jakesUniqueGoogleUserId'} // `jakesUniqueGoogleU
 GRANT ROLE reader TO jake
 ----
 
-The user will implicitly receive `native` authorization because `native` is in the list of authorization providers and you have explicitly granted the user a `ROLE`.
+The user will implicitly receive `native` authorization because `native` is in the list of authorization providers and you have explicitly granted the user a role.
 
-You can now disable native authentication for the database completely:
+Once you have set up your users in this way, you can now disable native authentication for the database completely:
 
 [source, properties]
 ----
@@ -466,10 +471,6 @@ REQUIRED
 GRANT ROLE reader TO jakesUniqueGoogleUserId
 ----
 
-
-
-
-
 == FAQ
 
 === When should `pkce` be used as auth flow?