https://doc.elabftw.net/assets/js/13081396.ae2f1515.js

1"use strict";(self.webpackChunkelabftw_documentation=self.webpackChunkelabftw_documentation||[]).push([["7551"],{4607(e,t,n){n.r(t),n.d(t,{metadata:()=>i,default:()=>c,frontMatter:()=>o,contentTitle:()=>r,toc:()=>d,assets:()=>l});var i=JSON.parse('{"id":"install/post-install/authentication/ldap","title":"LDAP authentication","description":"This page describes the configuration of LDAP authentication for an eLabFTW instance.","source":"@site/versioned_docs/version-5.6/install/post-install/authentication/4-ldap.md","sourceDirName":"install/post-install/authentication","slug":"/install/post-install/authentication/ldap","permalink":"/docs/5.6/install/post-install/authentication/ldap","draft":false,"unlisted":false,"editUrl":"https://github.com/elabftw/elabftw/edit/release/5.6/documentation/docs/install/post-install/authentication/4-ldap.md","tags":[],"version":"5.6","sidebarPosition":4,"frontMatter":{"sidebar_position":4,"title":"LDAP authentication"},"sidebar":"installSidebar","previous":{"title":"SAML authentication","permalink":"/docs/5.6/install/post-install/authentication/saml"},"next":{"title":"Microsoft Entra ID","permalink":"/docs/5.6/install/post-install/authentication/entraid"}}'),s=n(4848),a=n(8453);let o={sidebar_position:4,title:"LDAP authentication"},r="LDAP authentication",l={},d=[{value:"How does eLabFTW query LDAP servers?",id:"how-does-elabftw-query-ldap-servers",level:2},{value:"Sysadmin LDAP settings",id:"sysadmin-ldap-settings",level:2},{value:"Toggle LDAP login",id:"toggle-ldap-login",level:3},{value:"LDAP Scheme",id:"ldap-scheme",level:3},{value:"LDAP Host",id:"ldap-host",level:3},{value:"LDAP Port",id:"ldap-port",level:3},{value:"LDAP Base DN",id:"ldap-base-dn",level:3},{value:"LDAP Username",id:"ldap-username",level:3},{value:"LDAP Password",id:"ldap-password",level:3},{value:"Use TLS",id:"use-tls",level:3},{value:"By which LDAP attribute the user will be found",id:"by-which-ldap-attribute-the-user-will-be-found",level:3},{value:"What attribute to look for the team name",id:"what-attribute-to-look-for-the-team-name",level:3},{value:"Create team sent by server if it doesn&#39;t exist already",id:"create-team-sent-by-server-if-it-doesnt-exist-already",level:3},{value:"If no team attribute is found, to which team user is assigned?",id:"if-no-team-attribute-is-found-to-which-team-user-is-assigned",level:3},{value:"What attribute to look for ...",id:"what-attribute-to-look-for-",level:3},{value:"Using a custom cert file",id:"using-a-custom-cert-file",level:2}];function h(e){let t={code:"code",em:"em",h1:"h1",h2:"h2",h3:"h3",header:"header",li:"li",ol:"ol",p:"p",pre:"pre",strong:"strong",...(0,a.R)(),...e.components};return(0,s.jsxs)(s.Fragment,{children:[(0,s.jsx)(t.header,{children:(0,s.jsx)(t.h1,{id:"ldap-authentication",children:"LDAP authentication"})}),"\n",(0,s.jsx)(t.p,{children:"This page describes the configuration of LDAP authentication for an eLabFTW instance."}),"\n",(0,s.jsx)(t.p,{children:"It is possible to configure your LDAP instance to authenticate users through an LDAP service. Various settings are possible, to adapt to the different cases of LDAP servers."}),"\n",(0,s.jsx)(t.h2,{id:"how-does-elabftw-query-ldap-servers",children:"How does eLabFTW query LDAP servers?"}),"\n",(0,s.jsx)(t.p,{children:"The overall schematic for each query with the options set in the sysadmin menu looks like this:"}),"\n",(0,s.jsxs)(t.ol,{children:["\n",(0,s.jsx)(t.li,{children:"Connect to the LDAP server (-> TLS?, host, port)"}),"\n",(0,s.jsx)(t.li,{children:"Bind (login) with username and password, or anonymously (-> username, password)"}),"\n",(0,s.jsx)(t.li,{children:"Search for users within a certain region of the LDAP world directory (-> base DN) and extract certain properties/fields (-> filter attribute, team name, email, firstname, lastname)"}),"\n",(0,s.jsx)(t.li,{children:"Unbind (log out)"}),"\n"]}),"\n",(0,s.jsx)(t.p,{children:"For this to work, eLabFTW needs information from you, which is what the LDAP configuration options documented in the next section are for."}),"\n",(0,s.jsx)(t.h2,{id:"sysadmin-ldap-settings",children:"Sysadmin LDAP settings"}),"\n",(0,s.jsx)(t.p,{children:"The LDAP settings are found on the LDAP tab of the Sysconfig Panel."}),"\n",(0,s.jsx)(t.h3,{id:"toggle-ldap-login",children:"Toggle LDAP login"}),"\n",(0,s.jsx)(t.p,{children:"This is your general ON/OFF switch to toggle LDAP authentication from the login page. Note that if local login is left available, a radio button will allow users to select local/ldap login, and ldap will be selected by default. Generally, you'll want to disable local login once LDAP login is working (see setting for local login in first tab of sysconfig panel)."}),"\n",(0,s.jsx)(t.h3,{id:"ldap-scheme",children:"LDAP Scheme"}),"\n",(0,s.jsxs)(t.p,{children:["This setting allows you to override the scheme (",(0,s.jsx)(t.code,{children:"ldap"})," or ",(0,s.jsx)(t.code,{children:"ldaps"}),") used when connecting. This is because different LDAP implementations will require a different protocol depending on the use of TLS/StartTLS and the port. This setting is present to make sure we can cover all cases."]}),"\n",(0,s.jsx)(t.h3,{id:"ldap-host",children:"LDAP Host"}),"\n",(0,s.jsxs)(t.p,{children:["Enter the domain name or IP address of the LDAP server.\nThis should ",(0,s.jsx)(t.strong,{children:"not"})," include the protocol or the port, ",(0,s.jsx)(t.em,{children:"i.e."})," not ",(0,s.jsx)(t.code,{children:"ldaps://my.ldap.server:636"}),", but only ",(0,s.jsx)(t.code,{children:"my.ldap.server"}),'.\nFor selecting the protocol and port, use the dedicated "LDAP Port" and "Use TLS" options.']}),"\n",(0,s.jsx)(t.h3,{id:"ldap-port",children:"LDAP Port"}),"\n",(0,s.jsxs)(t.p,{children:["The port the LDAP server listens on, ",(0,s.jsx)(t.code,{children:"389"})," by default.\nUse port ",(0,s.jsx)(t.code,{children:"636"})," for LDAPS or any custom port you might have configured."]}),"\n",(0,s.jsx)(t.h3,{id:"ldap-base-dn",children:"LDAP Base DN"}),"\n",(0,s.jsxs)(t.p,{children:['This is the "Distinguished Name" for the search, ',(0,s.jsx)(t.em,{children:"i.e."})," which part of the (global) LDAP tree you want to find the users in.\nIt is probably something like ",(0,s.jsx)(t.code,{children:"dc=example,dc=org"}),', but might also include "Organizational Units", so something like ',(0,s.jsx)(t.code,{children:"ou=myinstitute,dc=example,dc=org"}),".\nImportantly, this is something completely different from the LDAP username, even though the notation might be similar."]}),"\n",(0,s.jsx)(t.h3,{id:"ldap-username",children:"LDAP Username"}),"\n",(0,s.jsxs)(t.p,{children:["This is the DN or username that connects (binds) to the LDAP server.\nExamples include ",(0,s.jsx)(t.code,{children:"myuser"})," or ",(0,s.jsx)(t.code,{children:"cn=AnAdminOf,ou=MyUnit,dc=example,dc=org"}),".\nThe user must have permission to query other users."]}),"\n",(0,s.jsx)(t.h3,{id:"ldap-password",children:"LDAP Password"}),"\n",(0,s.jsx)(t.p,{children:"This password is needed for the authentication on the LDAP server with the username specified above."}),"\n",(0,s.jsx)(t.h3,{id:"use-tls",children:"Use TLS"}),"\n",(0,s.jsx)(t.p,{children:"Select this if using LDAPS (= LDAP with TLS)."}),"\n",(0,s.jsx)(t.h3,{id:"by-which-ldap-attribute-the-user-will-be-found",children:"By which LDAP attribute the user will be found"}),"\n",(0,s.jsxs)(t.p,{children:['This is the "filter attribute" from above.\nCommon choices include ',(0,s.jsx)(t.code,{children:"cn"}),", ",(0,s.jsx)(t.code,{children:"uid"})," and the default ",(0,s.jsx)(t.code,{children:"mail"}),'.\nThis is the LDAP field that holds the information you want users to enter into the "login" field on the start page.']}),"\n",(0,s.jsx)(t.h3,{id:"what-attribute-to-look-for-the-team-name",children:"What attribute to look for the team name"}),"\n",(0,s.jsx)(t.p,{children:"The LDAP server will reply with the information associated with the user trying to authenticate.\nWhich field will be the one used to determine the team in which to create the user?"}),"\n",(0,s.jsx)(t.h3,{id:"create-team-sent-by-server-if-it-doesnt-exist-already",children:"Create team sent by server if it doesn't exist already"}),"\n",(0,s.jsx)(t.p,{children:"If the team found doesn't exist already, do you want to create one?"}),"\n",(0,s.jsx)(t.h3,{id:"if-no-team-attribute-is-found-to-which-team-user-is-assigned",children:"If no team attribute is found, to which team user is assigned?"}),"\n",(0,s.jsx)(t.p,{children:"Use this to add users to this team by default.\nUseful if the LDAP server doesn't answer with a team attribute that can be used for eLabFTW."}),"\n",(0,s.jsx)(t.h3,{id:"what-attribute-to-look-for-",children:"What attribute to look for ..."}),"\n",(0,s.jsx)(t.p,{children:"The last three fields are to specify the fields to look for for the user email, firstname and lastname."}),"\n",(0,s.jsx)(t.p,{children:".. note::"}),"\n",(0,s.jsxs)(t.p,{children:["If you encounter difficulties, make sure to get a useful log message before opening an issue, :doc:",(0,s.jsx)(t.code,{children:"see debug documentation <debug>"}),"."]}),"\n",(0,s.jsx)(t.h2,{id:"using-a-custom-cert-file",children:"Using a custom cert file"}

1),"\n",(0,s.jsxs)(t.p,{children:["When authenticating with a LDAPS server, a custom certfile might be needed.\nIt can easily be added by modifying the web/volumes part of ",(0,s.jsx)(t.code,{children:"elabftw.yml"})," like so:"]}),"\n",(0,s.jsx)(t.pre,{children:(0,s.jsx)(t.code,{className:"language-yaml",children:"services:\n  web:\n    ...\n    volumes:\n      ...\n      - /path/to/eLabFTW/certpath:/custom_certs\n      - /path/to/eLabFTW/openldap:/etc/openldap\n  ...\n...\n"})}),"\n",(0,s.jsxs)(t.p,{children:["Then, add your custom cert file to ",(0,s.jsx)(t.code,{children:"/path/to/eLabFTW/certpath"})," and at ",(0,s.jsx)(t.code,{children:"/path/to/eLabFTW/openldap/"})," add a new file ",(0,s.jsx)(t.code,{children:"ldap.conf"})," with the content"]}),"\n",(0,s.jsx)(t.pre,{children:(0,s.jsx)(t.code,{className:"language-bash",children:"TLS_CACERT /custom_certs/<certname>.pem\nTLS_REQCERT hard\n"})}),"\n",(0,s.jsxs)(t.p,{children:["where you substitute ",(0,s.jsx)(t.code,{children:"<certname>"})," for the name of the cert file for authenticating against the LDAP server.\nThis informs ",(0,s.jsx)(t.code,{children:"openldap"})," of the cert file and instructs it to always require a valid certificate from servers."]}),"\n",(0,s.jsxs)(t.p,{children:["After (re)starting using ",(0,s.jsx)(t.code,{children:"elabctl restart"}),", the LDAP server should now be reachable from inside the container.\nYou can check this via searching for a known user (like yourself?) via"]}),"\n",(0,s.jsx)(t.pre,{children:(0,s.jsx)(t.code,{className:"language-bash",children:"docker exec elabftw bash -c \"apk add openldap openldap-back-mdb openldap-clients && \\\n  ldapsearch -v -LLL \\\n    -H 'ldaps://<LDAP Host>' \\\n    -b '<LDAP Base DN>' \\\n    -D '<LDAP Username>' \\\n    -W \\\n    '<filter>'\"\n"})}),"\n",(0,s.jsxs)(t.p,{children:["where you might need to use ",(0,s.jsx)(t.code,{children:"sudo docker"})," if you are not ",(0,s.jsx)(t.code,{children:"root"}),".\nBe sure to substitute the ",(0,s.jsx)(t.code,{children:"<...>"})," fields with your values.\nThe command above installs the needed ",(0,s.jsx)(t.code,{children:"openldap"})," packages in the ",(0,s.jsx)(t.code,{children:"elabftw"})," container using Alpine Linux's package manager ",(0,s.jsx)(t.code,{children:"apk"})," and then launches a ldap search query.\n",(0,s.jsx)(t.code,{children:"<filter>"})," can for example be ",(0,s.jsx)(t.code,{children:"cn=MyOwnName"}),", or ",(0,s.jsx)(t.code,{children:"uid=5"}),".\nIf trying to connect to a LDAP server that listens on a port other than 636, specify it like ",(0,s.jsx)(t.code,{children:"-H 'ldaps://<host>:<port>'"}),"."]}),"\n",(0,s.jsxs)(t.p,{children:["For more information on the ",(0,s.jsx)(t.code,{children:"ldapsearch"})," command, consider"]}),"\n",(0,s.jsx)(t.pre,{children:(0,s.jsx)(t.code,{className:"language-bash",children:"docker exec elabftw ldapsearch --help\n"})}),"\n",(0,s.jsxs)(t.p,{children:["after installing the ",(0,s.jsx)(t.code,{children:"openldap"})," packages."]})]})}function c(e={}){let{wrapper:t}={...(0,a.R)(),...e.components};return t?(0,s.jsx)(t,{...e,children:(0,s.jsx)(h,{...e})}):h(e)}},8453(e,t,n){n.d(t,{R:()=>o,x:()=>r});var i=n(6540);let s={},a=i.createContext(s);function o(e){let t=i.useContext(a);return i.useMemo(function(){return"function"==typeof e?e(t):{...t,...e}},[t,e])}function r(e){let t;return t=e.disableParentContext?"function"==typeof e.components?e.components(s):e.components||s:o(e.components),i.createElement(a.Provider,{value:t},e.children)}}}]);