1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203
|
Installation Instructions for SPNEGO
Introduction
The WebLogin front-end for user authentication can optionally support
SPNEGO for browsers that support it, with fallback to the standard
username/password authentication. SPNEGO is the Microsoft protocol for
doing GSSAPI authentication (or NTLMv2 authentication, but that's less
interesting) over HTTP. It is supported by, at least, IE on PC, Firefox
on all platforms, and Safari on Mac, and probably by other browsers.
Before trying this configuration, set up a basic WebKDC and WebLogin
server as described in install-webkdc and make sure that's working
first.
These instructions assume that you're using mod_auth_kerb to do the
SPNEGO negotiation. Something similar will almost certainly work with
mod_gssapi, but I've not tested it myself and the exact name of the
configuration options will probably require changes.
Configuration
To use SPNEGO, you need to have two login URLs on your WebLogin server
rather than just one (traditionally /login). The following instructions
assume that you are using /login as the URL to try SPNEGO first and
/login-simple for the password fallback. This also allows clients that
don't want to use SPNEGO to point their WebAuthLoginURL directly to the
/login-simple version.
Set up an additional ScriptAlias for /login-simple that points to the
login.fcgi script. So, for instance, if you currently have:
ScriptAlias /login "webkdc/login.fcgi"
also add:
ScriptAlias /login-simple "webkdc/login.fcgi"
Then, add the following Apache configuration block to protect the
regular /login URL with SPNEGO:
<Location "/login">
AuthType Kerberos
require valid-user
KrbMethodNegotiate on
KrbMethodK5Passwd off
Krb5Keytab /etc/apache2/keytab
ErrorDocument 401 /login-simple
</Location>
Obviously, change the keytab path to something that makes sense on your
system.
Create a principal in Kerberos called HTTP/weblogin.example.com, where
weblogin.example.com is the name of the system that will be used in the
WebAuthLoginURL directives for your WebAuth application servers. Store
the key for that principal in the keytab configured above. Some
browsers use the name in the URL to construct the principal name and
others use the reverse DNS lookup of the IP address to which they're
connecting. You may want to patch mod_auth_kerb to support the
KrbServiceName Any option and then put both principals in the keytab
(the Debian libapache2-mod-auth-kerb package already has this patch
applied). The HTTP must be in all caps. For information on how to get
a Kerberos principal created and how to download a keytab, contact your
local Kerberos administrator.
Finally, edit /etc/webkdc/webkdc.conf or wherever your webkdc.conf file
is located (creating it if it doesn't already exist) and put, in it:
$REMUSER_ENABLED = 1;
$REMUSER_EXPIRES = 60 * 60 * 8;
The first line tells the WebLogin script to trust REMOTE_USER as set by
Apache if present (so make sure that there isn't a way of accessing the
script via an Apache authentication mechanism that you don't trust!).
The second line says how good authentication via REMOTE_USER should be
valid for (see Notes and Cautions below).
By default, whatever appears in REMOTE_USER will be expressed as the
authenticated identity, and any user allowed to authenticate by your
Kerberos administrative policies (such as cross-realm trust) will be
able to authenticate to WebLogin. To change that behavior, you can use
the following settings:
@REMUSER_PERMITTED_REALMS = ("EXAMPLE.COM");
@REMUSER_LOCAL_REALMS = ("EXAMPLE.COM");
The first setting lists the realms that are permitted to authenticate.
If you are happy to allow any realm with which you have cross-realm
trust, you can omit this. This is roughly equivalent to the
WebKdcPermittedRealms setting in mod_webkdc.
The second setting lists the realms that will be stripped off of the
authenticated identity before being passed to WebAuth Application
Servers. Depending on local practice, this may be set to your local
default realm or left unset. This is roughly equivalent to the
WebKdcLocalRealms setting in mod_webkdc.
You will also need to set $KEYRING_PATH if your WebKDC keyring is not
located in ../conf/webkdc/keyring relative to your server root. For
example, if you are using the Debian or Ubuntu packages, you will need:
$KEYRING_PATH = "/var/lib/webkdc/keyring";
Now, when the user hits /login with a browser, the server will attempt
to do an SPNEGO authentication. If the browser supports it, that
authentication information will be passed on to the WebLogin script in
REMOTE_USER and it will cobble up a temporary webkdc-proxy token for the
WebKDC. If the remote system did not request a Kerberos authenticator
or any additional credentials and only needs simple authentication, this
will bypass the login prompt. If it does need additional information,
the user will get the login screen anyway.
If the SPNEGO authentication fails, /login-simple will be run as the
error handler. It understands how to extract the WebAuth information
out of the environment and present the regular login page. The user's
browser will see the login page as the content of a 401 error, but the
browser should handle this correctly. Further interactions will
continue on the /login-simple URL, bypassing SPNEGO.
Configuration with Delegation
The above uses only Kerberos authentication. You can also optionally
support ticket delegation for browsers that support delegation over
SPNEGO. (Normally, this requires additional browser-specific security
configuration to enable.) To enable that support, add:
KrbSaveCredentials on
to the configuration for /login described above and add:
$WEBKDC_PRINCIPAL = "service/webkdc";
to /etc/webkdc/webkdc.conf or wherever your webkdc.conf file is
located, where the value is whatever principal you use for your WebKDC
(the same value that you use for WebAuthWebKdcPrincipal). You will also
need to configure REMOTE_USER support as described above. Now, if the
browser delegates credentials, those credentials will be used to create
a proxy token for the WebKDC and the WebKDC will be able to support
requests for additional credentials without needing to prompt the user
for their password.
If you enable this support, make sure that KRB5CCNAME is not set in the
environment of your Apache process except by mod_auth_kerb, since the
WebLogin script uses that environment variable to locate the ticket
cache to use.
Notes and Cautions
If the user is successfully authenticated with SPNEGO, the WebLogin
server will not set a single sign-on cookie the way that it normally
does with password authentication. Instead, the next time that the user
is redirected to the WebLogin server, the SPNEGO authentication will be
repeated. That way, their general WebAuth authentication won't outlast
their Kerberos tickets.
However, there is currently no way of extracting from mod_auth_kerb the
expiration date of the ticket used to authenticate, so the unless the
user delegates credentials, the authentication tokens created by the
WebKDC will be valid for whatever period is defined in $REMUSER_EXPIRES
in webkdc.conf even if the user's Kerberos credentials are about to
expire. This may be improved later by adding a way to export the
expiration time of the ticket from mod_auth_kerb to somewhere the
WebLogin script can see it.
Implementation Details
Under the hood, if the WebLogin script sees $REMUSER_ENABLED is set and
finds REMOTE_USER in the environment, it checks to see if KRB5CCNAME is
set. If it is, and $WEBKDC_PRINCIPAL is set in the configuration file,
it uses the provided ticket cache to request a proxy token from the
WebKDC. That proxy token is then added to the WebKDC login request as
if it came from a browser's cookies.
If KRB5CCNAME or $WEBKDC_PRINCIPAL is not set, there are no delegated
credentials. In this case, the WebLogin script creates a webkdc-proxy
token using the WebKDC keyring, with a proxy subject of
"WEBKDC:remuser". It then passes that webkdc-proxy token in to the
WebKDC in an initial request and sees if it gets back the desired tokens
based on the strength of that webkdc-proxy token. If it does, it
proceeds to the confirmation screen; if not, it presents the login form
as normal.
The special prefix "WEBKDC:" in a webkdc-proxy token is used to
represent single sign-on tokens, so this is a webkdc-proxy token of type
remuser instead of the normal krb5. Since it does not contain a TGT or
any other useful credential, it cannot be used to fulfill requests for
credentials or id tokens with krb5 authenticators; servers that request
such things will force a username/password authentication if the user
doesn't have a single sign-on cookie.
This webkdc-proxy token is never stored in a cookie, to force
reauthentication with SPNEGO on each visit.
License
Copyright 2006, 2008, 2009
The Board of Trustees of the Leland Stanford Junior University
Copying and distribution of this file, with or without modification, are
permitted in any medium without royalty provided the copyright notice
and this notice are preserved. This file is offered as-is, without any
warranty.
|