Define authentication, ripping off the client-server API description

api/client-server/definitions/openid_token.yaml

@@ -19,7 +19,7 @@ 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``.
+      API ``GET /openid/userinfo`` to verify the user's identity.
   token_type:
     type: string
     description: The string ``Bearer``.

api/identity/v2_auth.yaml

@@ -0,0 +1,109 @@
+# Copyright 2019 The Matrix.org Foundation C.I.C.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+swagger: '2.0'
+info:
+  title: "Matrix Identity Service Authentication API"
+  version: "2.0.0"
+host: localhost:8090
+schemes:
+  - https
+basePath: /_matrix/identity/v2
+consumes:
+  - application/json
+produces:
+  - application/json
+securityDefinitions:
+  $ref: definitions/security.yaml
+paths:
+  "/account/register":
+    post:
+      summary: Exchanges an OpenID token for an access token.
+      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.
+      operationId: registerAccount
+      parameters:
+        - in: body
+          name: body
+          schema:
+            $ref: "../client-server/definitions/openid_token.yaml"
+      responses:
+        200:
+          description: |-
+            A token which can be used to authenticate future requests to the
+            identity server.
+          examples:
+            application/json: {
+              "token": "abc123_OpaqueString"
+            }
+          schema:
+            type: object
+            properties:
+              token:
+                type: string
+                description: |-
+                  An opaque string representing the token to authenticate future
+                  requests to the identity server with.
+            required: ['token']
+  "/account":
+    get:
+      summary: Gets account holder information for a given token.
+      description: |-
+        Gets information about what user owns the access token used in the request.
+      operationId: getAccount
+      security:
+        - accessToken: []
+      parameters: []
+      responses:
+        200:
+          description: The token holder's information.
+          examples:
+            application/json: {
+              "user_id": "@alice:example.org"
+            }
+          schema:
+            type: object
+            properties:
+              user_id:
+                type: string
+                description: The user ID which registered the token.
+            required: ['user_id']
+  "/account/logout":
+    post:
+      summary: Logs out an access token, rendering it unusable.
+      description: |-
+        Logs out the access token, preventing it from being used to authenticate
+        future requests to the server.
+      operationId: logout
+      security:
+        - accessToken: []
+      parameters: []
+      responses:
+        200:
+          description: The token was successfully logged out.
+          examples:
+            application/json: {}
+          schema:
+            type: object
+        401:
+          description: |-
+            The token is not registered or is otherwise unknown to the server.
+          examples:
+            application/json: {
+              "errcode": "M_UNKNOWN_TOKEN",
+              "error": "Unrecognised access token"
+            }
+          schema:
+            $ref: "../client-server/definitions/errors/error.yaml"

specification/identity_service_api.rst

@@ -57,8 +57,6 @@ The following other versions are also available, in reverse chronological order:
 General principles
 ------------------
 
-.. TODO: TravisR - Define auth for IS v2 API in a future PR
-
 The purpose of an identity server is to validate, store, and answer questions
 about the identities of users. In particular, it stores associations of the form
 "identifier X represents the same user as identifier Y", where identities may
@@ -173,6 +171,33 @@ to be returned by servers on all requests are::
   Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
   Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Authorization
 
+Authentication
+--------------
+
+Most ``v2`` endpoints in the Identity Service API require authentication in order
+to ensure that the requesting user has accepted all relevant policies and is otherwise
+permitted to make the request. The ``v1`` API (currently deprecated) does not require
+this authentication, however using ``v1`` is strongly discouraged as it will be removed
+in a future release.
+
+Identity Servers use a scheme similar to the Client-Server API's concept of access
+tokens to authenticate users. The access tokens provided by an Identity Server cannot
+be used to authenticate Client-Server API requests.
+
+An access token is provided to an endpoint in one of two ways:
+
+1. Via a query string parameter, ``access_token=TheTokenHere``.
+2. Via a request header, ``Authorization: Bearer TheTokenHere``.
+
+Clients are encouraged to the use the ``Authorization`` header where possible to prevent
+the access token being leaked in access/HTTP logs. The query string should only be used
+in cases where the ``Authorization`` header is inaccessible for the client.
+
+When credentials are required but missing or invalid, the HTTP call will return with a
+status of 401 and the error code ``M_MISSING_TOKEN`` or ``M_UNKNOWN_TOKEN`` respectively.
+
+{{v2_auth_is_http_api}}
+
 Status check
 ------------