Quick start guide

In this guide we will add a login button and a greeting to a small PHP application. We will keep the shared setup in one file so that every page handles returning authentication requests in the same way.

1. Install the package

The client requires PHP 8.4 or later and the Sodium extension.

composer require authwave/php-client

2. Register the application

Create an application deployment in your Authwave provider and configure its client return URI. Copy the complete client key into the application's server-side configuration. For these examples, we will expose it to PHP through an environment variable named AUTHWAVE_CLIENT_KEY.

The key contains a deployment identifier and a secret, separated at the final underscore. Use the value supplied by the provider unchanged. It belongs on the server, outside public files and version control.

3. Create the shared setup

Create auth.php alongside vendor/:

<?php
use Authwave\Authenticator;

require_once __DIR__ . "/vendor/autoload.php";

session_start();

$clientKey = getenv("AUTHWAVE_CLIENT_KEY");
if($clientKey === false || $clientKey === "") {
	throw new RuntimeException("Set AUTHWAVE_CLIENT_KEY before running the application.");
}

$auth = new Authenticator(
	clientKey: $clientKey,
	currentUriPath: $_SERVER["REQUEST_URI"],
);

Composer's autoloader must be available before session_start() restores stored objects. The session must be started before constructing Authenticator.

Pass the actual request path and query string as currentUriPath, including on the provider's return request. The constructor checks this URI for the authentication response. Run this setup before HTML, whitespace or other response output because it can redirect immediately.

4. Add a login endpoint

Create login.php:

<?php
require __DIR__ . "/auth.php";

$auth->setReturnUri("/");
$auth->login();

// login() returns normally if the visitor is already logged in.
header("Location: /", true, 303);
exit;

login() normally sends a redirect and ends the request. The final redirect handles a visitor who is already logged in.

The requested return path must be supported by your provider configuration. See Provider configuration and return URIs for the distinction between the path sent by the client and the return URI selected by the provider.

5. Show the visitor's state

Create index.php:

<?php
require __DIR__ . "/auth.php";

if($auth->isLoggedIn()) {
	$user = $auth->getAuthUser();
	$email = htmlspecialchars($user->email, ENT_QUOTES, "UTF-8");
	echo "<p>You are logged in as <strong>$email</strong>.</p>";
}
else {
	echo '<p><a href="/login.php">Log in</a></p>';
}

Visit the application through your configured web server, choose Log in, and complete authentication at the provider. On return, the client stores the user and removes the encrypted response from the address bar with a redirect.

We now have the user's identity available on subsequent requests. Before adding a logout button, read Logging out for the current implementation's limitations.

---

Next, see Working with the authenticated user to use that identity in the application.