WANdisco
 Navigation:  v | Release Notes | Install | Upgrade | Administration | Reference | API | Glossary | Archive

3. Guide to Keberos

Introduction

Kerberos is a network authentication system defined by RFC 4120. Further developments added negotiation capabilities (RFC 4537 and RFC 5021) and a new interface method, GSSAPI (or General Security System Application Program Interface) - which allows applications that are suitably configured to make calls to the Kerberos service.

Number 5
The Kerberos supported by SVN MultiSite Plus is Kerberos (krb5). Earlier versions, up to Kerberos 4 are significantly different from version 5 and are no longer under development.

Kerberos is now widely used throughout the world of enterprise-level LAN and WAN networking and continues to be a popular solution for Single Sign-on authentication.

Definitions

Authentication
The process used to verify that data or information asserting that it originates from a source can only have come from that source.

This implementation of Kerberos covers the authentication requirement.
Authorization
When a user has been authenticated they may or may not be authorized to access a system/network resources such as files, applications, the ability to send email, etc. The authentication process typically provides access to a set of records in a security database that will contain specific access information and/or additional access information based on the accounts membership of one or more groups.

This implementation of Kerberos SSO is intended only as a replacement for password checks. In a future release Kerberos will be married to SVN MultiSite Plus's internal or LDAP-driven admin user list.
Credentials
Any kind of password/key or security token. Your credentials are the objects that are accepted as proof of identity. Since you should be the only one who knows or has access to your credentials. When you present them to a system or network and they match the credentials that were securely recorded on an earlier date then it proves that you are who you say you are. As noted above, once authenticated you may still need to be authorized to be able to actually access specific resources.

What Kerberos brings to the table

Important Kerberos Terms

Principal
This is the string that fully identifies a user of the Kerberos service. The Principal can be the name of a service which runs on a host called a Service-Principal (user, or sometimes called a User-Principal) and forms an index to the information stored about the entity in the Key Distribution Center (KDC). The format of the Principal differs for users and services.

Form: HTTP/node1.example.com
Realm
Those users and application servers that are covered by a particular Key Distribution Center (KDC). For a user to login to a realm the realm's authentication server must have knowledge of the user's credentials (and other information) which is maintained in some form of secure database . In Microsoft's implementation this would be called a "Domain". Realms may trust other realms (in this case the peer realms will have cross-authenticated).

Form: <name>@REALM (case sensitive) e.g. BECKY@REALM (by convention it's recommended that these be stated in upper case)
Ticket
This is a data structure with content that is known only to its issuer and any party or parties to which the ticket applies. Intermediate hosts, (clients, etc) treat the tickets as generic lumps of data and simply pass them on to their destination. There are two types of tickets used by Kerberos; Ticket Granting Tickets (TGT) proving a successful authentication or Service Tickets (ST) - are issued by a Ticket Granting Service (TGS), enabling the user to access a desired Application Service.

Configure browsers for Kerberos authentication

Use the following procedures to ensure that your browser will support Kerberos authentication:

Chrome

Start Chrome with the following switch:

google-chrome --auth-server-whitelist="*host.com"

Firefox

network.negotiate-auth.trusted-uris
Sites that are permitted to engage in SPNEGO authentication with the browser.
network.negotiate-auth.delegation-uris
Sites for which the browser may delegate user authorization to the server.

Fall back

In the event that the Kerberos system fails, SVN MultiSite Plus will fall back to basic authentication using manual entered username and password.

Known issue after a fall back
After falling back to basic authentication the system will automatically attempt to log in using Kerberos, generating an error message:
Error logging in: Unable to validate SSO/Kerberos ticket. Try logging in.
Ignore this message, you can now login with a suitable admin credentials.
Keber-what?
Kerberos is a riff on Cerberus the 3-headed dog from ancient Greek mythology who guarded the entrance to the underworld. Rest assured that unlike its semi-namesake, Kerberos does not contain any exploits that allow entry through the use of drugged honeycakes.

Kerberos API Resources

The API now includes a number of Kerberos related end-points. You can review these on your node's local copy of the API documentation. For convenice a copy of this document is available here: KerberosConfigResources.

Enable/Disable SSO via API

While there's a UI toggle for enabling or disabling Kerberos SSO, you can also managed this via API calls:

Enable SSO

curl -X POST -H "Content-Type:application/x-www-form-urlencoded" -d "enable=true" 'http://192.168.56.190:8082/api/security/kerberos/enableSso' -u admin:pass
or
curl -X POST -H "Content-Type:application/x-www-form-urlencoded" 'http://192.168.56.190:8082/api/security/kerberos/enableSso?enable=true' -u admin:pass

Log Report

The following message will appear in the log:
[Single-sign-on with Kerberos was enabled by admin]

Disable SSO

curl -X POST -H "Content-Type:application/x-www-form-urlencoded" -d "enable=false" 'http://192.168.56.190:8082/api/security/kerberos/enableSso' -u admin:pass
or
curl -X POST -H "Content-Type:application/x-www-form-urlencoded" 'http://192.168.56.190:8082/api/security/kerberos/enableSso?enable=false -u admin:pass

Log Report

The following message will appear in the log:
[Single-sign-on with Kerberos was disabled by admin]

Warning message

The following error message will appear in the log file as a result of enabling SSO via the Admin UI. You can ignore it.

'WARN [WebComponent:filterFormParameters] - A servlet request, to the URI http://node1.vagrant.wan:8082/api/security/kerberos/enableSso, contains form parameters in the request body but the request body has been consumed by the servlet or a servlet filter accessing the request parameters. Only resource methods using @FormParam will work as expected. Resource methods consuming the request body by other means will not work as expected.'

This message is meant to warn developers about the fact that the request entity body has been consumed, thus any other attempts to read the message body will fail.