Understanding Drupal's session management and user authentication

Question

I have a requirement to replace the default user authentication with the authentication of a central server, i.e., the SSO server.
By debugging Drupal, I learned that all the session management happens in the includes/session.inc file. I want to do authentication as shown in the image:

SCENARIO: Login
The details of the steps would be as follows:

1. Replace the login form to submit the username and password to the SSO server (not on Drupal, but on .NET).
2. Authenticate the user on the SSO server using that site's database, and send a response back to some custom PHP page of my website (or a form by a module?).
3. Using the response, identify the user in the users table, and create a session for that user without checking for the password (as it would mean double authentication). By default, Drupal sets a cookie with the name of the $insecure_session_name variable and the value $sid. I want Drupal not to set the cookie here but instead send the values of variables to the SSO server.
4. The SSO server will take the values, create a cookie, and drop it in the domain domain.com (to remind both my website and sso server are on the subdomain of the main domain, which is not in Drupal). Then, the drupal site can log in by using that cookie.

I know it is a tough ask, but I am just looking for pointers on how to start. as they say, "you should not hack the core". So, my questions are:

1. Where should I look to understand how Drupal authentication and session management works in depth?
2. Is there a way I could call the functions in includes/session.inc using hooks (as the comments with functions say "for internal use only/not to be modified")?

NOTE: I'll be using the same method to register the user so that the record remains in the central database of the SSO server. And during that will put in some junk password for the same user in the Drupal site's database (as the password will not be checked during login).

Answer 1

Drupal supports external authentication. There are many alternatives authentication modules for Drupal, such as OpenID (included in core), OAuth Connector, or LDAP. Learn more about how Drupal authentication works; the best would be to look at the OpenID and OAuth modules, and to the core login form submit callback. But, AFAIK, they always start the normal Drupal session after a successful authentication.

For session management, Drupal plugs into PHP session handling and register it own handlers. The Drupal session backend is itself pluggable, you can set the session_inc variable to the path of a file providing alternative implementations of the functions found in includes/session.inc. The memcache module use this to store session in memcached.

For references, the OpenID module handle successful authentication in openid_authentication() which itself ceats and call the user login form submit handler (ie. user_login_submit()). This submit handler itself is simple, it loads the successfully authenticated user with user_load() into the global $user variable, it then call user_login_finalize() which handle session, login timestamp in the user table and invoke hook_user_login() implementations.

Another option is the use the user_external_login_register() function. The function will log an external user in. It also creates a local user if needed. If you need more control on local user creation, you can always use user_save(), user_set_authmaps(), user_login_submit() and user_external_load() from you custom call, using user_external_login_register() as template of what needs to be done.

Answer 2

user_authenticate() APi might come in handy here.

3.Using the response, identify the user in the users table, and create a session for that user without checking for the password (as it would mean double authentication). By default, Drupal sets a cookie with name of $insecure_session_name variable, and with value $sid. I want Drupal not to set the cookie here, instead send the values of variables to SSO server.

EDIT : Once SSO server returns with true use this API to login the user which will automatically take care of sessions for you. I think its better if you use user_authenticate() instead of creating sessions by yourself. It shouldnt make a problem even its a double authentication as long as valid p-assowrd is provided.

Am not sure of 4. Do you want the cookie to be visible in both domains ? If so then in settings.php initialize $cookie_domain to the domain. Then cookies in subsite will be available in parent site.