Administrator's Guide - Authentication
Contents
Overview
Authentication to connect to Variations can be done in a number of ways. Client connections are made by sending the username and password (DES encrypted) gathered from the user to Variations in order to do a proxy login using one of the supported protocols. Administrator and cron connections done on the server can use a special login that does not prompt for a password.
Supported Authentication Protocols
- System Login Using SSH - this is an easy one to start with during initial system testing
- Active Directory (through Kerberos)
- Central Authentication Server (CAS)
- IMAP
- Java Authentication and Authorization Service (JAAS)
- Kerberos (using JAAS)
- LDAP
- Pam (using JPam See Pam Authentication through JPam)
- POP3
Server Configuration
Configuring authentication schemes, requires only a few lines in dmlserver.xml. Each scheme consists of a protocol, realm, and configuration. Each supported scheme has an AuthenticationScheme tag that must have a protocol attribute and optionally can have a reportedhostname, label, and hidden attributes. The content of the AuthenticationScheme tag is the realm (or hostname) of the authentication system used by the scheme. Note that the realm is case sensitive.
Attribute | Required | Example Value | Description |
---|---|---|---|
protocol | required | jaas | One of the supported authentication protocols (cas, imap, jaas, krb, ldap, pam, pop, ssh) |
reportedhostname | optional | example.edu | The reportedhostname attribute is a string that will replace the realm to form the Variations username (username@realm) |
label | optional | Example Campus | The optional label attribute should be a human readable string that will be passed to clients to aid users in selecting between available realms when more than one is present |
hidden | optional | true|false | The hidden attribute is a boolean flag indicating whether this method should be available to end users or not. Setting this to true can be useful for testing new authentication methods without confusing end users. Defaults to false. |
System Login Using SSH
The hostname specified as the content of the AuthenticationScheme tag is the host that the SSH login will be attempted against, such as your Variations server system. No additional attributes are specifically needed for SSH configuration.
CAS
The CAS authentiation is performed by requesting and submitting the CAS login form on behalf of the user. This is an inherently site specific operation and is prone to errors whenever the CAS login webpage changes. Usage of CAS for Variations authentication is discouraged. If attempting to use CAS, you will need to modify CASLoginProxy.java, build a new casproxy.jar, and put it in the lib directory on your Variations server.
Attribute | Required | Example Value | Description |
---|---|---|---|
loginurl | required | loginurl is a url prefix string that is appended to forming a valid CAS login url |
IMAP
Attribute | Required | Example Value | Description |
---|---|---|---|
port | required | 993 | The port the IMAP server is running on |
useSSL | optional | true|false | Use SSL when talking with the IMAP server. Defaults to false. |
JAAS
Attribute | Required | Example Value | Description |
---|---|---|---|
loginContext | true | VariationsKerberosContextPasswordAuth | The name of a JAAS context defined in conf/server/jaas.config |
Kerberos
Besides configuring the AuthenticationScheme element in dmlserver.xml and checking the JAAS context in jaas.config, krb5.conf needs to be modified to use your institution's Kerberos system. Kerberos can be used to connect to Microsoft Active Directory. If using Active Directory, make sure that the AuthenticationScheme realm matches a realm in your krb5.conf and is uppercase. While the Kerberos authentication is performed using JAAS inside Variations, the AuthenticationScheme protocol should be set to krb instead of jaas because extra handling is done to prepare the user credentials.
Attribute | Required | Example Value | Description |
---|---|---|---|
loginContext | true | VariationsKerberosContextPasswordAuth | The name of a JAAS context defined in conf/server/jaas.config |
LDAP
Attribute | Required | Example Value | Description |
---|---|---|---|
port | optional | 389 | The port the LDAP server is running on |
encryptionMethod | optional | simple|none|<list of SASL mechanisms> | Authentication method to use when attempting to bind to the LDAP server. See http://java.sun.com/docs/books/tutorial/jndi/ldap/auth_mechs.html for more information. Defaults to simple. |
principalFormat | optional | ads/{0} | principalFormat allows formating of the username principal sent to the LDAP server. The default {0} send the username as entered by the user. |
useSSL | optional | true|false | Use SSL when talking with the LDAP server. Defaults to false. |
PAM
Attribute | Required | Example Value | Description |
---|---|---|---|
pamConfig | required | variations | Name of the PAM config file in /etc/pam.d to be used |
POP
Attribute | Required | Example Value | Description |
---|---|---|---|
port | required | 110 | The port the POP server is running on |
prefix | optional | mail.imap | Property name prefix to be used if additional configuration is need. See the JavaMail API for more details. Defaults to the empty string. |
useSSL | optional | true|false | Use SSL when talking with the POP server. Defaults to false. |
Example Authentication Configurations
<AuthenticationSchemes> <AuthenticationScheme protocol="cas" loginurl="https://cas.iu.edu/cas/login?cassvc=DMLP"> iu.edu </AuthenticationScheme> <AuthenticationScheme protocol="imap" reportedhostname ="example.edu" port="993" useSSL="true"> imap.example.edu </AuthenticationScheme> <AuthenticationScheme protocol="krb" reportedhostname="example.edu" loginContext="VariationsKerberosContextPasswordAuth"> AD.EXAMPLE.EDU </AuthenticationScheme> <AuthenticationScheme protocol="ldap" reportedhostname="example.edu" encryptionMethod="None" port=636 useSSL="true" principalFormat="ads\{0}"> ldap.example.edu </AuthenticationScheme> <AuthenticationScheme protocol="pam" pamConfig="variations" hidden="true"> example.edu </AuthenticationScheme> <AuthenticationScheme protocol="pop" label="POP" port="110" useSSL="false"> pop.example.edu </AuthenticationScheme> <AuthenticationScheme protocol="ssh" reportedhostname="example.edu"> example.example.edu </AuthenticationScheme> </AuthenticationSchemes>
Client Configuration
Clients pull available authentication methods from the server. Client connections can bypass authentication if their session is still active and a cookie is present on the client's machine. For this functionality, the dml.login.useCookie property must be set to try in their dml.conf.
dml.login.useCookie=true
An example of a situation where you might want to set useCookie=false is for a set of machines in a computer lab where users typically share a login. Setting useCookie=false will mean that if a user exits Variations, the next user to run Variations on the computer will have to reauthenticate, keeping users from stepping on each other's bookmarks.