[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:<ol type='a'>
		<li>DNS server(s) with static IP addresses for all CUPS clients
		and servers or configured to allow DHCP updates to the host
		addresses</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 clients and servers to obtain
		Service Granting Tickets (SGTs) for the "ipp" service</li>
		<li>LDAP-based user accounts - both OpenDirectory and
		ActiveDirectory provide this with the KDC</li>
		<li>CUPS clients and servers bound to the KDC and LDAP
		server(s)</li>
	</ol></li>

	<li>An "ipp" Service Granting Ticket (SGT) for every CUPS client and
	server</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 Massachussetts 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 Mac OS X 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:</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://localhost: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
"ipp". Because of limitations in the HTTP GSSAPI protocol extension, only
a single domain/KDC is supported for authentication.</P>

<P>When doing printing tasks that require authentication, CUPS requests a
single-use "ticket" from your login session to authenticate who you are.
This ticket gives 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 has to ask the KDC
for a copy of your credentials (this is called delegation) that can be sent to
the remote server for authenticatation. Delegation only works when the system
has a stable hostname which maps to the current address of the system, which
is why you need a static IP address or DHCP that updates the DNS entry for your
system.</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
749b1e90 MS	11	<P>CUPS allows you to use a Key Distribution Center (KDC) for authentication
	12	on your local CUPS server and when printing to a remote authenticated queue.
	13	This document describes how to configure CUPS to use Kerberos authentication
	14	and provides links to the MIT help pages for configuring Kerberos on your
	15	systems and network.</P>
355e94dc	16
76cd9e37	17
749b1e90	18	<H2 CLASS="title"><A NAME="REQUIREMENTS">System Requirements</A></H2>
76cd9e37	19
749b1e90 MS	20	<p>The following are required to use Kerberos with CUPS:</p>
	21
	22	<ol>
	23
	24	<li>Heimdal Kerberos (any version) or MIT Kerberos (1.6.3 or newer)</li>
	25
	26	<li>Properly configured Domain Name System (DNS)
	27	infrastructure:<ol type='a'>
	28	<li>DNS server(s) with static IP addresses for all CUPS clients
	29	and servers or configured to allow DHCP updates to the host
	30	addresses</li>
	31	<li>All CUPS clients and servers configured to use the same
	32	DNS server(s)</li>
	33	</ol></li>
	34
	35	<li>Properly configured Kerberos infrastructure:<ol type='a'>
	36	<li>KDC configured to allow CUPS clients and servers to obtain
	37	Service Granting Tickets (SGTs) for the "ipp" service</li>
	38	<li>LDAP-based user accounts - both OpenDirectory and
	39	ActiveDirectory provide this with the KDC</li>
	40	<li>CUPS clients and servers bound to the KDC and LDAP
	41	server(s)</li>
	42	</ol></li>
	43
	44	<li>An "ipp" Service Granting Ticket (SGT) for every CUPS client and
	45	server</li>
	46
	47	</ol>
76cd9e37	48
355e94dc MS	49
	50	<H2 CLASS="title"><A NAME="KRB5">Configuring Kerberos on Your System</A></H2>
	51
	52	<P>Before you can use Kerberos with CUPS, you will need to configure
	53	Kerberos on your system and setup a system as a KDC. Because this
	54	configuration is highly system and site-specific, please consult
	55	the following on-line resources provided by the creators of Kerberos
	56	at the Massachussetts Institute of Technology (MIT):</P>
	57
	58	<UL>
	59
	60	<LI><A HREF="http://web.mit.edu/kerberos/">Kerberos: The Network
	61	Authentication Protocol</A></LI>
	62
	63	<LI><A HREF="http://web.mit.edu/macdev/KfM/Common/Documentation/faq-osx.html">Kerberos
	64	on Mac OS X Frequently Asked Questions</A></LI>
	65
	66	</UL>
	67
	68	<P>The Linux Documentation Project also has a HOWTO on Kerberos:</P>
	69
	70	<UL>
	71
	72	<LI><A HREF="http://tldp.org/HOWTO/html_single/Kerberos-Infrastructure-HOWTO/">Kerberos
	73	Infrastructure HOWTO</A></LI>
	74
	75	</UL>
	76
	77
	78	<H2 CLASS="title"><A NAME="CUPS">Configuring CUPS to Use Kerberos</A></H2>
	79
	80	<P>Once you have configured Kerberos on your system(s), you can then
	81	enable Kerberos authentication by selecting the <tt>Negotiate</tt>
	82	authentication type. The simplest way to do this is using the
	83	<tt>cupsctl(8)</tt> command:</P>
	84
	85	<PRE CLASS="command">
	86	<KBD>cupsctl DefaultAuthType=Negotiate</KBD>
	87	</PRE>
	88
	89	<P>You can also enable Kerberos from the web interface by checking the
	90	<VAR>Use Kerberos Authentication</VAR> box and clicking <VAR>Change
	91	Settings</VAR>:</P>
	92
	93	<PRE CLASS="command">
	94	http://localhost:631/admin
	95	</PRE>
	96
749b1e90 MS	97	<P>After you have enabled Kerberos authentication, use the built-in
	98	"authenticated" policy or your own custom policies with the printers you
	99	will be sharing. See <a href="policies.html">Managing Operation Policies</a>
	100	for more information.</P>
355e94dc MS	101
	102
	103	<H2 CLASS="title"><A NAME="IMPLEMENT">Implementation Information</A></H2>
	104
749b1e90 MS	105	<P>CUPS implements Kerberos over HTTP using GSSAPI and the service name
	106	"ipp". Because of limitations in the HTTP GSSAPI protocol extension, only
	107	a single domain/KDC is supported for authentication.</P>
	108
	109	<P>When doing printing tasks that require authentication, CUPS requests a
	110	single-use "ticket" from your login session to authenticate who you are.
	111	This ticket gives CUPS a username of the form "user@REALM", which is then
	112	converted to just "user" for purposes of user and group checks.</P>
	113
	114	<P>In order to support printing to a shared printer, CUPS has to ask the KDC
	115	for a copy of your credentials (this is called delegation) that can be sent to
	116	the remote server for authenticatation. Delegation only works when the system
	117	has a stable hostname which maps to the current address of the system, which
	118	is why you need a static IP address or DHCP that updates the DNS entry for your
	119	system.</P>
355e94dc MS	120
	121	</BODY>
	122	</HTML>