123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570 |
- # -*- coding: utf-8 -*-
- # Copyright 2020 Quentin Gliech
- # Copyright 2020-2021 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.
- from collections import Counter
- from typing import Iterable, Mapping, Optional, Tuple, Type
- import attr
- from synapse.config._util import validate_config
- from synapse.python_dependencies import DependencyException, check_requirements
- from synapse.types import Collection, JsonDict
- from synapse.util.module_loader import load_module
- from synapse.util.stringutils import parse_and_validate_mxc_uri
- from ._base import Config, ConfigError, read_file
- DEFAULT_USER_MAPPING_PROVIDER = "synapse.handlers.oidc_handler.JinjaOidcMappingProvider"
- class OIDCConfig(Config):
- section = "oidc"
- def read_config(self, config, **kwargs):
- self.oidc_providers = tuple(_parse_oidc_provider_configs(config))
- if not self.oidc_providers:
- return
- try:
- check_requirements("oidc")
- except DependencyException as e:
- raise ConfigError(e.message) from e
- # check we don't have any duplicate idp_ids now. (The SSO handler will also
- # check for duplicates when the REST listeners get registered, but that happens
- # after synapse has forked so doesn't give nice errors.)
- c = Counter([i.idp_id for i in self.oidc_providers])
- for idp_id, count in c.items():
- if count > 1:
- raise ConfigError(
- "Multiple OIDC providers have the idp_id %r." % idp_id
- )
- public_baseurl = self.public_baseurl
- if public_baseurl is None:
- raise ConfigError("oidc_config requires a public_baseurl to be set")
- self.oidc_callback_url = public_baseurl + "_synapse/client/oidc/callback"
- @property
- def oidc_enabled(self) -> bool:
- # OIDC is enabled if we have a provider
- return bool(self.oidc_providers)
- def generate_config_section(self, config_dir_path, server_name, **kwargs):
- return """\
- # List of OpenID Connect (OIDC) / OAuth 2.0 identity providers, for registration
- # and login.
- #
- # Options for each entry include:
- #
- # idp_id: a unique identifier for this identity provider. Used internally
- # by Synapse; should be a single word such as 'github'.
- #
- # Note that, if this is changed, users authenticating via that provider
- # will no longer be recognised as the same user!
- #
- # idp_name: A user-facing name for this identity provider, which is used to
- # offer the user a choice of login mechanisms.
- #
- # idp_icon: An optional icon for this identity provider, which is presented
- # by clients and Synapse's own IdP picker page. If given, must be an
- # MXC URI of the format mxc://<server-name>/<media-id>. (An easy way to
- # obtain such an MXC URI is to upload an image to an (unencrypted) room
- # and then copy the "url" from the source of the event.)
- #
- # idp_brand: An optional brand for this identity provider, allowing clients
- # to style the login flow according to the identity provider in question.
- # See the spec for possible options here.
- #
- # discover: set to 'false' to disable the use of the OIDC discovery mechanism
- # to discover endpoints. Defaults to true.
- #
- # issuer: Required. The OIDC issuer. Used to validate tokens and (if discovery
- # is enabled) to discover the provider's endpoints.
- #
- # client_id: Required. oauth2 client id to use.
- #
- # client_secret: oauth2 client secret to use. May be omitted if
- # client_secret_jwt_key is given, or if client_auth_method is 'none'.
- #
- # client_secret_jwt_key: Alternative to client_secret: details of a key used
- # to create a JSON Web Token to be used as an OAuth2 client secret. If
- # given, must be a dictionary with the following properties:
- #
- # key: a pem-encoded signing key. Must be a suitable key for the
- # algorithm specified. Required unless 'key_file' is given.
- #
- # key_file: the path to file containing a pem-encoded signing key file.
- # Required unless 'key' is given.
- #
- # jwt_header: a dictionary giving properties to include in the JWT
- # header. Must include the key 'alg', giving the algorithm used to
- # sign the JWT, such as "ES256", using the JWA identifiers in
- # RFC7518.
- #
- # jwt_payload: an optional dictionary giving properties to include in
- # the JWT payload. Normally this should include an 'iss' key.
- #
- # client_auth_method: auth method to use when exchanging the token. Valid
- # values are 'client_secret_basic' (default), 'client_secret_post' and
- # 'none'.
- #
- # scopes: list of scopes to request. This should normally include the "openid"
- # scope. Defaults to ["openid"].
- #
- # authorization_endpoint: the oauth2 authorization endpoint. Required if
- # provider discovery is disabled.
- #
- # token_endpoint: the oauth2 token endpoint. Required if provider discovery is
- # disabled.
- #
- # userinfo_endpoint: the OIDC userinfo endpoint. Required if discovery is
- # disabled and the 'openid' scope is not requested.
- #
- # jwks_uri: URI where to fetch the JWKS. Required if discovery is disabled and
- # the 'openid' scope is used.
- #
- # skip_verification: set to 'true' to skip metadata verification. Use this if
- # you are connecting to a provider that is not OpenID Connect compliant.
- # Defaults to false. Avoid this in production.
- #
- # user_profile_method: Whether to fetch the user profile from the userinfo
- # endpoint. Valid values are: 'auto' or 'userinfo_endpoint'.
- #
- # Defaults to 'auto', which fetches the userinfo endpoint if 'openid' is
- # included in 'scopes'. Set to 'userinfo_endpoint' to always fetch the
- # userinfo endpoint.
- #
- # allow_existing_users: set to 'true' to allow a user logging in via OIDC to
- # match a pre-existing account instead of failing. This could be used if
- # switching from password logins to OIDC. Defaults to false.
- #
- # user_mapping_provider: Configuration for how attributes returned from a OIDC
- # provider are mapped onto a matrix user. This setting has the following
- # sub-properties:
- #
- # module: The class name of a custom mapping module. Default is
- # {mapping_provider!r}.
- # See https://github.com/matrix-org/synapse/blob/master/docs/sso_mapping_providers.md#openid-mapping-providers
- # for information on implementing a custom mapping provider.
- #
- # config: Configuration for the mapping provider module. This section will
- # be passed as a Python dictionary to the user mapping provider
- # module's `parse_config` method.
- #
- # For the default provider, the following settings are available:
- #
- # subject_claim: name of the claim containing a unique identifier
- # for the user. Defaults to 'sub', which OpenID Connect
- # compliant providers should provide.
- #
- # localpart_template: Jinja2 template for the localpart of the MXID.
- # If this is not set, the user will be prompted to choose their
- # own username (see 'sso_auth_account_details.html' in the 'sso'
- # section of this file).
- #
- # display_name_template: Jinja2 template for the display name to set
- # on first login. If unset, no displayname will be set.
- #
- # email_template: Jinja2 template for the email address of the user.
- # If unset, no email address will be added to the account.
- #
- # extra_attributes: a map of Jinja2 templates for extra attributes
- # to send back to the client during login.
- # Note that these are non-standard and clients will ignore them
- # without modifications.
- #
- # When rendering, the Jinja2 templates are given a 'user' variable,
- # which is set to the claims returned by the UserInfo Endpoint and/or
- # in the ID Token.
- #
- # See https://github.com/matrix-org/synapse/blob/master/docs/openid.md
- # for information on how to configure these options.
- #
- # For backwards compatibility, it is also possible to configure a single OIDC
- # provider via an 'oidc_config' setting. This is now deprecated and admins are
- # advised to migrate to the 'oidc_providers' format. (When doing that migration,
- # use 'oidc' for the idp_id to ensure that existing users continue to be
- # recognised.)
- #
- oidc_providers:
- # Generic example
- #
- #- idp_id: my_idp
- # idp_name: "My OpenID provider"
- # idp_icon: "mxc://example.com/mediaid"
- # discover: false
- # issuer: "https://accounts.example.com/"
- # client_id: "provided-by-your-issuer"
- # client_secret: "provided-by-your-issuer"
- # client_auth_method: client_secret_post
- # scopes: ["openid", "profile"]
- # authorization_endpoint: "https://accounts.example.com/oauth2/auth"
- # token_endpoint: "https://accounts.example.com/oauth2/token"
- # userinfo_endpoint: "https://accounts.example.com/userinfo"
- # jwks_uri: "https://accounts.example.com/.well-known/jwks.json"
- # skip_verification: true
- # user_mapping_provider:
- # config:
- # subject_claim: "id"
- # localpart_template: "{{{{ user.login }}}}"
- # display_name_template: "{{{{ user.name }}}}"
- # email_template: "{{{{ user.email }}}}"
- # For use with Keycloak
- #
- #- idp_id: keycloak
- # idp_name: Keycloak
- # issuer: "https://127.0.0.1:8443/auth/realms/my_realm_name"
- # client_id: "synapse"
- # client_secret: "copy secret generated in Keycloak UI"
- # scopes: ["openid", "profile"]
- # For use with Github
- #
- #- idp_id: github
- # idp_name: Github
- # idp_brand: org.matrix.github
- # discover: false
- # issuer: "https://github.com/"
- # client_id: "your-client-id" # TO BE FILLED
- # client_secret: "your-client-secret" # TO BE FILLED
- # authorization_endpoint: "https://github.com/login/oauth/authorize"
- # token_endpoint: "https://github.com/login/oauth/access_token"
- # userinfo_endpoint: "https://api.github.com/user"
- # scopes: ["read:user"]
- # user_mapping_provider:
- # config:
- # subject_claim: "id"
- # localpart_template: "{{{{ user.login }}}}"
- # display_name_template: "{{{{ user.name }}}}"
- """.format(
- mapping_provider=DEFAULT_USER_MAPPING_PROVIDER
- )
- # jsonschema definition of the configuration settings for an oidc identity provider
- OIDC_PROVIDER_CONFIG_SCHEMA = {
- "type": "object",
- "required": ["issuer", "client_id"],
- "properties": {
- "idp_id": {
- "type": "string",
- "minLength": 1,
- # MSC2858 allows a maxlen of 255, but we prefix with "oidc-"
- "maxLength": 250,
- "pattern": "^[A-Za-z0-9._~-]+$",
- },
- "idp_name": {"type": "string"},
- "idp_icon": {"type": "string"},
- "idp_brand": {
- "type": "string",
- # MSC2758-style namespaced identifier
- "minLength": 1,
- "maxLength": 255,
- "pattern": "^[a-z][a-z0-9_.-]*$",
- },
- "discover": {"type": "boolean"},
- "issuer": {"type": "string"},
- "client_id": {"type": "string"},
- "client_secret": {"type": "string"},
- "client_secret_jwt_key": {
- "type": "object",
- "required": ["jwt_header"],
- "oneOf": [
- {"required": ["key"]},
- {"required": ["key_file"]},
- ],
- "properties": {
- "key": {"type": "string"},
- "key_file": {"type": "string"},
- "jwt_header": {
- "type": "object",
- "required": ["alg"],
- "properties": {
- "alg": {"type": "string"},
- },
- "additionalProperties": {"type": "string"},
- },
- "jwt_payload": {
- "type": "object",
- "additionalProperties": {"type": "string"},
- },
- },
- },
- "client_auth_method": {
- "type": "string",
- # the following list is the same as the keys of
- # authlib.oauth2.auth.ClientAuth.DEFAULT_AUTH_METHODS. We inline it
- # to avoid importing authlib here.
- "enum": ["client_secret_basic", "client_secret_post", "none"],
- },
- "scopes": {"type": "array", "items": {"type": "string"}},
- "authorization_endpoint": {"type": "string"},
- "token_endpoint": {"type": "string"},
- "userinfo_endpoint": {"type": "string"},
- "jwks_uri": {"type": "string"},
- "skip_verification": {"type": "boolean"},
- "user_profile_method": {
- "type": "string",
- "enum": ["auto", "userinfo_endpoint"],
- },
- "allow_existing_users": {"type": "boolean"},
- "user_mapping_provider": {"type": ["object", "null"]},
- },
- }
- # the same as OIDC_PROVIDER_CONFIG_SCHEMA, but with compulsory idp_id and idp_name
- OIDC_PROVIDER_CONFIG_WITH_ID_SCHEMA = {
- "allOf": [OIDC_PROVIDER_CONFIG_SCHEMA, {"required": ["idp_id", "idp_name"]}]
- }
- # the `oidc_providers` list can either be None (as it is in the default config), or
- # a list of provider configs, each of which requires an explicit ID and name.
- OIDC_PROVIDER_LIST_SCHEMA = {
- "oneOf": [
- {"type": "null"},
- {"type": "array", "items": OIDC_PROVIDER_CONFIG_WITH_ID_SCHEMA},
- ]
- }
- # the `oidc_config` setting can either be None (which it used to be in the default
- # config), or an object. If an object, it is ignored unless it has an "enabled: True"
- # property.
- #
- # It's *possible* to represent this with jsonschema, but the resultant errors aren't
- # particularly clear, so we just check for either an object or a null here, and do
- # additional checks in the code.
- OIDC_CONFIG_SCHEMA = {"oneOf": [{"type": "null"}, {"type": "object"}]}
- # the top-level schema can contain an "oidc_config" and/or an "oidc_providers".
- MAIN_CONFIG_SCHEMA = {
- "type": "object",
- "properties": {
- "oidc_config": OIDC_CONFIG_SCHEMA,
- "oidc_providers": OIDC_PROVIDER_LIST_SCHEMA,
- },
- }
- def _parse_oidc_provider_configs(config: JsonDict) -> Iterable["OidcProviderConfig"]:
- """extract and parse the OIDC provider configs from the config dict
- The configuration may contain either a single `oidc_config` object with an
- `enabled: True` property, or a list of provider configurations under
- `oidc_providers`, *or both*.
- Returns a generator which yields the OidcProviderConfig objects
- """
- validate_config(MAIN_CONFIG_SCHEMA, config, ())
- for i, p in enumerate(config.get("oidc_providers") or []):
- yield _parse_oidc_config_dict(p, ("oidc_providers", "<item %i>" % (i,)))
- # for backwards-compatibility, it is also possible to provide a single "oidc_config"
- # object with an "enabled: True" property.
- oidc_config = config.get("oidc_config")
- if oidc_config and oidc_config.get("enabled", False):
- # MAIN_CONFIG_SCHEMA checks that `oidc_config` is an object, but not that
- # it matches OIDC_PROVIDER_CONFIG_SCHEMA (see the comments on OIDC_CONFIG_SCHEMA
- # above), so now we need to validate it.
- validate_config(OIDC_PROVIDER_CONFIG_SCHEMA, oidc_config, ("oidc_config",))
- yield _parse_oidc_config_dict(oidc_config, ("oidc_config",))
- def _parse_oidc_config_dict(
- oidc_config: JsonDict, config_path: Tuple[str, ...]
- ) -> "OidcProviderConfig":
- """Take the configuration dict and parse it into an OidcProviderConfig
- Raises:
- ConfigError if the configuration is malformed.
- """
- ump_config = oidc_config.get("user_mapping_provider", {})
- ump_config.setdefault("module", DEFAULT_USER_MAPPING_PROVIDER)
- ump_config.setdefault("config", {})
- (
- user_mapping_provider_class,
- user_mapping_provider_config,
- ) = load_module(ump_config, config_path + ("user_mapping_provider",))
- # Ensure loaded user mapping module has defined all necessary methods
- required_methods = [
- "get_remote_user_id",
- "map_user_attributes",
- ]
- missing_methods = [
- method
- for method in required_methods
- if not hasattr(user_mapping_provider_class, method)
- ]
- if missing_methods:
- raise ConfigError(
- "Class %s is missing required "
- "methods: %s"
- % (
- user_mapping_provider_class,
- ", ".join(missing_methods),
- ),
- config_path + ("user_mapping_provider", "module"),
- )
- idp_id = oidc_config.get("idp_id", "oidc")
- # prefix the given IDP with a prefix specific to the SSO mechanism, to avoid
- # clashes with other mechs (such as SAML, CAS).
- #
- # We allow "oidc" as an exception so that people migrating from old-style
- # "oidc_config" format (which has long used "oidc" as its idp_id) can migrate to
- # a new-style "oidc_providers" entry without changing the idp_id for their provider
- # (and thereby invalidating their user_external_ids data).
- if idp_id != "oidc":
- idp_id = "oidc-" + idp_id
- # MSC2858 also specifies that the idp_icon must be a valid MXC uri
- idp_icon = oidc_config.get("idp_icon")
- if idp_icon is not None:
- try:
- parse_and_validate_mxc_uri(idp_icon)
- except ValueError as e:
- raise ConfigError(
- "idp_icon must be a valid MXC URI", config_path + ("idp_icon",)
- ) from e
- client_secret_jwt_key_config = oidc_config.get("client_secret_jwt_key")
- client_secret_jwt_key = None # type: Optional[OidcProviderClientSecretJwtKey]
- if client_secret_jwt_key_config is not None:
- keyfile = client_secret_jwt_key_config.get("key_file")
- if keyfile:
- key = read_file(keyfile, config_path + ("client_secret_jwt_key",))
- else:
- key = client_secret_jwt_key_config["key"]
- client_secret_jwt_key = OidcProviderClientSecretJwtKey(
- key=key,
- jwt_header=client_secret_jwt_key_config["jwt_header"],
- jwt_payload=client_secret_jwt_key_config.get("jwt_payload", {}),
- )
- return OidcProviderConfig(
- idp_id=idp_id,
- idp_name=oidc_config.get("idp_name", "OIDC"),
- idp_icon=idp_icon,
- idp_brand=oidc_config.get("idp_brand"),
- discover=oidc_config.get("discover", True),
- issuer=oidc_config["issuer"],
- client_id=oidc_config["client_id"],
- client_secret=oidc_config.get("client_secret"),
- client_secret_jwt_key=client_secret_jwt_key,
- client_auth_method=oidc_config.get("client_auth_method", "client_secret_basic"),
- scopes=oidc_config.get("scopes", ["openid"]),
- authorization_endpoint=oidc_config.get("authorization_endpoint"),
- token_endpoint=oidc_config.get("token_endpoint"),
- userinfo_endpoint=oidc_config.get("userinfo_endpoint"),
- jwks_uri=oidc_config.get("jwks_uri"),
- skip_verification=oidc_config.get("skip_verification", False),
- user_profile_method=oidc_config.get("user_profile_method", "auto"),
- allow_existing_users=oidc_config.get("allow_existing_users", False),
- user_mapping_provider_class=user_mapping_provider_class,
- user_mapping_provider_config=user_mapping_provider_config,
- )
- @attr.s(slots=True, frozen=True)
- class OidcProviderClientSecretJwtKey:
- # a pem-encoded signing key
- key = attr.ib(type=str)
- # properties to include in the JWT header
- jwt_header = attr.ib(type=Mapping[str, str])
- # properties to include in the JWT payload.
- jwt_payload = attr.ib(type=Mapping[str, str])
- @attr.s(slots=True, frozen=True)
- class OidcProviderConfig:
- # a unique identifier for this identity provider. Used in the 'user_external_ids'
- # table, as well as the query/path parameter used in the login protocol.
- idp_id = attr.ib(type=str)
- # user-facing name for this identity provider.
- idp_name = attr.ib(type=str)
- # Optional MXC URI for icon for this IdP.
- idp_icon = attr.ib(type=Optional[str])
- # Optional brand identifier for this IdP.
- idp_brand = attr.ib(type=Optional[str])
- # whether the OIDC discovery mechanism is used to discover endpoints
- discover = attr.ib(type=bool)
- # the OIDC issuer. Used to validate tokens and (if discovery is enabled) to
- # discover the provider's endpoints.
- issuer = attr.ib(type=str)
- # oauth2 client id to use
- client_id = attr.ib(type=str)
- # oauth2 client secret to use. if `None`, use client_secret_jwt_key to generate
- # a secret.
- client_secret = attr.ib(type=Optional[str])
- # key to use to construct a JWT to use as a client secret. May be `None` if
- # `client_secret` is set.
- client_secret_jwt_key = attr.ib(type=Optional[OidcProviderClientSecretJwtKey])
- # auth method to use when exchanging the token.
- # Valid values are 'client_secret_basic', 'client_secret_post' and
- # 'none'.
- client_auth_method = attr.ib(type=str)
- # list of scopes to request
- scopes = attr.ib(type=Collection[str])
- # the oauth2 authorization endpoint. Required if discovery is disabled.
- authorization_endpoint = attr.ib(type=Optional[str])
- # the oauth2 token endpoint. Required if discovery is disabled.
- token_endpoint = attr.ib(type=Optional[str])
- # the OIDC userinfo endpoint. Required if discovery is disabled and the
- # "openid" scope is not requested.
- userinfo_endpoint = attr.ib(type=Optional[str])
- # URI where to fetch the JWKS. Required if discovery is disabled and the
- # "openid" scope is used.
- jwks_uri = attr.ib(type=Optional[str])
- # Whether to skip metadata verification
- skip_verification = attr.ib(type=bool)
- # Whether to fetch the user profile from the userinfo endpoint. Valid
- # values are: "auto" or "userinfo_endpoint".
- user_profile_method = attr.ib(type=str)
- # whether to allow a user logging in via OIDC to match a pre-existing account
- # instead of failing
- allow_existing_users = attr.ib(type=bool)
- # the class of the user mapping provider
- user_mapping_provider_class = attr.ib(type=Type)
- # the config of the user mapping provider
- user_mapping_provider_config = attr.ib()
|