@ -15,7 +15,7 @@
.. See the License for the specific language governing permissions and .. See the License for the specific language governing permissions and
.. limitations under the License. .. limitations under the License.
Identity Servic e API
Identity Server API
====================
====================
{{unstable_warning_block_IDENTITY_RELEASE_LABEL}}
{{unstable_warning_block_IDENTITY_RELEASE_LABEL}}
@ -23,7 +23,7 @@ Identity Service API
The Matrix client-server and server-server APIs are largely expressed in Matrix
The Matrix client-server and server-server APIs are largely expressed in Matrix
user identifiers. From time to time, it is useful to refer to users by other
user identifiers. From time to time, it is useful to refer to users by other
("third-party") identifiers, or "3pid"s, e.g. their email address or phone
("third-party") identifiers, or "3pid"s, e.g. their email address or phone
number. This identity servic e specification describes how mappings between
number. This identity server specification describes how mappings between
third-party identifiers and Matrix user identifiers can be established,
third-party identifiers and Matrix user identifiers can be established,
validated, and used. This description technically may apply to any 3pid, but in
validated, and used. This description technically may apply to any 3pid, but in
practice has only been applied specifically to email addresses and phone numbers.
practice has only been applied specifically to email addresses and phone numbers.
@ -35,14 +35,14 @@ Changelog
---------
---------
.. topic :: Version: %IDENTITY_RELEASE_LABEL%.. topic :: Version: %IDENTITY_RELEASE_LABEL%
{{identity_servic e_changelog}}
{{identity_server _changelog}}
This version of the specification is generated from
This version of the specification is generated from
`matrix-doc <https://github.com/matrix-org/matrix-doc> `_ as of Git commit`matrix-doc <https://github.com/matrix-org/matrix-doc> `_ as of Git commit
`{{git_version}} <https://github.com/matrix-org/matrix-doc/tree/{{git_rev}}> `_ .`{{git_version}} <https://github.com/matrix-org/matrix-doc/tree/{{git_rev}}> `_ .
For the full historical changelog, see
For the full historical changelog, see
https://github.com/matrix-org/matrix-doc/blob/master/changelogs/identity_servic e.rst
https://github.com/matrix-org/matrix-doc/blob/master/changelogs/identity_server .rst
Other versions of this specification
Other versions of this specification
@ -50,25 +50,25 @@ Other versions of this specification
The following other versions are also available, in reverse chronological order:
The following other versions are also available, in reverse chronological order:
- `HEAD <https://matrix.org/docs/spec/identity_serv ic e/unstable.html>`_ : Includes all changes since the latest versioned release.
- `HEAD <https://matrix.org/docs/spec/identity_serv er /unstable.html>`_ : Includes all changes since the latest versioned release.
General principles
General principles
------------------
------------------
The purpose of an identity servic e 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
exist on different systems (such as email addresses, phone numbers,
exist on different systems (such as email addresses, phone numbers,
Matrix user IDs, etc).
Matrix user IDs, etc).
The identity servic e has some private-public keypairs. When asked about an
The identity server has some private-public keypairs. When asked about an
association, it will sign details of the association with its private key.
association, it will sign details of the association with its private key.
Clients may validate the assertions about associations by verifying the signature
Clients may validate the assertions about associations by verifying the signature
with the public key of the identity servic e.
with the public key of the identity server .
In general, identity servic es are treated as reliable oracles. They do not
In general, identity server s are treated as reliable oracles. They do not
necessarily provide evidence that they have validated associations, but claim to
necessarily provide evidence that they have validated associations, but claim to
have done so. Establishing the trustworthiness of an individual identity servic e
have done so. Establishing the trustworthiness of an individual identity server
is left as an exercise for the client.
is left as an exercise for the client.
3PID types are described in `3PID Types`_ Appendix.
3PID types are described in `3PID Types`_ Appendix.
@ -76,7 +76,7 @@ is left as an exercise for the client.
API standards
API standards
-------------
-------------
The mandatory baseline for identity servic e communication in Matrix is exchanging
The mandatory baseline for identity server communication in Matrix is exchanging
JSON objects over HTTP APIs. HTTPS is required for communication, and all API calls
JSON objects over HTTP APIs. HTTPS is required for communication, and all API calls
use a Content-Type of `` application/json `` . In addition, strings MUST be encoded as
use a Content-Type of `` application/json `` . In addition, strings MUST be encoded as
UTF-8.
UTF-8.
@ -145,7 +145,7 @@ Some standard error codes are below:
Privacy
Privacy
-------
-------
Identity is a privacy-sensitive issue. While the identity servic e exists to
Identity is a privacy-sensitive issue. While the identity server exists to
provide identity information, access should be restricted to avoid leaking
provide identity information, access should be restricted to avoid leaking
potentially sensitive data. In particular, being able to construct large-scale
potentially sensitive data. In particular, being able to construct large-scale
connections between identities should be avoided. To this end, in general APIs
connections between identities should be avoided. To this end, in general APIs
@ -157,7 +157,7 @@ Web browser clients
-------------------
-------------------
It is realistic to expect that some clients will be written to be run within a web
It is realistic to expect that some clients will be written to be run within a web
browser or similar environment. In these cases, the identity servic e should respond to
browser or similar environment. In these cases, the identity server should respond to
pre-flight requests and supply Cross-Origin Resource Sharing (CORS) headers on all
pre-flight requests and supply Cross-Origin Resource Sharing (CORS) headers on all
requests.
requests.
@ -177,17 +177,17 @@ Status check
Key management
Key management
--------------
--------------
An identity servic e has some long-term public-private keypairs. These are named
An identity server has some long-term public-private keypairs. These are named
in a scheme `` algorithm:identifier `` , e.g. `` ed25519:0 `` . When signing an
in a scheme `` algorithm:identifier `` , e.g. `` ed25519:0 `` . When signing an
association, the standard `Signing JSON`_ algorithm applies.
association, the standard `Signing JSON`_ algorithm applies.
.. TODO: Actually allow identity serv ic es to revoke all keys.. TODO: Actually allow identity serv er s to revoke all keys
See: https://github.com/matrix-org/matrix-doc/issues/1633
See: https://github.com/matrix-org/matrix-doc/issues/1633
.. In the event of key compromise, the identity serv ic e may revoke any of its keys... In the event of key compromise, the identity serv er may revoke any of its keys.
An HTTP API is offered to get public keys, and check whether a particular key is
An HTTP API is offered to get public keys, and check whether a particular key is
valid.
valid.
The identity servic e may also keep track of some short-term public-private
The identity server may also keep track of some short-term public-private
keypairs, which may have different usage and lifetime characteristics than the
keypairs, which may have different usage and lifetime characteristics than the
service's long-term keys.
service's long-term keys.
@ -241,14 +241,14 @@ General
Invitation storage
Invitation storage
------------------
------------------
An identity servic e can store pending invitations to a user's 3pid, which will
An identity server can store pending invitations to a user's 3pid, which will
be retrieved and can be either notified on or look up when the 3pid is
be retrieved and can be either notified on or look up when the 3pid is
associated with a Matrix user ID.
associated with a Matrix user ID.
At a later point, if the owner of that particular 3pid binds it with a Matrix user
At a later point, if the owner of that particular 3pid binds it with a Matrix user
ID, the identity servic e will attempt to make an HTTP POST to the Matrix user's
ID, the identity server will attempt to make an HTTP POST to the Matrix user's
homeserver via the `/3pid/onbind`_ endpoint. The request MUST be signed with a
homeserver via the `/3pid/onbind`_ endpoint. The request MUST be signed with a
long-term private key for the identity servic e.
long-term private key for the identity server .
{{store_invite_is_http_api}}
{{store_invite_is_http_api}}
Travis Ralston
6 years ago