[thirdparty/cups.git] / doc / help / kerberos.html

<HTML>
<!-- SECTION: Getting Started -->
<HEAD>
	<TITLE>Using Kerberos Authentication</TITLE>
	<LINK REL="STYLESHEET" TYPE="text/css" HREF="../cups-printable.css">
</HEAD>
<BODY>

<H1 CLASS="title">Using Kerberos Authentication</H1>

<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>


<H2 CLASS="title"><A NAME="REQUIREMENTS">System Requirements</A></H2>

<p>The following are required to use Kerberos with CUPS:</p>

<ol>

	<li>Heimdal Kerberos (any version) or MIT Kerberos (1.6.3 or newer)</li>

	<li>Properly configured Domain Name System (DNS) infrastructure (for your servers):<ol type='a'>
		<li>DNS server(s) with static IP addresses for all CUPS servers or configured to allow DHCP updates to the host addresses and</li>
		<li>All CUPS clients and servers configured to use the same
DNS server(s).</li>
	</ol></li>

	<li>Properly configured Kerberos infrastructure:<ol type='a'>
		<li>KDC configured to allow CUPS servers to obtain Service Granting Tickets (SGTs) for the "host" service,</li>
		<li>LDAP-based user accounts - both OpenDirectory and ActiveDirectory provide this with the KDC, and</li>
		<li>CUPS clients and servers bound to the same KDC and LDAP
	server(s).</li>
	</ol></li>

</ol>


<H2 CLASS="title"><A NAME="KRB5">Configuring Kerberos on Your System</A></H2>

<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>

<UL>

	<LI><A HREF="http://web.mit.edu/kerberos/">Kerberos: The Network Authentication Protocol</A></LI>

	<LI><A HREF="http://web.mit.edu/macdev/KfM/Common/Documentation/faq-osx.html">Kerberos
	on macOS Frequently Asked Questions</A></LI>

</UL>

<P>The Linux Documentation Project also has a HOWTO on Kerberos:</P>

<UL>

	<LI><A HREF="http://tldp.org/HOWTO/html_single/Kerberos-Infrastructure-HOWTO/">Kerberos
	Infrastructure HOWTO</A></LI>

</UL>


<H2 CLASS="title"><A NAME="CUPS">Configuring CUPS to Use Kerberos</A></H2>

<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>

<PRE CLASS="command">
<KBD>cupsctl DefaultAuthType=Negotiate</KBD>
</PRE>

<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>

<PRE CLASS="command">
http://server.example.com:631/admin
</PRE>

<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>


<H2 CLASS="title"><A NAME="IMPLEMENT">Implementation Information</A></H2>

<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>

<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>

<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>

</BODY>
</HTML>
Commit	Line	Data
355e94dc MS	1	<HTML>
	2	<!-- SECTION: Getting Started -->
	3	<HEAD>
	4	<TITLE>Using Kerberos Authentication</TITLE>
178cb736	5	<LINK REL="STYLESHEET" TYPE="text/css" HREF="../cups-printable.css">
355e94dc MS	6	</HEAD>
	7	<BODY>
	8
178cb736 MS	9	<H1 CLASS="title">Using Kerberos Authentication</H1>
178cb736 MS	10
771bd8cb	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>
355e94dc	12
76cd9e37	13
749b1e90	14	<H2 CLASS="title"><A NAME="REQUIREMENTS">System Requirements</A></H2>
76cd9e37	15
749b1e90 MS	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
771bd8cb MS	22	<li>Properly configured Domain Name System (DNS) infrastructure (for your servers):<ol type='a'>
771bd8cb MS	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>
749b1e90	24	<li>All CUPS clients and servers configured to use the same
771bd8cb	25	DNS server(s).</li>
749b1e90 MS	26	</ol></li>
	27
	28	<li>Properly configured Kerberos infrastructure:<ol type='a'>
771bd8cb MS	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>
749b1e90 MS	33	</ol></li>
749b1e90 MS	34
749b1e90	35	</ol>
76cd9e37	36
355e94dc MS	37
	38	<H2 CLASS="title"><A NAME="KRB5">Configuring Kerberos on Your System</A></H2>
	39
771bd8cb	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>
355e94dc MS	41
	42	<UL>
	43
771bd8cb	44	<LI><A HREF="http://web.mit.edu/kerberos/">Kerberos: The Network Authentication Protocol</A></LI>
355e94dc MS	45
355e94dc MS	46	<LI><A HREF="http://web.mit.edu/macdev/KfM/Common/Documentation/faq-osx.html">Kerberos
8072030b	47	on macOS Frequently Asked Questions</A></LI>
355e94dc MS	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
dd3fdd2c	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>
355e94dc MS	64
	65	<PRE CLASS="command">
	66	<KBD>cupsctl DefaultAuthType=Negotiate</KBD>
	67	</PRE>
	68
771bd8cb	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>
355e94dc MS	70
355e94dc MS	71	<PRE CLASS="command">
771bd8cb	72	http://server.example.com:631/admin
355e94dc MS	73	</PRE>
355e94dc MS	74
771bd8cb	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>
355e94dc MS	76
	77
	78	<H2 CLASS="title"><A NAME="IMPLEMENT">Implementation Information</A></H2>
	79
771bd8cb MS	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
1960468b	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>
355e94dc MS	85
	86	</BODY>
	87	</HTML>