Authentication and Authorization
================================

The use of Cyrus IMAP may have a significant impact on the design, use and load of the current authentication and authorization infrastructure. In addition, authentication and authorization relates to both to security, and also, in the particular case of Cyrus IMAP, personal privacy.

Typically, an authentication and authorization database, such as for example LDAP, is already available and in use within an infrastructure. Cyrus IMAP would integrate with a variety of technologies, but a few considerations deserve outlining.

For example, when a user wants to set group permissions on an IMAP folder, the most intuitive attribute in LDAP to refer to the group is the Common Name (CN). This attribute however is not guaranteed to be unique. Uniqueness can be enforced within LDAP, although that may be too restrictive, and so the groups available in Cyrus IMAP can be limited to scope one, while the cn is used in the rdn (the cn is the naming attribute to compose the dn with); effectively enforcing uniqueness for those groups available to Cyrus IMAP.

Similarly, many deployments choose to use the mail LDAP attribute value as the mailbox name, while mail is a multi-valued attribute and is not configured to be enforced globally unique in the LDAP information tree under the root dn. In addition, attributes such as amilAlternateAddress and/or alias could potentially hold the same value as anyone's mail attribute. These limitations or such implications become very clear when canonification of the authentication ID to the desired authorization ID is attempted.

For example, if <literal>jdoe</literal> is the login username, and Cyrus IMAP has a default realm configured <literal>example.org</literal>, the authentication ID becomes <literal>jdoe@example.org</literal>. It is this authentication ID, and not the supplied login username, that Cyrus IMAP uses to verify the credentials.

Cyrus IMAP thereafter allows authorization mechanisms, such as <emphasis>ptclient</emphasis> modules, to canonify the authentication ID to then ultimately return the authorization ID.

Suppose in the case of <literal>jdoe@example.org</literal>, where the authentication ID had been set, an LDAP module for ptloader could search LDAP for a <literal>uid=%U</literal> (where %U is the local part of the authentication ID), find the mail attribute value is <literal>john.doe@example.org</literal>, and authorize the user as such. Effectively, this enables Cyrus IMAP users to log in both with their username (uid) as well as their email address (or any of the aliases).

The process of client authentication and authorization


Client Authentication
---------------------

The exchange and verification of identity information provided by a client, otherwise known as *the process of authentication*, provides a set of credentials that allow the server to verify that the user is in fact the user, and not an imposter.

.. important::
    **Authentication != Authorization**

    Authentication and authorization are two separate processes. Authentication is about verifying the credentials supplied by the client, while authorization is the process of determining what rights the client has. Authentication, logically, preseeds authorization.

The most common set of credentials is a *username* and *password*, but other forms exist like Kerberos v5 ticket exchange (for which, to obtain such, most often a password is supplied), or certificate based authentication (the secret keys for which are most often locked with a passphrase). In any case, authentication works based on a shared secret, and/or a trusted source for verification. Kerberos v5 works based on shared secrets (keytab), and certificate based authentication works based on shared, trusted sources for verification.

In the case of usernames and passwords though, the exchange and verification of the credentials is at the basis of its security. Sending plain text usernames and passwords over the wire would not allow any application to verify the source of the credentials is actually the user &ndash;who is supposed to be the only party to know the unique combination of username and password.

To obfuscate the login credentials, authentication can be encrypted with CRAM-MD5 or DIGEST-MD5, but this requires the server to have a copy of the original, plain text password. The password in this case becomes the shared secret.

Another method is to allow the plain text username and password to be transmitted over the wire, but ensure Transport Layer Security (TLS) or the more implicit Secure Socket Layer (SSL). The plain text password can now be used to compare it against a SQL database, bind to an LDAP database, attempt PAM authentication with, etc.

Users and Mailboxes
-------------------

User mailboxes have a globally unique identifier which is not necessarily the same as the login name used. There are three distinguishable aspects to a user's entity and the mailbox associated with it;

The **user login credentials** that are associated with the user authentication entity and verify the user is who the user claims to be.

For example, the user logs in with username <code>john.doe@example.org</code> and password <code>verysecret</code>.

The **user's authentication entity** - with all attributes associated with it - can have one of those attributes be used to create the relationship between the user authentication entity on the one side, and the mailbox entity on the other side.

For example, the user that authenticated as <code>john.doe@example.org</code> may have a mailbox named <code>jdoe</code>.

The **authorization entity**, used to assign certain permissions to the user, uses the same attribute used to determine the mailbox name.

For example, the user that authenticated as <code>john.doe@example.com</code> and has mailbox <code>jdoe</code> needs an access control list entry on that mailbox that assigns <code>jdoe</code> certain rights on said mailbox.

