Merge branch 'travis/spec/is-auth' into travis/spec/is-terms

pull/977/head
Travis Ralston 5 years ago
commit b7e84cf4ce

@ -110,10 +110,13 @@ paths:
id_server: id_server:
type: string type: string
description: The identity server to use. description: The identity server to use.
id_access_token:
type: string
description: An access token previously registered with the identity server.
sid: sid:
type: string type: string
description: The session identifier given by the identity server. description: The session identifier given by the identity server.
required: ["client_secret", "id_server", "sid"] required: ["client_secret", "id_server", "id_access_token", "sid"]
bind: bind:
type: boolean type: boolean
description: |- description: |-
@ -125,6 +128,7 @@ paths:
example: { example: {
"three_pid_creds": { "three_pid_creds": {
"id_server": "matrix.org", "id_server": "matrix.org",
"id_access_token": "abc123_OpaqueString",
"sid": "abc123987", "sid": "abc123987",
"client_secret": "d0n'tT3ll" "client_secret": "d0n'tT3ll"
}, },
@ -189,6 +193,11 @@ paths:
homeserver does not know the original ``id_server``, it MUST return homeserver does not know the original ``id_server``, it MUST return
a ``id_server_unbind_result`` of ``no-support``. a ``id_server_unbind_result`` of ``no-support``.
example: "example.org" example: "example.org"
id_access_token:
type: string
description: |-
An access token previously registered with the identity server. Required
if an ``id_server`` is specified.
medium: medium:
type: string type: string
description: The medium of the third party identifier being removed. description: The medium of the third party identifier being removed.

@ -139,6 +139,9 @@ paths:
id_server: id_server:
type: string type: string
description: The hostname+port of the identity server which should be used for third party identifier lookups. description: The hostname+port of the identity server which should be used for third party identifier lookups.
id_access_token:
type: string
description: An access token previously registered with the identity server.
medium: medium:
type: string type: string
# TODO: Link to Identity Service spec when it eixsts # TODO: Link to Identity Service spec when it eixsts
@ -146,7 +149,7 @@ paths:
address: address:
type: string type: string
description: The invitee's third party identifier. description: The invitee's third party identifier.
required: ["id_server", "medium", "address"] required: ["id_server", "id_access_token", "medium", "address"]
room_version: room_version:
type: string type: string
description: |- description: |-

@ -0,0 +1,36 @@
# Copyright 2018 New Vector Ltd
# 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.
type: object
properties:
access_token:
type: string
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.
token_type:
type: string
description: The string ``Bearer``.
matrix_server_name:
type: string
description: |-
The homeserver domain the consumer should use when attempting to
verify the user's identity.
expires_in:
type: integer
description: |-
The number of seconds before this token expires and a new one must
be generated.
required: ['access_token', 'token_type', 'matrix_server_name', 'expires_in']

@ -23,4 +23,7 @@ allOf:
include a port. This parameter is ignored when the homeserver handles include a port. This parameter is ignored when the homeserver handles
3PID verification. 3PID verification.
example: "id.example.com" example: "id.example.com"
required: ["id_server"] id_access_token:
type: string
description: An access token previously registered with the identity server.
required: ["id_server", "id_access_token"]

@ -23,4 +23,7 @@ allOf:
include a port. This parameter is ignored when the homeserver handles include a port. This parameter is ignored when the homeserver handles
3PID verification. 3PID verification.
example: "id.example.com" example: "id.example.com"
required: ["id_server"] id_access_token:
type: string
description: An access token previously registered with the identity server.
required: ["id_server", "id_access_token"]

@ -73,28 +73,7 @@ paths:
"expires_in": 3600, "expires_in": 3600,
} }
schema: schema:
type: object $ref: "definitions/openid_token.yaml"
properties:
access_token:
type: string
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``.
token_type:
type: string
description: The string ``Bearer``.
matrix_server_name:
type: string
description: |-
The homeserver domain the consumer should use when attempting to
verify the user's identity.
expires_in:
type: integer
description: |-
The number of seconds before this token expires and a new one must
be generated.
required: ['access_token', 'token_type', 'matrix_server_name', 'expires_in']
429: 429:
description: This request was rate-limited. description: This request was rate-limited.
schema: schema:

@ -542,6 +542,11 @@ paths:
it must return an ``id_server_unbind_result`` of it must return an ``id_server_unbind_result`` of
``no-support``. ``no-support``.
example: "example.org" example: "example.org"
id_access_token:
type: string
description: |-
An access token previously registered with the identity server. Required if an
``id_server`` is supplied.
responses: responses:
200: 200:
description: The account has been deactivated. description: The account has been deactivated.

@ -92,6 +92,7 @@ paths:
type: object type: object
example: { example: {
"id_server": "matrix.org", "id_server": "matrix.org",
"id_access_token": "abc123_OpaqueString",
"medium": "email", "medium": "email",
"address": "cheeky@monkey.com" "address": "cheeky@monkey.com"
} }
@ -99,6 +100,9 @@ paths:
id_server: id_server:
type: string type: string
description: The hostname+port of the identity server which should be used for third party identifier lookups. description: The hostname+port of the identity server which should be used for third party identifier lookups.
id_access_token:
type: string
description: An access token previously registered with the identity server.
medium: medium:
type: string type: string
# TODO: Link to Identity Service spec when it eixsts # TODO: Link to Identity Service spec when it eixsts
@ -106,7 +110,7 @@ paths:
address: address:
type: string type: string
description: The invitee's third party identifier. description: The invitee's third party identifier.
required: ["id_server", "medium", "address"] required: ["id_server", "id_access_token", "medium", "address"]
responses: responses:
200: 200:
description: The user has been invited to join the room. description: The user has been invited to join the room.

@ -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"

@ -0,0 +1 @@
Add a required ``id_access_token`` to many places which require an ``id_server`` parameter.

@ -0,0 +1 @@
Deprecate the v1 API in favour of an authenticated v2 API.

@ -0,0 +1 @@
Add ``/account``, ``/account/register``, and ``/account/logout`` to authenticate with the identity server.

@ -170,7 +170,7 @@ This endpoint does *not* require authentication.
#### `POST $prefix/terms`: #### `POST $prefix/terms`:
Requests to this endpoint have a single key, `user_accepts` whose value is Requests to this endpoint have a single key, `user_accepts` whose value is
a list of URLs (given by the `url` field in the GET response) of documents that a list of URLs (given by the `url` field in the GET response) of documents that
the user has agreed to: the user has agreed to:
```json ```json
@ -269,7 +269,7 @@ A client uses this client/server API endpoint to request that the Homeserver
removes the given 3PID from the given Identity Server, or all Identity Servers. removes the given 3PID from the given Identity Server, or all Identity Servers.
Takes the same parameters as Takes the same parameters as
`POST /_matrix/client/r0/account/3pid/delete`, ie. `id_server`, `medium`, `POST /_matrix/client/r0/account/3pid/delete`, ie. `id_server`, `medium`,
`address` and the newly added `is_token`. `address` and the newly added `id_access_token`.
Returns the same as `POST /_matrix/client/r0/account/3pid/delete`. Returns the same as `POST /_matrix/client/r0/account/3pid/delete`.

@ -802,7 +802,8 @@ To use this authentication type, clients should submit an auth dict as follows:
{ {
"sid": "<identity server session id>", "sid": "<identity server session id>",
"client_secret": "<identity server client secret>", "client_secret": "<identity server client secret>",
"id_server": "<url of identity server authed with, e.g. 'matrix.org:8090'>" "id_server": "<url of identity server authed with, e.g. 'matrix.org:8090'>",
"id_access_token": "<access token previously registered with the identity server>"
} }
], ],
"session": "<session ID>" "session": "<session ID>"
@ -830,7 +831,8 @@ To use this authentication type, clients should submit an auth dict as follows:
{ {
"sid": "<identity server session id>", "sid": "<identity server session id>",
"client_secret": "<identity server client secret>", "client_secret": "<identity server client secret>",
"id_server": "<url of identity server authed with, e.g. 'matrix.org:8090'>" "id_server": "<url of identity server authed with, e.g. 'matrix.org:8090'>",
"id_access_token": "<access token previously registered with the identity server>"
} }
], ],
"session": "<session ID>" "session": "<session ID>"

@ -57,8 +57,6 @@ The following other versions are also available, in reverse chronological order:
General principles 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 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 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 "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-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Authorization 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_UNAUTHORIZED``.
{{v2_auth_is_http_api}}
Status check Status check
------------ ------------

Loading…
Cancel
Save