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

Kerberos is generally distrustful of any underlying network security, although it does need to trust its own network elements - chiefly the parts of the Kerberos Key Distribution Centre (we'll refer to it as the KDC from this point).

As a result of its distrust, Kerberos never sends credentials across the network. It assumes that someone is packet-sniffing with the aim of stealing credentials. It therefore ensures that credentials are stored only in a single secure location (the Kerberos Key Distribution Center). So credentials are never stored on the user's host. Once the initial authentication exchange takes place the password must be discarded by that host.

Application hosts/servers must be able to prove their identity to anyone requesting such proof.

All communication between authenticated users (clients) and application services must be capable of being encrypted. Various bulk cipher algorithms (all-symmetric) are supported and may be negotiated.

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

Start Firefox. In the Address line, enter "about:config"

Navigate to the property "network.negotiate-auth.delegation-uris", double click it and enter in the Kerberos domain.

"network.negotiate-auth.trusted-uris" is updated in the same way.

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

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

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.