NAME
Catalyst::Authentication::Credential::GSSAPI - rfc4559 SPNEGO/GSSAPI
SYNOPSIS
In your application configuration:
<authentication>
default_realm "myrealm"
<realms>
<myrealm>
<credential>
class "GSSAPI"
</credential>
<store>
class "LDAP"
ldap_server "myrealm.mydomain.com"
binddn "anonymous"
bindpw "dontcarehow"
user_basedn "OU=Users,DC=myrealm,DC=mydomain,DC=com"
user_field "userprincipalname"
user_filter "(userprincipalname=%s)"
user_scope "sub"
</store>
</myrealm>
</realms>
</authentication>
On your application code:
$c->authenticate({ });
DESCRIPTION
This module implements the HTTP negotiation described in rfc4559. The
authentication is implemented by the natively calling the gssapi from
the krb5 library. It provides only the "Credential" part of the system.
You are required to plugin a different "Storage", such as LDAP, in order
to get the data for the user info.
This allows your application to perform Single-Sign-On (SSO) if you are
in an environment with Kerberos authentication. One example of such
scenario is for environments managed with Microsoft Active Directory.
This module will not, however, perform password-based authentication on
the Kerberos realm. It will only accept token-based negotiation with
GSSAPI.
Like Catalyst::Authentication::Credential::HTTP, this module will detach
your action for the HTTP negotiation to happen and will only return when
a valid user was authenticated and retrieved from the store.
KEYTABS AND PRINCIPALS
When implementing GSSAPI negotiation over HTTP, the convention specify
that the name of the principal for the service will always be:
HTTP/hostname.of.the.server
Such that if the client is connecting to
http://myservice.mydomain.com
the name of Service Principal Name (SPN) will be required to be
HTTP/myservice.mydomain.com
The SPN needs to be registered with the kerberos server, and application
needs to be run with a keytab that contains that principal. One way to
verify that is by doing:
$ k5srvutil -f mykeytabfile.keytab list
Keytab name: FILE:mykeytabfile.keyttab
KVNO Principal
---- --------------------------------------------------------------------
3
[email protected]
3 HTTP/
[email protected]
With the MIT krb5 library, you can use the keytab by exporting the
following environment variable for the process running the application:
export KRB5_KTNAME=FILE:/full/path/to/mykeytabfile.keytab
That way the application will be able to participate in the
authentication.
CLIENT SIDE
The client side, of course, also has to support this negotiation.
BROWSER SUPPORT
All major browsers support this negotiation, some configuration may be
required in order to enable it.
CURL
Curl can be built with krb5 support, at which point you should be able
to use:
curl --negotiate -u x:x
http://myservice.mydomain.com
The "-u x:x" argument is necessary in order to tell curl to enable
authentication, the user name and password will not be used and can be
set to a dummy value, like "x:x".
CONFIGURATION
username_field
This configures what field should the username be set to in the
authinfo hash. Defaults to "username".
The authentication will send the "src name" from gssapi as the user
name for the find_user call.
strip_realm
When using kerberos, the full principal name is returned, which is
usually in the form of user@REALM. Setting this will strip
everything after the '@' before sending it to the credential store.
This is useful if you are using a store that is not connected to the
kerberos authentication.
USING WITH LDAP ON MICROSOFT ACTIVE DIRECTORY
Active Directory offers the LDAP attribute "userprincipalname" that will
match the kerberos principal used by this API. If you set the user_field
and user_filter configurations of the LDAP store, it will seamlessly
integrate and return you a valid LDAP user.
COPYRIGHT
Copyright 2015 Bloomberg Finance L.P.
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
