Now it's time to start phpMyAdmin and try connecting to it with the values we configured. This will test the following:

We start our browser and point it to the directory where we installed phpMyAdmin, as in http://www.mydomain.com/phpMyAdmin/. If this does not work, we try http://www.mydomain.com/phpMyAdmin/index.php. (This would mean that our web server is not configured to interpret index.php as the default starting document.)

If you still get an error, refer to the Appendix for troubleshooting and support. We should now see phpMyAdmin's home page. Chapter 3 gives an overview of the panels seen now.

This mode—http—is the traditional mode offered in HTTP, in which the browser asks for the username and password, sends them to phpMyAdmin, and keeps sending them until all the browser windows are closed.

To enable this mode, we simply use the following line:

$cfg['Servers'][$i]['auth_type'] = 'http';

We can also define the HTTP basic auth realm (http://en.wikipedia.org/wiki/Basic_access_authentication), which is a message to be displayed to the user at login time, via $cfg['Servers'][$i]['auth_http_realm']. This can help indicate the purpose of this server.

This mode has the following limitations:

The cookie authentication mode is superior to http in terms of the functionalities it offers. This mode permits true login and logout, and can be used with PHP running on any kind of web server. It presents a login panel (as shown in the following screenshot) from within phpMyAdmin. This can be customized as we have the application source code. However, as you may have guessed, for cookie authentication, the browser must accept cookies coming from the web server—but this is the case for all authentication modes anyway.

This mode stores the username typed in the login screen into a permanent cookie in our browser while the password is stored as a temporary cookie. In a multi-server configuration, the username and password corresponding to each server are stored separately. To protect the username and password secrecy against attack methods that target cookie content, they are encrypted using the Blowfish cipher. So, to use this mode, we have to define (once) in config.inc.php, a secret string that will be used to securely encrypt all passwords stored as cookies from this phpMyAdmin installation.

This string is set via the blowfish_secret directive:

$cfg['blowfish_secret'] = 'jgjgRUD875G%/*';

In the previous example, an arbitrary string of characters was used; this string can be very complex as nobody will ever need to type it on a login panel. If we fail to configure this directive, a random secret string is generated by phpMyAdmin but it will last only for the current working session. Therefore, some features such as recalling the previous username on the login panel won't be available.

Then, for each server-specific section, use the following:

$cfg['Servers'][$i]['auth_type'] = 'cookie';

The next time we start phpMyAdmin, we will see the login panel as shown in the following screenshot:

By default, phpMyAdmin displays (in the login panel) the last username for which a successful login was achieved for this particular server, as retrieved from the permanent cookie. If this behavior is not acceptable (someone else who logs in from the same workstation should not see the previous username), we can set the following parameter to FALSE:

$cfg['LoginCookieRecall'] = FALSE;

There is a security feature to add a specific time limit for the validity of a password. This feature helps to protect the working session. After a successful login, our password is stored (encrypted) in a cookie, along with a timer. Every action in phpMyAdmin resets the timer. If we stay inactive for a certain number of seconds, as defined in $cfg['LoginCookieValidity'], we are disconnected and have to log in again. Increasing this parameter does not work in all cases, because PHP's own session.gc_maxlifetime directive can get in the way. Please refer to http://php.net/manual/en/session.configuration.php for an explanation of this directive. Therefore, if phpMyAdmin detects that the value of session.gc_maxlifetime is less than the configured $cfg['LoginCookieValidity'], a warning is displayed on the main page. The default is 1440 seconds; this matches the php.ini's default value of the session.gc_maxlifetime parameter.

During the course of a working session, a user may encounter several requests to authenticate, from different web applications. The reason is these applications don't talk to each other and this situation inconveniences most users.

The signon mode enables us to use the credentials from another application to skip the authentication phase of phpMyAdmin. In order for this to work, this other application has to store the proper credentials into PHP's session data to be retrieved later by phpMyAdmin.

To enable this mode, we start with the following directive:

$cfg['Servers'][$i]['auth_type'] = 'signon';

Let us suppose that the authenticating application has used a session named FirstApp to store the credentials. We tell this to phpMyAdmin by adding the following line of code:

$cfg['Servers'][$i]['SignonSession'] = 'FirstApp';

We must take care of users that would try to access phpMyAdmin before the other application; in this case, phpMyAdmin will redirect users to the authenticating application. This is done with:

$cfg['Servers'][$i]['SignonURL'] = 'http://www.mydomain.com/FirstApp';

How does the authenticating application store credentials in a format that phpMyAdmin can understand? An example is included as scripts/signon.php. In this script, there is a simple HTML form to input the credentials and logic that initializes the session—we would use FirstApp as a session name, and create the user, password, host, and port information into this session, shown as follows:

$_SESSION['PMA_single_signon_user']     = $_POST['user'];
$_SESSION['PMA_single_signon_password'] = $_POST['password'];
$_SESSION['PMA_single_signon_host']     = $_POST['host'];
$_SESSION['PMA_single_signon_port']     = $_POST['port'];

To pass additional configuration parameters to the signon module, $_SESSION['PMA_single_signon_cfgupdate'] can receive an array containing any additional server parameters that are permitted in $cfg['Servers'][$i].

The authenticating application then uses a way of its choosing—a link or a button—to let its users start phpMyAdmin. If an error happens during the login (for example, a denied access), the signon module saves into $_SESSION['PMA_single_signon_error_message'] the appropriate error message.

In another example, scripts/openid.php shows how to log in using the popular OpenID mechanism.

In the server-specific sections of the config.inc.php file, we see lines referring to $cfg['Servers'][$i] for each server. Here, the variable $i is used so that one can easily cut and paste whole sections of the configuration file to configure more servers. While copying such sections, we should take care that the $i++; instruction, which precedes each section and is crucial to delimit the server sections, is also copied.

Then, at the end of the sections, the following line controls the startup:

$cfg['ServerDefault'] = 1;

The default value, 1, means that phpMyAdmin will use by default the first server defined. We can specify any number, for the corresponding server-specific section. We can also enter the value 0, signifying no default server; in this case a list of available servers will be presented at login time.

This configuration can also be done via web-based setup. Given here is an example of a multi-server definition, with the default server being set to let the user choose:

With no default server defined, phpMyAdmin will present a server choice:

Another mechanism can be used if we want to be able to connect to an undefined MySQL server. First, we have to set the following parameter:

$cfg['AllowArbitraryServer'] = TRUE;

We also have to put back the default value of 1 into $cfg['ServerDefault']. Then, we need to use the cookie authentication type. We will be able to choose the server and enter a username and a password.

As seen here, we still can choose one of the defined servers in Server Choice. In addition, we can also enter an arbitrary server name, a username, and a password: