oysteikt/heimdal
0
0
Fork 0
Code Issues 5 Pull Requests Releases Activity

Rewrite the transit policy section

Browse Source 
Expand the transit policy section considerably, with additional
examples and explanation of the examples.  Separate allowing
cross-realm transits from configuring clients to do cross-realm
transits.  Add a separate example section for an Active Directory
forest.

Signed-off-by: Love Hornquist Astrand <lha@h5l.org>
This commit is contained in:
Russ Allbery
2010-06-10 18:57:36 -07:00
committed by Love Hornquist Astrand
parent dfd107c709
commit cd1f1dd75e
1 changed files with 123 additions and 17 deletions
Download Patch File Download Diff File Expand all files Collapse all files

140
doc/setup.texi
View File

@@ -758,17 +758,36 @@ May 3 14:10:54 May 3 23:55:54 host/hummel.it.su.se@@SU.SE
@section Transit policy @section Transit policy
@cindex Transit policy @cindex Transit policy
If you want to use cross realm authentication through an intermediate Under some circumstances, you may not wish to set up direct
realm, it must be explicitly allowed by either the KDCs or the server cross-realm trust with every realm to which you wish to authenticate
receiving the request. This is done in @file{krb5.conf} in the or from which you wish to accept authentications. Kerberos supports
multi-hop cross-realm trust where a client principal in realm A
authenticates to a service in realm C through a realm B with which
both A and C have cross-realm trust relationships. In this situation,
A and C need not set up cross-realm principals between each other.
If you want to use cross-realm authentication through an intermediate
realm, it must be explicitly allowed by either the KDCs for the realm
to which the client is authenticating (in this case, realm C), or the
server receiving the request. This is done in @file{krb5.conf} in the
@code{[capaths]} section. @code{[capaths]} section.
In addition, the client in realm A need to be configured to know how
to reach realm C via realm B. This can be done either on the client or
via KDC configuration in the KDC for realm A.
@subsection Allowing cross-realm transits
When the ticket transits through a realm to another realm, the When the ticket transits through a realm to another realm, the
destination realm adds its peer to the "transited-realms" field in the destination realm adds its peer to the "transited-realms" field in the
ticket. The field is unordered, since there is no way to know if ticket. The field is unordered, since there is no way to know if know
know if one of the transited-realms changed the order of the list. if one of the transited-realms changed the order of the list. For the
authentication to be accepted by the final destination realm, all of
the transited realms must be listed as trusted in the @code{[capaths]}
configuration, either in the KDC for the destination realm or on the
server receiving the authentication.
The syntax for @code{[capaths]} section: The syntax for @code{[capaths]} section is:
@example @example
[capaths] [capaths]
@@ -777,11 +796,15 @@ The syntax for @code{[capaths]} section:
@} @}
@end example @end example
The realm @code{STACKEN.KTH.SE} allows clients from @code{SU.SE} and In the following example, the realm @code{STACKEN.KTH.SE} only has
@code{DSV.SU.SE} to cross it. Since @code{STACKEN.KTH.SE} only has direct cross-realm set up with @code{KTH.SE}. @code{KTH.SE} has
direct cross realm setup with @code{KTH.SE}, and @code{DSV.SU.SE} only direct cross-realm set up with @code{STACKEN.KTH.SE} and @code{SU.SE}.
has direct cross realm setup with @code{SU.SE} they need to use both @code{DSV.SU.SE} only has direct cross-realm set up with @code{SU.SE}.
@code{SU.SE} and @code{KTH.SE} as transit realms. The goal is to allow principals in the @code{DSV.SU.SE} or
@code{SU.SE} realms to authenticate to services in
@code{STACKEN.KTH.SE}. This is done with the following
@code{[capaths]} entry on either the server accepting authentication
or on the KDC for @code{STACKEN.KTH.SE}.
@example @example
[capaths] [capaths]
@@ -791,17 +814,100 @@ has direct cross realm setup with @code{SU.SE} they need to use both
DSV.SU.SE = @{ DSV.SU.SE = @{
STACKEN.KTH.SE = SU.SE KTH.SE STACKEN.KTH.SE = SU.SE KTH.SE
@} @}
@end example @end example
The first entry allows cross-realm authentication from clients in
@code{SU.SE} transiting through @code{KTH.SE} to
@code{STACKEN.KTH.SE}. The second entry allows cross-realm
authentication from clients in @code{DSV.SU.SE} transiting through
both @code{SU.SE} and @code{KTH.SE} to @code{STACKEN.KTH.SE}.
Be careful of which realm goes where; it's easy to put realms in the
wrong place. The block is tagged with the client realm (the realm of
the principal authenticating), and the realm before the equal sign is
the final destination realm: the realm to which the client is
authenticating. After the equal sign go all the realms that the
client transits through.
The order of the @code{PERMITTED-CROSS-REALMS} is not important when The order of the @code{PERMITTED-CROSS-REALMS} is not important when
doing transit cross realm verification. doing transit cross realm verification.
However, the order is important when the @code{[capaths]} section is used @subsection Configuring client cross-realm transits
to figure out the intermediate realm to go to when doing multi-realm
transit. When figuring out the next realm, the first realm of the list The @code{[capaths]} section is also used for another purpose: to tell
of @code{PERMITTED-CROSS-REALMS} is chosen. This is done in both the clients which realm to transit through to reach a realm with which
client kerberos library and the KDC. their local realm does not have cross-realm trust. This can be done
by either putting a @code{[capaths]} entry in the configuration of the
client or by putting the entry in the configuration of the KDC for the
client's local realm. In the latter case, the KDC will then hand back
a referral to the client when the client requests a cross-realm ticket
to the destination realm, telling the client to try to go through an
intermediate realm.
For client configuration, the order of @code{PERMITTED-CROSS-REALMS}
is significant, since only the first realm in this section (after the
equal sign) is used by the client.
For example, again consider the @code{[capaths]} entry above for the
case of a client in the @code{SU.SE} realm, and assume that the client
or the @code{SU.SE} KDC has that @code{[capaths]} entry. If the
client attempts to authenticate to a service in the
@code{STACKEN.KTH.SE} realm, that entry says to first authenticate
cross-realm to the @code{KTH.SE} realm (the first realm listed in the
@code{PERMITTED-CROSS-REALMS} section), and then from there to
@code{STACKEN.KTH.SE}.
Each entry in @code{[capaths]} can only give the next hop, since only
the first realm in @code{PERMITTED-CROSS-REALMS} is used. If, for
instance, a client in @code{DSV.SU.SE} had a @code{[capaths]}
configuration as above but without the first block for @code{SU.SE},
they would not be able to reach @code{STACKEN.KTH.SE}. They would get
as far as @code{SU.SE} based on the @code{DSV.SU.SE} entry in
@code{[capaths]} and then attempt to go directly from there to
@code{STACKEN.KTH.SE} and get stuck (unless, of course, the
@code{SU.SE} KDC had the additional entry required to tell the client
to go through @code{KTH.SE}).
@subsection Active Directory forest example
One common place where a @code{[capaths]} configuration is desirable
is with Windows Active Directory forests. One common Active Directory
configuration is to have one top-level Active Directory realm but then
divide systems, services, and users into child realms (perhaps based
on organizational unit). One generally establishes cross-realm trust
only with the top-level realm, and then uses transit policy to permit
authentications to and from the child realms.
For example, suppose an organization has a Heimdal realm
@code{EXAMPLE.COM}, a Windows Active Directory realm
@code{WIN.EXAMPLE.COM}, and then child Active Directory realms
@code{ENGR.WIN.EXAMPLE.COM} and @code{SALES.WIN.EXAMPLE.COM}. The
goal is to allow users in any of these realms to authenticate to
services in any of these realms. The @code{EXAMPLE.COM} KDC (and
possibly client) configuration should therefore contain a
@code{[capaths]} section as follows:
@example
[capaths]
ENGR.WIN.EXAMPLE.COM = @{
EXAMPLE.COM = WIN.EXAMPLE.COM
@}
SALES.WIN.EXAMPLE.COM = @{
EXAMPLE.COM = WIN.EXAMPLE.COM
@}
EXAMPLE.COM = @{
ENGR.WIN.EXAMPLE.COM = WIN.EXAMPLE.COM
SALES.WIN.EXAMPLE.COM = WIN.EXAMPLE.COM
@}
@end example
The first two blocks allow clients in the @code{ENGR.WIN.EXAMPLE.COM}
and @code{SALES.WIN.EXAMPLE.COM} realms to authenticate to services in
the @code{EXAMPLE.COM} realm. The third block tells the client (or
tells the KDC to tell the client via referrals) to transit through
@code{WIN.EXAMPLE.COM} to reach these realms. Both sides of the
configuration are needed for bi-directional transited cross-realm
authentication.
@c To test the cross realm configuration, use: @c To test the cross realm configuration, use:
@c kmumble transit-check client server transit-realms ... @c kmumble transit-check client server transit-realms ...