Link this to the actual page on docs.zendframework.com. Also, that page is now under a /v1/ segment...

It's not storing the user's credential, though, but rather the username and any authorization details, right?

Yes, that's true. It stores the following information:

[
    'oauth_user_id' => /* user's identifier (string) */,
    'oauth_client_id' => /* the client id (string) */,
    'oauth_access_token_id' => /* the access token id (string) */,
    'oauth_scopes' => /* the scopes (mixed, usually an array) */
]

I'll rephrase the sentence.

Rephrase:

You may retrieve these values en masse using the getDetails() method or individually using the getDetail($name) method of the user instance. As an example:

The above is confusion. May I recommend the following?

If you wish to provide a custom Zend\Expressive\Authentication\UserInterface implementation, you will need to provide:

• a custom implementation of the the interface
• a factory capable of generating instances of that interface
• a DI factory for generating the previous factory
• configuration wiring the UserInterface service to your factory.

The factory noted in the second step should be a callable with the following signature:

function (
    string $identity,
    array $roles = [],
    array $details = []
) : Zend\Expressive\Authentication\UserInterface

As an example of the factory in the third point, you will create a standard DI factory to return it. It could, for instance, compose a database adapter to pull information and create your custom user implementation:

class CustomUserFactory
{
    public function __invoke(Psr\Container\ContainerInterface $container) : callable
    {
        $db = $container->get(Zend\Db\Adapter\AdapterInterface::class);
        return function (string $identity, array $roles = [], array $details = []) use ($db) : Zend\Expressive\Authentication\UserInterface {
            // get some data from $db
            // return a new instance
            return new MyCustomUserType(/* ... */);
        });
    }
}

You will then need to wire this factory to the UserInterface service, per the following example:

and then you would have the example you detail below for configuration.

Avoid words like "simple" and "easy" in the documentation. When a user doesn't find the instructions simple or easy, they then feel they are not smart enough to use the code.

The above can be rephrased to something like:

Adding the token endpoint involves routing to the provided Zend\Expressive\Authentication\OAuth2\TokenHandler.

Question: is there any reason we should NOT provide this middleware by default?

This middleware is related to the business logic of the application and can vary from case to case. Maybe, we should think to provide an example for a common scenario.

We need to document this change in the CHANGELOG.md as well.

This was actually a documentation error introduced by #42. The correct attribute for user was UserInterface::class and not authenticated_user.

One note: because these pages are already published, we need to provide them in the repository as redirects. You can see how this is done in the zend-expressive repo; it involves having pages with a JS redirect, and then having _-prefixed pages in the mkdocs.yml file that point to them (so they don't end up in the TOC).

Since one or the other of these has to be set (see previous conditional), this can be just $userId ?? $clientId.