feat(am): add note into migration guide about the new way to boostrap…

… the administrator user

Fixes gravitee-io/issues#3975

pages/am/3.x/installation-guide/configuration/installation-guide-management-api-configuration.adoc

@@ -74,6 +74,54 @@ jetty:
       password:
 ----
 
+
+=== Security
+
+Since  AM 3.10, the security section allows you to define the users available to authenticate to the management console after the first start.
+Until AM 3.9, there was only one user `admin` created in a inline identity provider. In 3.10, this behaviour is preserve by enabling the `security.defaultAdmin` option (default value).
+
+This section introduce a providers section to define a set of identity providers instantiated on startup. These providers are not visible from the management UI.
+
+Currently, only the provider type `memory` is available. The users known by this provider are defined into a list named `users` (see example here after).
+For each user, you have to define one organization role:
+
+* ORGANIZATION_PRIMARY_OWNER
+* ORGANIZATION_OWNER
+* ORGANIZATION_USER
+
+If a user role or a user password is updated, new values are applied on restart.
+
+[source,yaml]
+----
+security:
+  # If true create on AM boostrap an inline identity provider with an admin user (login: admin)
+  # this is the legacy mode
+  defaultAdmin: true
+  ## authentication providers
+  ## currently, only "in memory" provider is supported
+  providers:
+    - type: memory
+      enabled: false
+      ## Name of IdentityProvider
+      ## If missing the type will be used to create a generic name (ex: Memory users)
+      #name:
+      ## password encoding/hashing algorithm. One of:
+      ## - BCrypt : passwords are hashed with bcrypt (supports only $2a$ algorithm)
+      ## - none : passwords are not hashed/encrypted
+      #default value is BCrypt
+      password-encoding-algo: BCrypt
+      users:
+        - username: admin
+          #email:
+          firstname: Administrator
+          lastname: Administrator
+          ## Passwords are encoded using BCrypt
+          ## Password value: adminadmin
+          password: $2a$10$NG5WLbspq8V1yJDzUKfUK.oum94qL/Ne3B5fQCgekw/Y4aOEaoFZq
+          role: ORGANIZATION_OWNER
+----
+
+
 === Configure email
 
 ----

pages/am/3.x/installation-guide/installation-guide-migration.adoc

@@ -10,6 +10,13 @@ WARNING: If you plan to skip versions when you upgrade, ensure that you read the
 
 WARNING: Be sure to run scripts on the correct database since `gravitee-am` is not always the default database! Check your db name by running `show dbs;`
 
+
+== Upgrade to 3.10.0
+
+=== Management API
+
+With previous versions the administrator user for the Management API was created on startup using hard coded values for username and password. Starting from 3.10.0 it is possible to define your own values thanks to the link:/am/current/am_installguide_management_api_configuration.html#security[security] section of the `gravitee.yml` file. By default, this configuration section use the same behaviour as AM 3.9 and earlier.
+
 == Upgrade to 3.9.0
 
 NOTE: For more information about the breaking changes of this version please visit link:/am/current/am_breaking_changes_3.9.html[Breaking changes in 3.9]