#822 Built-in & LDAP documentation

nemerosa · May 1, 2021 · 8843b7d · 8843b7d
1 parent 0062120
commit 8843b7d
Show file tree

Hide file tree

Showing 7 changed files with 88 additions and 69 deletions.
diff --git a/ontrack-docs/src/docs/asciidoc/administration-accounts.adoc b/ontrack-docs/src/docs/asciidoc/administration-accounts.adoc
@@ -0,0 +1,2 @@
+[[administration-accounts]]
+=== Accounts management
diff --git a/ontrack-docs/src/docs/asciidoc/administration.adoc b/ontrack-docs/src/docs/asciidoc/administration.adoc
@@ -1,12 +1,12 @@
 [[administration]]
 == Administration
 
-include::security.adoc[]
+include::administration-accounts.adoc[]
 
-include::ldap.adoc[]
+// TODO include::security.adoc[]
 
-include::admin-console.adoc[]
+// TODO include::admin-console.adoc[]
 
-include::admin-log-entries.adoc[]
+// TODO include::admin-log-entries.adoc[]
 
-include::admin-status.adoc[]
+// TODO include::admin-status.adoc[]
diff --git a/ontrack-docs/src/docs/asciidoc/authentication-built-in.adoc b/ontrack-docs/src/docs/asciidoc/authentication-built-in.adoc
@@ -1,2 +1,22 @@
 [[authentication-built-in]]
 === Built-in authentication
+
+Ontrack comes with its own registry to store accounts. In particular, it contains the built-in `admin` user.
+
+[NOTE]
+====
+While having a fallback `admin` user, it's not recommended to use the built-in authentication for the rest of the users. Privilegiate using either the <<authentication-ldap,LDAP>> or <<authentication-openid,OIDC>> integrations for production usage.
+====
+
+No configuration is needed to enable the built-in authentication.
+
+To create and manage accounts, go to your user menu and select _Account management_.
+
+When user are connected using the built-in authentication mechanism, they are able to change their password using the _Change password_ user menu.
+
+[NOTE]
+====
+Administrators can _lock_ built-in users so they cannot change their password; this is needed to create fixed guest accounts.
+====
+
+For the management of built-in accounts, see <<administration-accounts>>.
diff --git a/ontrack-docs/src/docs/asciidoc/authentication-ldap.adoc b/ontrack-docs/src/docs/asciidoc/authentication-ldap.adoc
@@ -1,2 +1,55 @@
 [[authentication-ldap]]
 === LDAP authentication
+
+It is possible to enable authentication using a LDAP instance and to use the
+LDAP-defined groups to map them against Ontrack groups.
+
+[[authentication-ldap-setup]]
+==== LDAP general setup
+
+As an _administrator_, go to the _Settings_ menu. In the _LDAP settings_ section, click on _Edit_ and fill the following parameters:
+
+* _Enable LDAP authentication_: Yes
+* _URL_: URL to your LDAP
+* _User_ and _Password_: credentials needed to access the LDAP
+* _Search base_: query to get the user
+* _Search filter_: filter on the user query
+* _Full name attribute_: attribute which contains the full name, `cn` by
+default
+* _Email attribute_: attribute which contains the email, `email` by default
+* _Group attribute_: attribute which contains the list of groups a user belongs
+to, `memberOf` by default
+* _Group filter_: optional, name of the OU field used to filter groups a user belongs to
+
+IMPORTANT: The list of groups (indicated by the `memberOf`
+attribute or any other attribute defined by the _Group attribute_
+property) is not searched recursively and that only the direct groups
+are taken into account.
+
+For example:
+
+image::images/security.ldap.png[LDAP settings,400]
+
+TIP: The settings shown above are suitable to use with an Activate Directory LDAP instance.
+
+[[ldap-mapping]]
+==== LDAP group mapping
+
+A LDAP group a user belongs to can be used to map onto an Ontrack group.
+
+As an _administrator_, go to the _Account management_ menu and click on the _LDAP mapping_ command.
+
+NOTE: This command is only available if the LDAP authentication has been enabled in the general settings.
+
+To add a new mapping, click on _Create mapping_ and enter:
+
+* the _name_ of the LDAP group you want to map
+* the Ontrack _group_ which must be mapped
+
+For example, if you map the `ontrack_admin` LDAP group to an _Administrators_ group in Ontrack, any user who belongs to _ontrack_admin_ will automatically be assigned to the _Administrators_ group when connecting.
+
+NOTE: This assignment based on mapping is dynamic only, and no information is stored about it in Ontrack.
+
+Note that those LDAP mappings can be generated using <<casc,configuration as code>>.
+
+Existing mappings can be updated and deleted.
diff --git a/ontrack-docs/src/docs/asciidoc/authentication.adoc b/ontrack-docs/src/docs/asciidoc/authentication.adoc
@@ -7,8 +7,13 @@ Ontrack supports the following authentication backends:
 * <<authentication-ldap,LDAP>>
 * <<authentication-openid,OpenID>>
 
+[NOTE]
+====
+Ontrack is able to work with multiple sources of authentication.
+====
+
 include::authentication-built-in.adoc[]
 
 include::authentication-ldap.adoc[]
 
-include::authentication-openid.adoc[]
+include::authentication-openid.adoc[]
diff --git a/ontrack-docs/src/docs/asciidoc/index.adoc b/ontrack-docs/src/docs/asciidoc/index.adoc
@@ -31,4 +31,6 @@ include::usage.adoc[]
 
 include::api.adoc[]
 
+include::administration.adoc[]
+
 // ========================================================
diff --git a/ontrack-docs/src/docs/asciidoc/ldap.adoc b/ontrack-docs/src/docs/asciidoc/ldap.adoc