PHP : Utiliser l’Authentication API avec Auth0-PHP

En utilisant l’Authentication API d’Auth0 dans vos applications PHP.

La trousse SDK Auth0 pour PHP fournit une classe Auth0\SDK\API\Authentication, qui contient les méthodes que vous pouvez utiliser pour accéder directement à l’Authentication API. Veuillez noter que cette interface est destinée à des applications plus avancées et fournit en général une façon de suivre les sessions des utilisateurs. Pour la plupart des cas d’utilisation, vous souhaiterez travailler avec la classe de base Auth0.

Dans cet article, vous trouverez des exemples d’opérations d’authentification communes.

Prérequis

La documentation ci-dessous part du principe que vous avez suivi les étapes des sections sur l’installation et le démarrage, et que vous avez utilisé le code fourni.

Flux de code d’autorisation

Un Flux de code d’autorisation est la façon de base de donner accès aux utilisateurs à votre application. Ce flux est le même utilisé sur la Utilisation de base d’Auth0-PHP. Si vous avez besoin d’un contrôle plus granulaire sur le processus de connexion ou de Callback, cette section explique comment utiliser directement l’Authentication API.

Les utilisateurs doivent s’authentifier avec Auth0 pour générer le code d’autorisation. Ceci se fait en étant redirigé vers le point de terminaison /authorize pour votre domaine locataire. Le code suivant s’affichera sur une page nécessitant une authentification :

// 👆 We're continuing from the "getting started" guide linked in "Prerequisites" above. Append this to the index.php file you created there.

// Setup a PHP session, which we'll use as a custom session store for the authenticated user.
session_start();

// $user will be null if no session is available; otherwise it will contain user data.
$user = $_SESSION['user'] ?? null;

// Has the user authenticated with us yet?
if ($user === null) {
    // Generates cryptographically secure pseudo-random bytes to use as a CSRF mitigating value.
    // Store this for retrieval after authentication.
    $_SESSION['state'] = bin2hex(random_bytes(16));

    // Generate the authorize URL, and redirect the user to it.
    header('Location: ' . $auth0->authentication()->getLoginLink($_SESSION['state']));
    exit;
}

echo '<h1>Sensitive data!</h1>';

Le processus ci-dessus réalise le suivant :

1. Nous vérifions s’il existe un état d’utilisateur authentifié stocké dans notre gestionnaire de session personnalisé. Votre application peut gérer les sessions utilisateur différemment.
2. S’il n’y a pas de session, nous devons alors connecter l’utilisateur en le redirigeant vers la page de connexion universelle.
3. Nous définissons une valeur d’état avec la demande de connexion, puis vérifions cette valeur lorsque le code est renvoyé sur l’URL de rappel. Nous stockons cela dans notre session PHP sous la clé « state ».
4. L’appel getLoginLink() crée le lien /authorize avec le type de réponse correct (code dans ce cas), l’URI de redirection (dans lequel l’application nous gérerons la réponse, expliquée ci-dessous) et l’état (ci-dessus).
5. Nous redirigeons ensuite vers cette URL et attendons que l’utilisateur soit redirigé vers nous.

Après authentification, l’utilisateur est redirigé vers notre application à l’URL de rappel, qui est gérée comme suit :

// 👆 We're continuing from the "getting started" guide linked in "Prerequisites" above. Append this to the index.php file you created there.

// Ensure we have our PHP session open so we can retrieve our stored state for comparison.
session_start();

// Extract `code` and `state` parameters from the request query, if present.
$code = filter_var($_GET['code'] ?? null, FILTER_UNSAFE_RAW, FILTER_NULL_ON_FAILURE);
$state = filter_var($_GET['state'] ?? null, FILTER_UNSAFE_RAW, FILTER_NULL_ON_FAILURE);

// Check if a code is present in the request query.
if ($code === null) {
    die('No authorization code found.');
}

// Check if a state is present, and compare it with the one we generated and stored before redirecting the user.
if ($state === null || $state !== $_SESSION['state']) {
    die('Invalid state.');
}

// We have compared states, we should discard this stored value now.
unset($_SESSION['state']);

// Attempt to get an access_token with the code returned and original redirect URI. (This returns a PSR-7 ResponseInterface.)
$response = $auth0->authentication()->codeExchange($code);

// Does the status code of the response indicate failure?
if ($response->getStatusCode() !== 200) {
    die("Code exchange failed.");
}

// Decode the JSON response into a PHP array:
$response = json_decode(response->getBody()->__toString(), true, 512, JSON_THROW_ON_ERROR);

// Create an array to store our session information in.
$session = [
    'id_token' => $response['id_token'] ?? null,
    'access_token' => $response['access_token'] ?? null,
    'scope' => $response['scope'] ?? null,
    'refresh_token' => $response['refresh_token'] ?? null,
    'expires_in' => $response['expires_in'] ?? null,
    'user' => null
];

// We retrieved an ID token; let's process it!
if ($session['id_token'] !== null) {
    // The Auth0 SDK includes a helpful token processing utility we'll leverage for this:
    $token = new \Auth0\SDK\Token($auth0->configuration(), $session['id_token'], \Auth0\SDK\Token::TYPE_ID_TOKEN);

    // Verify the token, and validate it's claims. These will throw an \Auth0\SDK\Exception\InvalidTokenException if a check fails.
    $token->verify();
    $token->validate();

    $session['user'] => $token->toArray();
}

// Store our authenticated session state.
$_SESSION['user'] = $session;

// Let's echo the user claims/identity as a demo of a successful authentication flow:
print_r($session['user']);

Parcourir le processus en détail :

1. Nous recherchons un paramètre code dans une demande. S’il est manquant, nous abandonnons l’authentification.
2. Nous vérifions que nous avons une valeur state et qu’elle coïncide à la même que celle générée. Ceci est important pour éviter les attaques CSRF.
3. Nous tentons un échange de code avec l’appel codeExchange(), en s’assurant de transmettre le code qu’Auth0 a donné à notre application lorsqu’il nous a renvoyé l’utilisateur authentifiant.
4. Si cela réussit, nous savons que l’échange a réussi et nous disposons d’un jeton d’ID et d’un jeton d’accès parmi d’autres valeurs potentielles.
5. Nous validons le jeton d’ID et utilisons les demandes pour l’identité de l’utilisateur.
6. Si cette dernière étape réussit, nous stockons l’utilisateur et le redirigeons vers nos données sensibles.

Flux des identifiants client

Le Flux des identifiants client donne à une application l’accès à une API particulière en fonction des permissions définies dans le tableau de bord. C’est ainsi que les applications peuvent, par exemple, appeler Management API. Une authentification réussie entraînera l’émission d’un jeton d’accès pour l’API demandée.

Premièrement, activez la méthode Identification du client, puis l’onglet Paramètres avancés > Types d’autorisation sur la page Paramètres d’application.

Ensuite, autorisez l’application pour l’API a utiliser sous l’onglet Applications de communication entre machines sur la page Paramètres de l’API. Assurez-vous que toutes les permissions nécessaires sont sélectionnées (mais pas plus) et mettez à jour. Revenez sous l’onglet Paramètres et copiez la valeur de Identifiant. Ceci doit être ajouté à une clé AUTH0_MANAGEMENT_AUDIENCE dans votre fichier .env.

Demandez un jeton d’accès pour l’API en utilisant l’exemple ci-dessous :

// 👆 We're continuing from the "getting started" guide linked in "Prerequisites" above.

// Begin a client credentials exchange:
$response = $auth0->authentication()->clientCredentials([
    'audience' => $_ENV['AUTH0_MANAGEMENT_AUDIENCE']
]);

// Does the status code of the response indicate failure?
if ($response->getStatusCode() !== 200) {
    die("Code exchange failed.");
}

// Decode the JSON response into a PHP array:
$response = json_decode(response->$getBody()->__toString(), true, 512, JSON_THROW_ON_ERROR);

// Echo the response to the browser
print_r($response, true);

Si la méthode a réussi, vous devriez voir ce qui suit :

Array
(
    [access_token] => eyJ0eXAi...eyJpc3Mi...QoB2c24w
    [scope] => read:users read:clients ...
    [expires_in] => 86400
    [token_type] => Bearer
)

Consultez Utilisation de Management API avec Auth0-PHP pour plus d’informations sur la façon d’utiliser ce jeton d’accès.

Déconnexion d’authentification unique (SSO)

Bien que détruire la session locale avec session_destroy() suffirait à désauthentifier un utilisateur de votre application, vous devez aussi fermer la session de votre utilisateur final avec Auth0. Cela garantit que la prochaine fois que l’utilisateur verra un formulaire de connexion Auth0, ses informations d’identification lui seront demandées pour se connecter.. Tout d’abord, déterminez où l’utilisateur doit se retrouver une fois la déconnexion terminée. Enregistrez-le dans les paramètres de l’application Auth0 dans le champ « URL de déconnexion autorisées ». Aussi, ajoutez une clé AUTH0_LOGOUT_RETURN_URL avec cette URL comme valeur dans votre fichier .env Ajoutez ce qui suit au code de déconnexion de votre application :

// 👆 We're continuing from the "getting started" guide linked in "Prerequisites" above.

// Deauthenticate the user's local session in your application.
session_destroy();

// Redirect to Auth0's logout URL to end their Auth0 session:
header("Location: " . $auth0->authentication()->getLogoutLink($_ENV['AUTH0_LOGOUT_RETURN_URL']);

En savoir plus

• PHP : Premiers pas avec Auth0-PHP
• PHP : Connexion, déconnexion et restitution des profils utilisateurs avec Auth0-PHP
• PHP : Utiliser Management API avec Auth0-PHP
• PHP : valider les jetons Web JSON (JWT) avec Auth0-PHP
• PHP : Dépannage de votre intégration Auth0-PHP