rogergee / php-uniauth Goto Github PK
View Code? Open in Web Editor NEWA PHP extension implementing universal user authentication session management
A PHP extension implementing universal user authentication session management
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 <[email protected]> -------------------------------------------------------------------------------- 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!
A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.