Improve the sample config for SSO (OIDC, SAML, and CAS). (#8635)

This commit is contained in:
Patrick Cloke 2020-10-30 10:01:59 -04:00 committed by GitHub
parent cbc82aa09f
commit 8f1aefa694
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
5 changed files with 157 additions and 104 deletions

1
changelog.d/8635.doc Normal file
View File

@ -0,0 +1 @@
Improve the sample configuration for single sign-on providers.

View File

@ -1505,10 +1505,8 @@ trusted_key_servers:
## Single sign-on integration ## ## Single sign-on integration ##
# Enable SAML2 for registration and login. Uses pysaml2. # The following settings can be used to make Synapse use a single sign-on
# # provider for authentication, instead of its internal password database.
# At least one of `sp_config` or `config_path` must be set in this section to
# enable SAML login.
# #
# You will probably also want to set the following options to `false` to # You will probably also want to set the following options to `false` to
# disable the regular login/registration flows: # disable the regular login/registration flows:
@ -1517,6 +1515,11 @@ trusted_key_servers:
# #
# You will also want to investigate the settings under the "sso" configuration # You will also want to investigate the settings under the "sso" configuration
# section below. # section below.
# Enable SAML2 for registration and login. Uses pysaml2.
#
# At least one of `sp_config` or `config_path` must be set in this section to
# enable SAML login.
# #
# Once SAML support is enabled, a metadata file will be exposed at # Once SAML support is enabled, a metadata file will be exposed at
# https://<server>:<port>/_matrix/saml2/metadata.xml, which you may be able to # https://<server>:<port>/_matrix/saml2/metadata.xml, which you may be able to
@ -1532,40 +1535,42 @@ saml2_config:
# so it is not normally necessary to specify them unless you need to # so it is not normally necessary to specify them unless you need to
# override them. # override them.
# #
#sp_config: sp_config:
# # point this to the IdP's metadata. You can use either a local file or # Point this to the IdP's metadata. You must provide either a local
# # (preferably) a URL. # file via the `local` attribute or (preferably) a URL via the
# metadata: # `remote` attribute.
# #local: ["saml2/idp.xml"] #
# remote: #metadata:
# - url: https://our_idp/metadata.xml # local: ["saml2/idp.xml"]
# # remote:
# # By default, the user has to go to our login page first. If you'd like # - url: https://our_idp/metadata.xml
# # to allow IdP-initiated login, set 'allow_unsolicited: true' in a
# # 'service.sp' section: # By default, the user has to go to our login page first. If you'd like
# # # to allow IdP-initiated login, set 'allow_unsolicited: true' in a
# #service: # 'service.sp' section:
# # sp: #
# # allow_unsolicited: true #service:
# # sp:
# # The examples below are just used to generate our metadata xml, and you # allow_unsolicited: true
# # may well not need them, depending on your setup. Alternatively you
# # may need a whole lot more detail - see the pysaml2 docs! # The examples below are just used to generate our metadata xml, and you
# # may well not need them, depending on your setup. Alternatively you
# description: ["My awesome SP", "en"] # may need a whole lot more detail - see the pysaml2 docs!
# name: ["Test SP", "en"]
# #description: ["My awesome SP", "en"]
# organization: #name: ["Test SP", "en"]
# name: Example com
# display_name: #organization:
# - ["Example co", "en"] # name: Example com
# url: "http://example.com" # display_name:
# # - ["Example co", "en"]
# contact_person: # url: "http://example.com"
# - given_name: Bob
# sur_name: "the Sysadmin" #contact_person:
# email_address": ["admin@example.com"] # - given_name: Bob
# contact_type": technical # sur_name: "the Sysadmin"
# email_address": ["admin@example.com"]
# contact_type": technical
# Instead of putting the config inline as above, you can specify a # Instead of putting the config inline as above, you can specify a
# separate pysaml2 configuration file: # separate pysaml2 configuration file:
@ -1641,11 +1646,10 @@ saml2_config:
# value: "sales" # value: "sales"
# OpenID Connect integration. The following settings can be used to make Synapse # Enable OpenID Connect (OIDC) / OAuth 2.0 for registration and login.
# use an OpenID Connect Provider for authentication, instead of its internal
# password database.
# #
# See https://github.com/matrix-org/synapse/blob/master/docs/openid.md. # See https://github.com/matrix-org/synapse/blob/master/docs/openid.md
# for some example configurations.
# #
oidc_config: oidc_config:
# Uncomment the following to enable authorization against an OpenID Connect # Uncomment the following to enable authorization against an OpenID Connect
@ -1778,15 +1782,37 @@ oidc_config:
# Enable CAS for registration and login. # Enable Central Authentication Service (CAS) for registration and login.
# #
#cas_config: cas_config:
# enabled: true # Uncomment the following to enable authorization against a CAS server.
# server_url: "https://cas-server.com" # Defaults to false.
# service_url: "https://homeserver.domain.com:8448" #
# #displayname_attribute: name #enabled: true
# #required_attributes:
# # name: value # The URL of the CAS authorization endpoint.
#
#server_url: "https://cas-server.com"
# The public URL of the homeserver.
#
#service_url: "https://homeserver.domain.com:8448"
# The attribute of the CAS response to use as the display name.
#
# If unset, no displayname will be set.
#
#displayname_attribute: name
# It is possible to configure Synapse to only allow logins if CAS attributes
# match particular values. All of the keys in the mapping below must exist
# and the values must match the given value. Alternately if the given value
# is None then any value is allowed (the attribute just must exist).
# All of the listed attributes must match for the login to be permitted.
#
#required_attributes:
# userGroup: "staff"
# department: None
# Additional settings to use with single-sign on systems such as OpenID Connect, # Additional settings to use with single-sign on systems such as OpenID Connect,

View File

@ -26,14 +26,14 @@ class CasConfig(Config):
def read_config(self, config, **kwargs): def read_config(self, config, **kwargs):
cas_config = config.get("cas_config", None) cas_config = config.get("cas_config", None)
if cas_config: self.cas_enabled = cas_config and cas_config.get("enabled", True)
self.cas_enabled = cas_config.get("enabled", True)
if self.cas_enabled:
self.cas_server_url = cas_config["server_url"] self.cas_server_url = cas_config["server_url"]
self.cas_service_url = cas_config["service_url"] self.cas_service_url = cas_config["service_url"]
self.cas_displayname_attribute = cas_config.get("displayname_attribute") self.cas_displayname_attribute = cas_config.get("displayname_attribute")
self.cas_required_attributes = cas_config.get("required_attributes", {}) self.cas_required_attributes = cas_config.get("required_attributes") or {}
else: else:
self.cas_enabled = False
self.cas_server_url = None self.cas_server_url = None
self.cas_service_url = None self.cas_service_url = None
self.cas_displayname_attribute = None self.cas_displayname_attribute = None
@ -41,13 +41,35 @@ class CasConfig(Config):
def generate_config_section(self, config_dir_path, server_name, **kwargs): def generate_config_section(self, config_dir_path, server_name, **kwargs):
return """ return """
# Enable CAS for registration and login. # Enable Central Authentication Service (CAS) for registration and login.
# #
#cas_config: cas_config:
# enabled: true # Uncomment the following to enable authorization against a CAS server.
# server_url: "https://cas-server.com" # Defaults to false.
# service_url: "https://homeserver.domain.com:8448" #
# #displayname_attribute: name #enabled: true
# #required_attributes:
# # name: value # The URL of the CAS authorization endpoint.
#
#server_url: "https://cas-server.com"
# The public URL of the homeserver.
#
#service_url: "https://homeserver.domain.com:8448"
# The attribute of the CAS response to use as the display name.
#
# If unset, no displayname will be set.
#
#displayname_attribute: name
# It is possible to configure Synapse to only allow logins if CAS attributes
# match particular values. All of the keys in the mapping below must exist
# and the values must match the given value. Alternately if the given value
# is None then any value is allowed (the attribute just must exist).
# All of the listed attributes must match for the login to be permitted.
#
#required_attributes:
# userGroup: "staff"
# department: None
""" """

View File

@ -87,11 +87,10 @@ class OIDCConfig(Config):
def generate_config_section(self, config_dir_path, server_name, **kwargs): def generate_config_section(self, config_dir_path, server_name, **kwargs):
return """\ return """\
# OpenID Connect integration. The following settings can be used to make Synapse # Enable OpenID Connect (OIDC) / OAuth 2.0 for registration and login.
# use an OpenID Connect Provider for authentication, instead of its internal
# password database.
# #
# See https://github.com/matrix-org/synapse/blob/master/docs/openid.md. # See https://github.com/matrix-org/synapse/blob/master/docs/openid.md
# for some example configurations.
# #
oidc_config: oidc_config:
# Uncomment the following to enable authorization against an OpenID Connect # Uncomment the following to enable authorization against an OpenID Connect

View File

@ -216,10 +216,8 @@ class SAML2Config(Config):
return """\ return """\
## Single sign-on integration ## ## Single sign-on integration ##
# Enable SAML2 for registration and login. Uses pysaml2. # The following settings can be used to make Synapse use a single sign-on
# # provider for authentication, instead of its internal password database.
# At least one of `sp_config` or `config_path` must be set in this section to
# enable SAML login.
# #
# You will probably also want to set the following options to `false` to # You will probably also want to set the following options to `false` to
# disable the regular login/registration flows: # disable the regular login/registration flows:
@ -228,6 +226,11 @@ class SAML2Config(Config):
# #
# You will also want to investigate the settings under the "sso" configuration # You will also want to investigate the settings under the "sso" configuration
# section below. # section below.
# Enable SAML2 for registration and login. Uses pysaml2.
#
# At least one of `sp_config` or `config_path` must be set in this section to
# enable SAML login.
# #
# Once SAML support is enabled, a metadata file will be exposed at # Once SAML support is enabled, a metadata file will be exposed at
# https://<server>:<port>/_matrix/saml2/metadata.xml, which you may be able to # https://<server>:<port>/_matrix/saml2/metadata.xml, which you may be able to
@ -243,40 +246,42 @@ class SAML2Config(Config):
# so it is not normally necessary to specify them unless you need to # so it is not normally necessary to specify them unless you need to
# override them. # override them.
# #
#sp_config: sp_config:
# # point this to the IdP's metadata. You can use either a local file or # Point this to the IdP's metadata. You must provide either a local
# # (preferably) a URL. # file via the `local` attribute or (preferably) a URL via the
# metadata: # `remote` attribute.
# #local: ["saml2/idp.xml"] #
# remote: #metadata:
# - url: https://our_idp/metadata.xml # local: ["saml2/idp.xml"]
# # remote:
# # By default, the user has to go to our login page first. If you'd like # - url: https://our_idp/metadata.xml
# # to allow IdP-initiated login, set 'allow_unsolicited: true' in a
# # 'service.sp' section: # By default, the user has to go to our login page first. If you'd like
# # # to allow IdP-initiated login, set 'allow_unsolicited: true' in a
# #service: # 'service.sp' section:
# # sp: #
# # allow_unsolicited: true #service:
# # sp:
# # The examples below are just used to generate our metadata xml, and you # allow_unsolicited: true
# # may well not need them, depending on your setup. Alternatively you
# # may need a whole lot more detail - see the pysaml2 docs! # The examples below are just used to generate our metadata xml, and you
# # may well not need them, depending on your setup. Alternatively you
# description: ["My awesome SP", "en"] # may need a whole lot more detail - see the pysaml2 docs!
# name: ["Test SP", "en"]
# #description: ["My awesome SP", "en"]
# organization: #name: ["Test SP", "en"]
# name: Example com
# display_name: #organization:
# - ["Example co", "en"] # name: Example com
# url: "http://example.com" # display_name:
# # - ["Example co", "en"]
# contact_person: # url: "http://example.com"
# - given_name: Bob
# sur_name: "the Sysadmin" #contact_person:
# email_address": ["admin@example.com"] # - given_name: Bob
# contact_type": technical # sur_name: "the Sysadmin"
# email_address": ["admin@example.com"]
# contact_type": technical
# Instead of putting the config inline as above, you can specify a # Instead of putting the config inline as above, you can specify a
# separate pysaml2 configuration file: # separate pysaml2 configuration file: