Provider configuration and return URIs

The client key, provider host and return location describe one application deployment. Keeping those settings together makes it easier to move from local development to a deployed application.

Choosing the provider

The default host is login.authwave.com. To use a self-hosted provider, supply authwaveHost:

$auth = new Authwave\Authenticator(
	clientKey: $clientKey,
	currentUriPath: $_SERVER["REQUEST_URI"],
	authwaveHost: "https://login.example.com",
);

Use the client key issued by that provider for the intended deployment. The client splits it at the final underscore into the deployment ID and shared secret.

authwaveHost describes the provider's authority: scheme, host and optional port. A path prefix is discarded when the provider URI is normalised, so these URI builders do not support mounting the provider under a path such as /authwave/.

Local development

A local provider can use HTTP:

$auth = new Authwave\Authenticator(
	clientKey: $clientKey,
	currentUriPath: $_SERVER["REQUEST_URI"],
	authwaveHost: "http://localhost:8081",
);

HTTPS is required for other hosts except the additional literal 127.0.0.127 allowed by the current implementation. In particular, http://127.0.0.1 is not covered by that exception. An unsupported scheme raises Authwave\InsecureProtocolException when a provider URI is built.

Returning after login

currentUriPath tells the constructor where this request arrived. Include the path and query string so the client can recognise an authentication response and remove it afterwards.

Login requests use that URI as their requested return destination unless we configure another value. For example, a visitor signing in to view their orders can return straight to that page:

$auth->setReturnUri("/members/orders?status=open#latest");
$auth->login();

The provider saves the validated destination during login and sends the encrypted authentication response to /members/orders?status=open, with #latest as the fragment. That application route must run the same authentication setup as the rest of the application. The client stores the user, restores the saved query string and redirects to remove the authentication response parameter.

Call setReturnUri() before login(). It changes subsequent outgoing login and logout destinations; it does not change the current request or rerun the constructor's response processing.

Supported login destinations

The provider resolves destinations against the deployment's configured client return URI. If that URI is https://app.example.com/callback, the following destinations are supported:

Requested destination	Return location
/members/orders?status=open#latest	https://app.example.com/members/orders?status=open#latest
https://app.example.com/members/	https://app.example.com/members/
?page=2	https://app.example.com/callback?page=2
#details	https://app.example.com/callback#details

Absolute URLs must match the configured client scheme, host and effective port. For example, HTTPS on its default port is equivalent to an explicit port of 443. Use paths beginning with / rather than path-relative values such as members/orders.

The provider ignores external origins, credentials in URLs, scheme-relative values beginning with //, malformed hexadecimal data, control characters and backslashes. Without a valid requested destination it uses the deployment's configured client return URI. Integrations that supply only an encrypted returnQuery can apply that query string to the default location.

The default behaviour of this PHP client is to request its current URI, so omitting setReturnUri() normally returns the visitor to the page that started login.

What the provider receives

The URI builder sends the requested return value as hexadecimal text in the u query parameter. It also sends d for the deployment identifier, c for the encrypted request and i for its initialisation vector. The provider validates u and keeps the resolved destination in its login session.

The client also includes the requested query string as encrypted returnQuery data and saves it in the application's session for response tidying. The provider uses the query from a validated full destination in preference to the query-only value.

Returning after logout

An explicit destination passed to logout() takes priority over setReturnUri(). The client sends the chosen destination as encrypted redirectTo data, which the provider uses for return navigation. Relative paths are resolved against the deployment's client URI. Without either setting, the provider uses its default return location. See Logging out for examples.

A query-only logout argument uses the current application request path. For login, a query-only destination uses the deployment's configured return path, as shown above.

Keep destinations under application control. If a destination comes from a request parameter, validate it against the routes our application allows before passing it on.

---

Next, see Sessions and redirects for integrating the client into an existing application.