Usage
Verify
Introduction
Most usage of this package will be through the \Rawilk\Yubikey\Facades\Yubikey facade, which represents the \Rawilk\Yubikey\Yubikey class. You will need to use the facade to associate a new security key with a user, and you may optionally use it to verify a security key for a user, but our trait for the user model will make doing that a little easier.
Verify To Associate
To verify a security key, you will need to capture the OTP token generated by the security key when the user touches the key to confirm they want to use it. In this example, we will reference it from a POST variable in the request via request()->otp, but your implementation may be different.
$response = \Rawilk\Yubikey\Facades\Yubikey::verify(request()->otp);
Auth::user()->associateYubikeyIdentity($response['identity']);
Given that the security key signature is valid, and the user doesn't already have that key tied to their account, this will associate that security key with the user account. The $response variable will be an array returned from the Yubico API only if the request was for a valid key. In all other cases, a \Rawilk\Yubikey\Exceptions\YubikeyVerifyException will be thrown. The following scenarios will result in an exception being thrown:
| Status | Description |
|---|---|
| BAD_OTP | The OTP is an invalid format. |
| REPLAYED_OTP | The OTP has already been seen by the service. |
| BAD_SIGNATURE | The HMAC signature verification failed. |
| MISSING_PARAMETER | The request lacks a required parameter. |
| NO_SUCH_CLIENT | The request client id is not valid. |
| OPERATION_NOT_ALLOWED | The API key is not allowed to verify OTPs. |
| BACKEND_ERROR | Unexpected error occured on a Yubico server. |
| NOT_ENOUGH_ANSWERS | A Yubico server could not get requested number of syncs before timeout. |
| REPLAYED_REQUEST | The Yubico server has already seen the OTP/Nonce combination before. |
When associating a security key to a user via associateYubikeyIdentity, a \Rawilk\Yubikey\Exceptions\YubikeyIdentityException will be thrown if:
- The user (or another user) already registered the security key.
- The user already has 5 keys registered to their account.
{tip} You may specify a name for the security key as the second argument for the
associateYubikeyIdentity()method. This can be useful for users to keep track of which keys are which.
Verify To Authenticate
In your authentication workflows, you may verify that a security key as a two-factor authentication method for a user via the verifyYubikeyIdentity() method provided on the HasYubikeys trait.
$verified = $user->verifyYubikeyIdentity(request()->otp);
Behind the scenes, the verifyYubikeyIdentity method is calling \Rawilk\Yubikey\Facades\Yubikey::verify() to verify the legitimacy of the security key, and is then checking that the security key is registered and belongs to the given user. As with the previous step for associating the key, a \Rawilk\Yubikey\Exceptions\YubikeyVerifyException may be thrown for any number of reasons if the request fails, and your application should handle them accordingly.
You may choose to call the verify method on the facade yourself, but you must then ensure the security key is actually for the user you're trying to authenticate.