doc/help/kerberos.html

   1 <HTML>
   2 <!-- SECTION: Getting Started -->
   3 <HEAD>
   4         <TITLE>Using Kerberos Authentication</TITLE>
   5         <LINK REL="STYLESHEET" TYPE="text/css" HREF="../cups-printable.css">
   6 </HEAD>
   7 <BODY>
   8
   9 <H1 CLASS="title">Using Kerberos Authentication</H1>
  10
  11 <P>CUPS allows you to use a Key Distribution Center (KDC) for authentication on your local CUPS server and when printing to a remote authenticated queue. This document describes how to configure CUPS to use Kerberos authentication and provides links to the MIT help pages for configuring Kerberos on your systems and network.</P>
  12
  13
  14 <H2 CLASS="title"><A NAME="REQUIREMENTS">System Requirements</A></H2>
  15
  16 <p>The following are required to use Kerberos with CUPS:</p>
  17
  18 <ol>
  19
  20         <li>Heimdal Kerberos (any version) or MIT Kerberos (1.6.3 or newer)</li>
  21
  22         <li>Properly configured Domain Name System (DNS) infrastructure (for your servers):<ol type='a'>
  23                 <li>DNS server(s) with static IP addresses for all CUPS servers or configured to allow DHCP updates to the host addresses and</li>
  24                 <li>All CUPS clients and servers configured to use the same
  25 DNS server(s).</li>
  26         </ol></li>
  27
  28         <li>Properly configured Kerberos infrastructure:<ol type='a'>
  29                 <li>KDC configured to allow CUPS servers to obtain Service Granting Tickets (SGTs) for the "host" service,</li>
  30                 <li>LDAP-based user accounts - both OpenDirectory and ActiveDirectory provide this with the KDC, and</li>
  31                 <li>CUPS clients and servers bound to the same KDC and LDAP
  32         server(s).</li>
  33         </ol></li>
  34
  35 </ol>
  36
  37
  38 <H2 CLASS="title"><A NAME="KRB5">Configuring Kerberos on Your System</A></H2>
  39
  40 <P>Before you can use Kerberos with CUPS, you will need to configure Kerberos on your system and setup a system as a KDC. Because this configuration is highly system and site-specific, please consult the following on-line resources provided by the creators of Kerberos at the Massachusetts Institute of Technology (MIT):</P>
  41
  42 <UL>
  43
  44         <LI><A HREF="http://web.mit.edu/kerberos/">Kerberos: The Network Authentication Protocol</A></LI>
  45
  46         <LI><A HREF="http://web.mit.edu/macdev/KfM/Common/Documentation/faq-osx.html">Kerberos
  47         on macOS Frequently Asked Questions</A></LI>
  48
  49 </UL>
  50
  51 <P>The Linux Documentation Project also has a HOWTO on Kerberos:</P>
  52
  53 <UL>
  54
  55         <LI><A HREF="http://tldp.org/HOWTO/html_single/Kerberos-Infrastructure-HOWTO/">Kerberos
  56         Infrastructure HOWTO</A></LI>
  57
  58 </UL>
  59
  60
  61 <H2 CLASS="title"><A NAME="CUPS">Configuring CUPS to Use Kerberos</A></H2>
  62
  63 <P>Once you have configured Kerberos on your system(s), you can then enable Kerberos authentication by selecting the <tt>Negotiate</tt> authentication type. The simplest way to do this is using the <tt>cupsctl(8)</tt> command on your server(s):</P>
  64
  65 <PRE CLASS="command">
  66 <KBD>cupsctl DefaultAuthType=Negotiate</KBD>
  67 </PRE>
  68
  69 <P>You can also enable Kerberos from the web interface by checking the <VAR>Use Kerberos Authentication</VAR> box and clicking <VAR>Change Settings</VAR>:</P>
  70
  71 <PRE CLASS="command">
  72 http://server.example.com:631/admin
  73 </PRE>
  74
  75 <P>After you have enabled Kerberos authentication, use the built-in "authenticated" policy or your own custom policies with the printers you will be sharing. See <a href="policies.html">Managing Operation Policies</a> for more information.</P>
  76
  77
  78 <H2 CLASS="title"><A NAME="IMPLEMENT">Implementation Information</A></H2>
  79
  80 <P>CUPS implements Kerberos over HTTP using GSSAPI and the service name "host". Because of limitations in the HTTP GSSAPI protocol extension, only a single domain/KDC is supported for authentication. The HTTP extension is described in <a href="http://tools.ietf.org/html/rfc4559">RFC 4559</a>.</P>
  81
  82 <P>When doing printing tasks that require authentication, CUPS requests single-use "tickets" from your login session to authenticate who you are. These tickets give CUPS a username of the form "user@REALM", which is then converted to just "user" for purposes of user and group checks.</P>
  83
  84 <P>In order to support printing to a shared printer, CUPS runs the IPP backend as the owner of the print job so it can obtain the necessary credentials when the job is de-spooled to the server.</P>
  85
  86 </BODY>
  87 </HTML>