# Authenticator Selection Criteria

By default, any type of authenticator can be used by your users and interact with your application. In certain circumstances, you may need to select specific authenticators e.g. when user verification is required.

The WebAuthn API and this library allow you to define a set of options to disallow the registration of authenticators that do not fulfill the conditions.

The class `Webauthn\AuthenticatorSelectionCriteria` is designed for this purpose. It is used when generating the `Webauthn\PublicKeyCredentialCreationOptions` object.

## Available Criteria

### Authenticator Attachment Modality

You can indicate if the authenticator must be attached to the client (platform authenticator i.e. it is usually not removable from the client device) or must be detached (roaming authenticator).

Possible values are:

* `AuthenticatorSelectionCriteria::AUTHENTICATOR_ATTACHMENT_NO_PREFERENCE`: there is no requirement (default value),
* `AuthenticatorSelectionCriteria::AUTHENTICATOR_ATTACHMENT_PLATFORM`: the authenticator must be attached,
* `AuthenticatorSelectionCriteria::AUTHENTICATOR_ATTACHMENT_CROSS_PLATFORM`: must be a roaming authenticator.

A primary use case for platform authenticators is to register a particular client device as a "trusted device" for future authentication. This gives the user the convenience benefit of not needing a roaming authenticator, e.g., the user will not have to dig around in their pocket for their key fob or phone.

### Resident Key

With this criterion, a credential record will be stored in the authenticator, client or client device. Such storage requires an authenticator capable to store such a resident credential.

{% hint style="info" %}
A resident key shall be created if you want to [authenticate users without username](/pure-php/advanced-behaviours/authentication-without-username.md).
{% endhint %}

{% hint style="warning" %}
**Backward Compatibility (v5.3.0+):** The `requireResidentKey` property has been restored for backward compatibility with WebAuthn Level 3 specification. While `residentKey` is the preferred modern approach, `requireResidentKey` is still supported for legacy implementations.
{% endhint %}

### User Verification

[Please refer to this page](/pure-php/advanced-behaviours/user-verification.md).

### Example

With this example, we require the user verification (PIN, fingerprint...), a resident key and an authenticator embedded onto a device. This is typically what you will require for Windows Hello or Face ID authentication.

{% code lineNumbers="true" %}

```php
use Webauthn\AuthenticatorSelectionCriteria;
use Webauthn\PublicKeyCredentialCreationOptions;

$authenticatorSelectionCriteria = AuthenticatorSelectionCriteria::create(
    authenticatorAttachment: AuthenticatorSelectionCriteria::AUTHENTICATOR_ATTACHMENT_PLATFORM,
    userVerification: AuthenticatorSelectionCriteria::USER_VERIFICATION_REQUIREMENT_REQUIRED,
    residentKey:AuthenticatorSelectionCriteria::RESIDENT_KEY_REQUIREMENT_REQUIRED,
);

$publicKeyCredentialCreationOptions =
    PublicKeyCredentialCreationOptions::create(
        $rpEntity,
        $userEntity,
        $challenge,
        authenticatorSelection: $authenticatorSelectionCriteria
);
```

{% endcode %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://webauthn-doc.spomky-labs.com/pure-php/advanced-behaviours/authenticator-selection-criteria.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.