php-uniauth - v1.1.1
--------------------------------------------------------------------------------
This PHP extension provides authentication session management via a uniauth
server. The extension implements an authentication flow designed to make user
authentication universal among applications talking to the same uniauth server.

The implementation consists of an extension that provides PHP userspace a
high-level interface for connecting with a uniauth server and manipulating
sessions.

Uniauth server implementations:

    *NOTE* The following implementation is used for this extension.

    Linux: https://git.rserver.us/network/uniauthd.git

Primary author:

    Roger Gee <rpg11a@acu.edu>

--------------------------------------------------------------------------------
The Uniauth Flow

Uniauth implements a user authentication flow for web applications. This flow
involves a persistent uniauth server and a stateless client. Whenever the client
needs to check user authentication, it connects to the server and queries a
session record by ID. Likewise, when the client needs to create and authenticate
a session, it uses the server to store and update the session information.

There are two roles in the flow taken by applications:

    1. applicant
    2. registrar

The applicant endpoint queries authentication status and, if none is found,
redirects to the registrar endpoint for registration, during which process
authentication occurs. The registrar then redirects the user-agent back to the
applicant, upon which event the applicant queries authentication status and
finds that it exists. This entire process happens transparently in the
applicant: the applicant does not have to handle both cases separately.

The registrar endpoint provides a means to collect user credentials and
authenticate users. Once the registrar has verified user credentials, it submits
the collected user ID and name (along with a display name) to the uniauth
server. The server assigns this information to an internal session, thus
registering the user as authenticated. Internally, this uniauth registration is
shared among all applications that use the registrar endpoint for the same user.

While the specifics of uniauth sessions may differ between server
implementations, the basic idea is that a single registration is maintained
among all applicants targeting the same registrar. The means that the server
internally connects the applicant and registrar sessions so that they point at
the same registration. This allows applicants from different domains
(i.e. having different session IDs) to utilize the same registration.

--------------------------------------------------------------------------------
Storage

A uniauth server maintains a database of authentication records that hold
information about the user session. Records are keyed by a session ID (sometimes
called a session key in this document). This ID may be provided by the userspace
script. If the userspace script does not provide a session ID, the PHP session
ID will be used as the uniauth session ID instead. (This means you must have
already called session_start() in your program).

    *NOTE* The extension does not actually manipulate the PHP session data
    itself if it uses the session ID. Instead it uses the configured session ID
    to key the uniauth records it creates with the server. This frees PHP
    userspace from having to track this information in its session. You can
    however still use the PHP session backend to store additional session
    values.

If a PHP session is not required, then a separate cookie can be used instead. To
avoid boilerplate associated with creating cookies and generating uniauth keys,
the uniauth_cookie() function is provided. This function generates a random
cookie session, overriding the default behavior of using the PHP session when
using the other extension functions. It also sets the cookie so it gets
transmitted to the user agent.

--------------------------------------------------------------------------------
PHP Userspace Functions Overview

Applicant Endpoint:

The core function used by applicants is uniauth(), which checks to see if a
registration exists for session (i.e. checks if the session is
authenticated). If not, it transparently redirects the user-agent to the
specified registrar endpoint. Otherwise, the function returns an associative
array containing the 'id', 'user' and 'display' records for the entry.

When an applicant redirects to a registrar, it passes the uniauth session ID via
a GET query parameter named 'uniauth'. This allows the registrar to identify the
target session that is to be associated with the registration should
authentication be successful.

Note: a uniauth session is considered authenticated by the standard when there
is a valid ID associated with the session (i.e. id >= 1).

A call to uniauth() is the minimum that is required for applicants. This call
will transparently begin the redirect flow.

Registrar Endpoint:

When calling a registrar endpoint, one of two things can happen.

1. There is no uniauth session for the registrar:

    In this case, a session must be created and authenticated. The registrar
    endpoint calls uniauth_apply() to begin this process. This function takes
    the query parameter passed from the applicant's call to uniauth() and stores
    it in a new uniauth session. It must set a cookie (possibly via
    uniauth_cookie()) or use the PHP session to track the new uniauth session.

    Now the registrar can present a login form or similar means to collect user
    credentials. When the credentials have been verified, the uniauth_register()
    function can be called with the correct information. This updates the
    registration associated with the registrar session. Once registration is
    complete, the registrar session is authenticated and ready to transfer.

    Finally, the uniauth_transfer() function is called to transfer the registrar
    session into the applicant session. Internally this updates the applicant
    session to point at the same registration as the registrar session. This
    function will automatically redirect the user-agent back to the original,
    applicant endpoint, thus "transferring" back to the original applicant
    endpoint.

2. There is already an authenticated uniauth session for the registrar:

    In this case the functionality should skip to calling uniauth_transfer().

    The uniauth_check() function is provided for the registrar endpoint so that
    it can check if an authenticated session exists. This should be done before
    calling uniauth_apply() in the former case. If 'true' is returned, then the
    registrar can skip to calling uniauth_transfer() (i.e. case #2 is true).

Logging Out:

To explictly invalidate a uniauth session, the uniauth_purge() API may be
employed. This function clears out the registration associated with the session
ID so the user login status is void. Note that this will log out all services
(i.e. applicants) that have sessions referencing the registration. The session
record is not technically freed until it expires naturally. This means the same
session IDs can be reused for future authentications until the user-agent drops
the cookie.

--------------------------------------------------------------------------------
PHP Userspace Functions Detail

    Generate notes:

        Unless a connection error occurs, all functions throw upon error. It is
        recommended that you wrap all uniauth calls in a try-catch block so as
        to report errors.

        Some functions have unusual side effects, such as setting superglobal
        values or cookies or aborting the script. Make sure you are aware of
        these.

    array uniauth([string $url, string $session_id])

        This function looks up an authenticated uniauth session.

        The function returns the session information as a login array if an
        authenticated session was found. If not, the function's behavior depends
        on whether an authentication endpoint url was specified:

            If an authentication endpoint url was specified, the function sends
            a redirect header pointing at the specified URL for the registrar
            endpoint. It then aborts the script.

            Otherwise (if url=null) the function just returns null, indicating
            that no authenticated session was available.

        The calling script has no awareness that a redirect occurred. Thus the
        redirect flow happens transparently.

        If the second parameter is specified, then the function uses the
        requested session ID. Otherwise, the current PHP session ID is used
        unless uniauth_cookie() was previously called.

            $url - The url of the registrar endpoint handling the
            authentication. This parameter may be null to avoid a redirect and
            just query the status of a uniauth session.

            $session_id - An override uniauth session ID to use in place of the
            default behavior.

        Return value: an array with the following keys pulled from the uniauth
        session:

            id - user tracking ID as determined by the registrar
            user - user handle as determined by the registrar
            display - user display name as determined by the registrar

        Returns mnull if no session was available and a redirect did not occur.

    bool uniauth_check([string $session_id])

        This function determines if an authenticated session exists. It does not
        update the session expiration.

            $session_id - Uniauth session ID to use (optional)

                The actual session ID used is determined in the same way as in
                the uniauth() function.

        Return value: true is returned if the specified session exists and is
        authenticated. False is returned if the specified session does not exist
        or exists but is not authenticated.

        NOTE: This function is largely obsolete in applicant implementations due
        to changes to the uniauth() function. Prefer calling uniauth(null) over
        using uniauth_check() when needing to conditionally obtain a session's
        login array.

            GOOD: $login = uniauth(null);

            BAD: if (uniauth_check()) $login = uniauth('http://auth.tld')
                 else $login = null;

    void uniauth_apply([string $session_id])

        This function creates a uniauth session for the registrar endpoint
        application (if it doesn't exist). The function annotates the new
        registrar session with the applicant session ID, which is passed in
        using a 'uniauth' query parameter in the request.

        This function should only be called in the initial GET request to the
        registrar endpoint. It must be called before any uniauth_transfer() call
        would succeed.

            $session_id - Uniauth session ID to use (optional)

                The actual session ID used is determined in the same way as in
                the uniauth() function.

        The session ID is determined in the same way as in the uniauth()
        function.

    void uniauth_register(int $id, string $name, string $display_name[, string $session_id, int $lifetime])

        This function is used to register (i.e. authenticate) a uniauth
        session. It assigns the specified user information into the
        current/specified uniauth session. After a successful call, the session
        is now authenticated.

            $id - Application-defined user ID for the session

            $name - Application-defined user name for the session

            $display_name - Application-defined user display name for the session

            $session_id - Uniauth session ID to use (optional)

                The actual session ID used is determined in the same way as in
                the uniauth() function.

            $lifetime - Defines the session lifetime starting from the current instant (optional)

                If this value is omitted or a non-positive number, then the
                uniauth session will have a lifetime equal to the value of the
                php.ini option "uniauth.lifetime" and the uniauth cookie (if
                any) is a persistent cookie. The default value for
                "uniauth.lifetime" is 86400, or 1 day; the value for this
                setting indicates the number of seconds for the lifetime.

                Otherwise the uniauth session has the specified lifetime and the
                uniauth cookie (if any) will be a session cookie.

    void uniauth_transfer([string $session_id])

        This function is used to transfer the information from one session
        (i.e. the source session) into another (i.e. the destination
        session). Internally this merely updates the destination session to
        point at the source session. Practically, the source session is the
        registrar session and the destination is the applicant session.

        The destination session ID is pulled from the source session. It was set
        previously in a call to uniauth_apply().

            $session_id - Uniauth session ID to use (optional)

                The actual session ID used is determined in the same way as in
                the uniauth() function.

        This function technically does not return and will bail out to perform the redirect. Otherwise it will throw an exception on failure.

    bool uniauth_purge([string $session_id])

        This functions ends the current uniauth session.

            $session_id - Uniauth session ID to use (optional)

                The actual session ID used is determined in the same way as in
                the uniauth() function.

        Note: this function merely invalidates the uniauth session. The session
        lifetime actually persists, which means the backend record can be reused
        in future authentication attempts within a certain amount of time. Any
        cookies used to track the session ID should also be preserved so as to
        avoid having to regenerate the session within a certain amount of time.

        Returns true if the session was valid and was invalidated, false
        otherwise.

    string uniauth_cookie()

        This is a convenience function used to eliminate boilerplate associated
        with when you want to use a simple cookie to track the session ID
        instead of the PHP session. This function will randomly generate a
        64-character ID and set it in a cookie with name="uniauth". If such a
        cookie already exists, it merely continues to use that session ID.

        Another vital behavior of this function is that it overrides the default
        behavior of most uniauth functions when determining the default session
        ID. Instead of using the PHP session by default, the functions' default
        behavior will be to use the uniauth cookie. For example:

            // This call will use the PHP session ID.
            session_start();
            uniauth("http://localhost/auth.php");

            // This call will use the generated uniauth cookie.
            uniauth_cookie();
            uniauth("http://localhost/auth.php");

        Return value: the function returns the session ID. Note that this value
        can also be grabbed from the $_COOKIE superglobal (without another
        request) since the function makes sure the cookie's value is set as part
        of its implementation.

        NOTE: using uniauth cookies will overwrite any existing cookies! You
        should always make uniauth calls before any other calls to set cookies!