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.

Here setReturnUri("/") returns the visitor to the application's home page. The provider resolves this path against the deployment's configured client URI. Each return route must load auth.php before output so it can complete authentication. See Provider configuration and return URIs for destinations, query strings and fragments.

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. Continue with Logging out to add a sign-out action and choose where visitors return afterwards.

---

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