From 8843b7d3df39c9c30dd2e3faa67ccd89d539827f Mon Sep 17 00:00:00 2001 From: Damien Coraboeuf Date: Sat, 1 May 2021 08:15:41 +0200 Subject: [PATCH] #822 Built-in & LDAP documentation --- .../asciidoc/administration-accounts.adoc | 2 + .../src/docs/asciidoc/administration.adoc | 10 +-- .../asciidoc/authentication-built-in.adoc | 20 ++++++ .../docs/asciidoc/authentication-ldap.adoc | 53 ++++++++++++++++ .../src/docs/asciidoc/authentication.adoc | 7 ++- ontrack-docs/src/docs/asciidoc/index.adoc | 2 + ontrack-docs/src/docs/asciidoc/ldap.adoc | 63 ------------------- 7 files changed, 88 insertions(+), 69 deletions(-) create mode 100644 ontrack-docs/src/docs/asciidoc/administration-accounts.adoc delete mode 100644 ontrack-docs/src/docs/asciidoc/ldap.adoc diff --git a/ontrack-docs/src/docs/asciidoc/administration-accounts.adoc b/ontrack-docs/src/docs/asciidoc/administration-accounts.adoc new file mode 100644 index 00000000000..4002ad4d0b9 --- /dev/null +++ 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 index ed55e2fbfb0..1bcf45aed01 100644 --- 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 index 6cce806e4bd..9be9a1ba77f 100644 --- 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 <> or <> 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 <>. diff --git a/ontrack-docs/src/docs/asciidoc/authentication-ldap.adoc b/ontrack-docs/src/docs/asciidoc/authentication-ldap.adoc index 7725b156f97..670372df320 100644 --- 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 <>. + +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 index ccaad980017..3c54a40d82b 100644 --- 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: * <> * <> +[NOTE] +==== +Ontrack is able to work with multiple sources of authentication. +==== + include::authentication-built-in.adoc[] include::authentication-ldap.adoc[] -include::authentication-openid.adoc[] \ No newline at end of file +include::authentication-openid.adoc[] diff --git a/ontrack-docs/src/docs/asciidoc/index.adoc b/ontrack-docs/src/docs/asciidoc/index.adoc index 21be2195fbc..5912ce25d5f 100644 --- 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 deleted file mode 100644 index 4b864807d39..00000000000 --- a/ontrack-docs/src/docs/asciidoc/ldap.adoc +++ /dev/null @@ -1,63 +0,0 @@ -[[ldap]] -=== LDAP setup - -It is possible to enable authentication using a LDAP instance and to use the -LDAP-defined groups to map them against Ontrack groups. - -[[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: As of version 2.14, 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 the DSL. - -Existing mappings can be updated and deleted.