REST API: Add App Password introspection endpoint

[TimothyBlynJacobs]

It can be helpful for an Application to be able to know which App Password it is using to authenticate. For instance, if an application is uninstalled, it'd be great if it could automatically delete its app password. This could also be helpful to add additional UI hints to the application's interface about how they are authenticated. For instance displaying the App Password's label. In the future, this would be necessary so an application could determine what scope it has been granted.

Currently, this is somewhat achievable by utilizing the app_id and making a request to wp/v2/application-passwords/me and searching thru all app password's with it's app_id. However, this doesn't work for instances where an Application might be installed on multiple devices, each of which will have it's own app password, but should use the same app_id.

I think this could be implemented as a wp/v2/application-passwords/introspect endpoint that would return the prepared response for the app password being used to authenticate. If one isn't found, the endpoint would 404. A more RESTful sounding name suggestion would be welcome. Note we already have a /me, and I think we'll also have a future exchange or refresh endpoint that would update the app password's password.

By traversing the self link, the Application could determine the correct route to use to update or delete the credential. So I don't think we necessarily need to implement those methods on the introspect route itself.

OAuth describes a potential introspection endpoint in ​RFC 7662. One thing of note is that it accepts a token as an argument. I think that is less useful for us because we don't have a separate concept of client authentication. The app password itself is the credential.

Trac ticket: https://core.trac.wordpress.org/ticket/52275

[xkon]

I agree that it's more efficient to provide a direct endpoint for self discovery than pushing it to the client to find out it's details by other means, which would result on issues if the app_id is the same on multiple instances.

Also as the uuid isn't known to the client from the get-go since only a username:pass is basically needed, direct calls to application-passwords/{uuid} endpoint are not possible as well.

Regarding the naming convention, since we're already using instances of me & self to avoid confusion by re-using any of those, the only extra that I could think of would be a whoami but not really sure if it's appropriate for use here. Introspect works just fine as well though imho.

---

I've already run some tests against the PR provided and everything seems to work as expected.

If anyone else is interested here's some details that show the problem this resolves & testing steps:

Step 1:
I've installed ​Basic Auth, just to do everything via Postman directly.

Step 2:
Created 2 Application Passwords by using my users username:password via BasicAuth for the time being. Examples:

• POST ​https://core.local/src/index.php?rest_route=/wp/v2/users/me/application-passwords&name=postman-test-1&app_id=794a4798-81fc-4f74-83f2-a716bcde8cd7
• POST ​https://core.local/src/index.php?rest_route=/wp/v2/users/me/application-passwords&name=postman-test-2&app_id=794a4798-81fc-4f74-83f2-a716bcde8cd7

Make sure to save 1 of the returned Passwords for testing the next steps.

Step 3:
Change BasicAuth details in Postman to username:application-password ( use any of the previously returned passwords ).

Step 4:
In Postman make a

• GET ​https://core.local/src/index.php?rest_route=/wp/v2/users/me/application-passwords/

This returns the Application Passwords registered to me but since the app_id is the same on both (since its the same app but on different supposed installations) I can't identify which of all apps I am and most importantly what's my uuid to continue with further actions.

Example response:

[
    {
        "uuid": "e2726369-36db-4447-8e58-013c8d7f915f",
        "app_id": "794a4798-81fc-4f74-83f2-a716bcde8cd7",
        "name": "postman-test-1",
        "created": "2021-01-28T12:06:29",
        "last_used": null,
        "last_ip": null,
        "_links": {
            "self": [
                {
                    "href": "https://core.local/src/index.php?rest_route=/wp/v2/users/1/application-passwords/e2726369-36db-4447-8e58-013c8d7f915f"
                }
            ]
        }
    },
    {
        "uuid": "5bb6b48b-99a5-4525-95c2-05ab72e3e2de",
        "app_id": "794a4798-81fc-4f74-83f2-a716bcde8cd7",
        "name": "postman-test-2",
        "created": "2021-01-28T12:06:39",
        "last_used": "2021-01-28T12:07:19",
        "last_ip": "127.0.0.1",
        "_links": {
            "self": [
                {
                    "href": "https://core.local/src/index.php?rest_route=/wp/v2/users/1/application-passwords/5bb6b48b-99a5-4525-95c2-05ab72e3e2de"
                }
            ]
        }
    }
]

Step 5:
Applied the patch from the provided PR (it can also be applied since the start, doesn't really matter).

Step 6:
In Postman make a new request to the /introspect endpoint which returns the details of the current Application Password used to make the request. I was using the password from the 2nd created client so postman-test-2 should be the correct return.

• GET ​https://core.local/src/index.php?rest_route=/wp/v2/users/me/application-passwords/introspect

{
    "uuid": "5bb6b48b-99a5-4525-95c2-05ab72e3e2de",
    "app_id": "794a4798-81fc-4f74-83f2-a716bcde8cd7",
    "name": "postman-test-2",
    "created": "2021-01-28T12:06:39",
    "last_used": "2021-01-28T12:07:19",
    "last_ip": "127.0.0.1",
    "_links": {
        "self": [
            {
                "href": "https://core.local/src/index.php?rest_route=/wp/v2/users/1/application-passwords/5bb6b48b-99a5-4525-95c2-05ab72e3e2de"
            }
        ]
    }
}

[TimothyBlynJacobs]

Thanks for testing @xkon! whoami is interesting and I think means the right thing, but yeah I think the language isn't exactly right here.

[TimothyBlynJacobs]

In 50065:

App Passwords: Introduce introspection endpoint.

This introduces a new endpoint, wp/v2/users/me/application-passwords/introspect, that will return details about the App Password being used to authenticate the current request. This allows for an application to disambiguate between multiple installations of their application which would all share the same app_id.

Props xkon, peterwilsoncc, TimothyBlynJacobs.
Fixes #52275.

Merged in ​https://github.com/WordPress/wordpress-develop/commit/e290a9b557406230612161839d90b068f3c6983b.