Add cross-references between the OpenID endpoints of the Client-Server API, Server-Server API and Identity-Service API

changelogs/client_server/newsfragments/2426.clarification

@@ -0,0 +1 @@
+Add cross-references between the OpenID endpoints of the Client-Server API, Server-Server API and Identity-Service API.

changelogs/identity_service/newsfragments/2426.clarification

@@ -0,0 +1 @@
+Add cross-references between the OpenID endpoints of the Client-Server API, Server-Server API and Identity-Service API.

changelogs/server_server/newsfragments/2426.clarification

@@ -0,0 +1 @@
+Add cross-references between the OpenID endpoints of the Client-Server API, Server-Server API and Identity-Service API.

content/client-server-api/modules/openid.md

@@ -4,6 +4,7 @@
 This module allows users to verify their identity with a third-party
 service. The third-party service does need to be matrix-aware in that it
 will need to know to resolve matrix homeservers to exchange the user's
-token for identity information.
+token for identity information, using the [OpenID section of the
+Server-Server API](/server-server-api/#openid).
 
 {{% http-api spec="client-server" api="openid" %}}

content/identity-service-api.md

@@ -164,6 +164,12 @@ of access tokens to authenticate users. The access tokens provided by an
 Identity Server cannot be used to authenticate Client-Server API
 requests.
 
+An Identity Service access token may be obtained as follows:
+ 1. The user's client requests an OpenID token from the homeserver using the
+     Client-Server API's [OpenID module](/client-server-api/#openid).
+ 2. The OpenID token is exchanged for an Identity Service access token via the
+     [`POST /_matrix/identity/v2/account/register`](#post_matrixidentityv2accountregister) endpoint.
+
 Access tokens may be provided via a request header, using the
 Authentication Bearer scheme: `Authorization: Bearer TheTokenHere`.
 

content/server-server-api.md

@@ -1134,9 +1134,10 @@ more specific queries that can be made.
 ## OpenID
 
 Third-party services can exchange an access token previously generated
-by the <span class="title-ref">Client-Server API</span> for information
-about a user. This can help verify that a user is who they say they are
-without granting full access to the user's account.
+by the [OpenID module of the Client-Server
+API](/client-server-api/#openid) for information about a user. This can
+help verify that a user is who they say they are without granting full
+access to the user's account.
 
 Access tokens generated by the OpenID API are only good for the OpenID
 API and nothing else.

data/api/client-server/definitions/openid_token.yaml

@@ -20,7 +20,8 @@ properties:
     description: |-
       An access token the consumer may use to verify the identity of
       the person who generated the token. This is given to the federation
-      API `GET /openid/userinfo` to verify the user's identity.
+      API [`GET /_matrix/federation/v1/openid/userinfo`](/server-server-api/#get_matrixfederationv1openiduserinfo)
+      to verify the user's identity.
   token_type:
     type: string
     description: The string `Bearer`.

data/api/client-server/openid.yaml

@@ -22,8 +22,8 @@ paths:
       description: |-
         Gets an OpenID token object that the requester may supply to another
         service to verify their identity in Matrix. The generated token is only
-        valid for exchanging for user information from the federation API for
-        OpenID.
+        valid for exchanging for user information from the
+        [federation API for OpenID](/server-server-api/#get_matrixfederationv1openiduserinfo).
 
         The access token generated is only valid for the OpenID API. It cannot
         be used to request another OpenID access token or call `/sync`, for

data/api/identity/v2_auth.yaml

@@ -22,7 +22,9 @@ paths:
       description: |-
         Exchanges an OpenID token from the homeserver for an access token to
         access the identity server. The request body is the same as the values
-        returned by `/openid/request_token` in the Client-Server API.
+        returned by
+        [`POST /_matrix/client/v3/user/{userId}/openid/request_token`](/client-server-api/#post_matrixclientv3useruseridopenidrequest_token)
+        in the Client-Server API.
       operationId: registerAccount
       requestBody:
         content:

data/api/server-server/openid.yaml

@@ -24,6 +24,10 @@ paths:
         Exchanges an OpenID access token for information about the user
         who generated the token. Currently this only exposes the Matrix
         User ID of the owner.
+
+        The access token is obtained by the Client-Server API's
+        [`POST /_matrix/client/v3/user/{userId}/openid/request_token`](/client-server-api/#post_matrixclientv3useruseridopenidrequest_token)
+        endpoint.
       operationId: exchangeOpenIdToken
       parameters:
         - in: query