From f5dc8d2f788fad1eab415dc0d4185b1d5437aaef Mon Sep 17 00:00:00 2001 From: Badlop Date: Thu, 15 Apr 2010 17:20:57 +0200 Subject: [PATCH] Document GSSAPI (EJAB-831) --- README | 1 + doc/guide.html | 37 ++++++++++++++++++++++++++++++++- doc/guide.tex | 55 ++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 92 insertions(+), 1 deletion(-) diff --git a/README b/README index 360d62707..876f20d41 100644 --- a/README +++ b/README @@ -16,6 +16,7 @@ To compile ejabberd you need: - Erlang mysql library. Optional. MySQL authentication/storage. - Erlang pgsql library. Optional. PostgreSQL authentication/storage. - PAM library. Optional. For Pluggable Authentication Modules (PAM). + - ESASL library. Optional. For SASL GSSAPI authentication. - ImageMagick's Convert program. Optional. For CAPTCHA challenges. diff --git a/doc/guide.html b/doc/guide.html index 1a4178ea0..318f43640 100644 --- a/doc/guide.html +++ b/doc/guide.html @@ -350,6 +350,7 @@ GNU Make
  • Erlang mysql library. Optional. For MySQL authentication or storage. See section 3.2.1.
  • Erlang pgsql library. Optional. For PostgreSQL authentication or storage. See section 3.2.3.
  • PAM library. Optional. For Pluggable Authentication Modules (PAM). See section 3.1.4. +
  • ESASL library. Optional. For SASL GSSAPI authentication. See section 3.1.4.
  • ImageMagick’s Convert program. Optional. For CAPTCHA challenges. See section 3.1.8.

    • 2.4.2  Download Source Code

    @@ -1027,6 +1028,7 @@ database storage in internal Mnesia or ODBC — See section ldap — See section 3.2.5.

  • anonymous — See section 3.1.4.
  • pam — See section 3.1.4. +
  • a method with SASL GSSAPI — See section 3.1.4.

    • Account creation is only supported by the methods: internal Mnesia storage, ODBC storage, and external.

    Database Storage

    @@ -1178,7 +1180,40 @@ attacks. module provides such functionality.

  • If you use pam_winbind to authorise against a Windows Active Directory, then /etc/nssswitch.conf must be configured to use winbind as well. -

    • +

    +

    SASL GSSAPI Authentication

    +

    ejabberd supports SASL GSSAPI authentication. +It is compatible with SSO as implemented in Spark 2.5.3.

    To use this feature, you have to download the esasl library +source code from +http://github.com/mikma/esasl, +compile and install it. Example instructions: +

    git clone git://github.com/mikma/esasl.git
+cd esasl
+./configure --prefix=/usr
+make
+sudo make install
+

    After doing this, check that esasl was installed in the /usr/lib/erlang/lib/ directory. +For compiling esasl, maybe you need to get some development files; +(for example, in Debian, the package libgsasl7-dev).

    The SASL GSSAPI mechanism uses a authentication backend only to check for a +valid user name when authorizing the user. +The authentication is done by esasl against a Kerberos key server (KDC). +Often Kerberos authentication is combined with LDAP to store user account information. +To do that, edit ejabberd.cfg and modify the auth_mehtod depending +on what you want to allow. For example: +

    {auth_method, [ldap]}.
+

    Now define the Kerberos realm: +

    {sasl_realm, "Kerberos realm"}.
+

    and manually set the FQDN. +ejabberd does a reverse lookup on the connecting IP and uses +that FQDN for locating its keytab entry in the keytab file. +

    {sasl_fqdn, "dbs.example.com"}.
+

    The environment variable KRB5_KTNAME is the location of the keytab file, +and needs to be set before starting ejabberd. +The keytab referenced by KRB5_KTNAME should contain the principal xmpp/FQDN, +where FQDN is the fully qualified host name of the ejabberd server. +For example, in Debian, add to the file /etc/ejabberd/default the line: +

    export KRB5_KTNAME="/etc/keytabs/xmpp-dbs.example.com-EXAMPLE.COM.keytab
+

    3.1.5  Access Rules

    ACL Definition

    diff --git a/doc/guide.tex b/doc/guide.tex index d4c489920..e0ff370f9 100644 --- a/doc/guide.tex +++ b/doc/guide.tex @@ -316,6 +316,7 @@ To compile \ejabberd{} on a `Unix-like' operating system, you need: \item Erlang mysql library. Optional. For MySQL authentication or storage. See section \ref{compilemysql}. \item Erlang pgsql library. Optional. For PostgreSQL authentication or storage. See section \ref{compilepgsql}. \item PAM library. Optional. For Pluggable Authentication Modules (PAM). See section \ref{pam}. +\item ESASL library. Optional. For SASL GSSAPI authentication. See section \ref{gssapi}. \item ImageMagick's Convert program. Optional. For CAPTCHA challenges. See section \ref{captcha}. \end{itemize} @@ -1178,6 +1179,7 @@ The following authentication methods are supported by \ejabberd{}: \item ldap --- See section~\ref{ldap}. \item anonymous --- See section~\ref{saslanonymous}. \item pam --- See section~\ref{pam}. +\item a method with SASL GSSAPI --- See section~\ref{gssapi}. \end{itemize} Account creation is only supported by the methods: @@ -1400,6 +1402,59 @@ module provides such functionality. then \term{/etc/nssswitch.conf} must be configured to use \term{winbind} as well. \end{itemize} + +\makesubsubsection{gssapi}{SASL GSSAPI Authentication} +\ind{SASL GSSAPI authentication} + +\ejabberd{} supports SASL GSSAPI authentication. +It is compatible with SSO as implemented in Spark 2.5.3. + +To use this feature, you have to download the \term{esasl} library +source code from +\footahref{http://github.com/mikma/esasl}{http://github.com/mikma/esasl}, +compile and install it. Example instructions: +\begin{verbatim} +git clone git://github.com/mikma/esasl.git +cd esasl +./configure --prefix=/usr +make +sudo make install +\end{verbatim} +After doing this, check that esasl was installed in the \term{/usr/lib/erlang/lib/} directory. +For compiling esasl, maybe you need to get some development files; +(for example, in Debian, the package \term{libgsasl7-dev}). + +The SASL GSSAPI mechanism uses a authentication backend only to check for a +valid user name when authorizing the user. +The authentication is done by esasl against a Kerberos key server (KDC). +Often Kerberos authentication is combined with LDAP to store user account information. +To do that, edit \term{ejabberd.cfg} and modify the \term{auth\_mehtod} depending +on what you want to allow. For example: +\begin{verbatim} +{auth_method, [ldap]}. +\end{verbatim} + +Now define the Kerberos realm: +\begin{verbatim} +{sasl_realm, "Kerberos realm"}. +\end{verbatim} +and manually set the FQDN. +\ejabberd{} does a reverse lookup on the connecting IP and uses +that FQDN for locating its keytab entry in the keytab file. +\begin{verbatim} +{sasl_fqdn, "dbs.example.com"}. +\end{verbatim} + +The environment variable \term{KRB5\_KTNAME} is the location of the keytab file, +and needs to be set before starting ejabberd. +The keytab referenced by \term{KRB5\_KTNAME} should contain the principal xmpp/FQDN, +where FQDN is the fully qualified host name of the ejabberd server. +For example, in Debian, add to the file \term{/etc/ejabberd/default} the line: +\begin{verbatim} +export KRB5_KTNAME="/etc/keytabs/xmpp-dbs.example.com-EXAMPLE.COM.keytab +\end{verbatim} + + \makesubsection{accessrules}{Access Rules} \ind{access rules}\ind{ACL}\ind{Access Control List}