/ 
Catalyst-Authentication-Credential-GSSAPI-v0.0.5
River stage zero No dependents
/ Catalyst::Authentication::Credential::GSSAPI

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 serviceaccount@MYREALM.MYDOMAIN.COM
 3 HTTP/myservice.mydomain.com@MYREALM.MYDOMAIN.COM

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.