Clarify SSO mapping provider documentation by writing def or async def before the names of methods, as appropriate. (#11681)

This commit is contained in:
reivilibre 2022-01-05 11:25:32 +00:00 committed by GitHub
parent 7013e06e2f
commit 84d790a32e
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 13 additions and 12 deletions

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

@ -0,0 +1 @@
Clarify SSO mapping provider documentation by writing `def` or `async def` before the names of methods, as appropriate.

View File

@ -49,12 +49,12 @@ comment these options out and use those specified by the module instead.
A custom mapping provider must specify the following methods: A custom mapping provider must specify the following methods:
* `__init__(self, parsed_config)` * `def __init__(self, parsed_config)`
- Arguments: - Arguments:
- `parsed_config` - A configuration object that is the return value of the - `parsed_config` - A configuration object that is the return value of the
`parse_config` method. You should set any configuration options needed by `parse_config` method. You should set any configuration options needed by
the module here. the module here.
* `parse_config(config)` * `def parse_config(config)`
- This method should have the `@staticmethod` decoration. - This method should have the `@staticmethod` decoration.
- Arguments: - Arguments:
- `config` - A `dict` representing the parsed content of the - `config` - A `dict` representing the parsed content of the
@ -63,13 +63,13 @@ A custom mapping provider must specify the following methods:
any option values they need here. any option values they need here.
- Whatever is returned will be passed back to the user mapping provider module's - Whatever is returned will be passed back to the user mapping provider module's
`__init__` method during construction. `__init__` method during construction.
* `get_remote_user_id(self, userinfo)` * `def get_remote_user_id(self, userinfo)`
- Arguments: - Arguments:
- `userinfo` - A `authlib.oidc.core.claims.UserInfo` object to extract user - `userinfo` - A `authlib.oidc.core.claims.UserInfo` object to extract user
information from. information from.
- This method must return a string, which is the unique, immutable identifier - This method must return a string, which is the unique, immutable identifier
for the user. Commonly the `sub` claim of the response. for the user. Commonly the `sub` claim of the response.
* `map_user_attributes(self, userinfo, token, failures)` * `async def map_user_attributes(self, userinfo, token, failures)`
- This method must be async. - This method must be async.
- Arguments: - Arguments:
- `userinfo` - A `authlib.oidc.core.claims.UserInfo` object to extract user - `userinfo` - A `authlib.oidc.core.claims.UserInfo` object to extract user
@ -91,7 +91,7 @@ A custom mapping provider must specify the following methods:
during a user's first login. Once a localpart has been associated with a during a user's first login. Once a localpart has been associated with a
remote user ID (see `get_remote_user_id`) it cannot be updated. remote user ID (see `get_remote_user_id`) it cannot be updated.
- `displayname`: An optional string, the display name for the user. - `displayname`: An optional string, the display name for the user.
* `get_extra_attributes(self, userinfo, token)` * `async def get_extra_attributes(self, userinfo, token)`
- This method must be async. - This method must be async.
- Arguments: - Arguments:
- `userinfo` - A `authlib.oidc.core.claims.UserInfo` object to extract user - `userinfo` - A `authlib.oidc.core.claims.UserInfo` object to extract user
@ -125,15 +125,15 @@ comment these options out and use those specified by the module instead.
A custom mapping provider must specify the following methods: A custom mapping provider must specify the following methods:
* `__init__(self, parsed_config, module_api)` * `def __init__(self, parsed_config, module_api)`
- Arguments: - Arguments:
- `parsed_config` - A configuration object that is the return value of the - `parsed_config` - A configuration object that is the return value of the
`parse_config` method. You should set any configuration options needed by `parse_config` method. You should set any configuration options needed by
the module here. the module here.
- `module_api` - a `synapse.module_api.ModuleApi` object which provides the - `module_api` - a `synapse.module_api.ModuleApi` object which provides the
stable API available for extension modules. stable API available for extension modules.
* `parse_config(config)` * `def parse_config(config)`
- This method should have the `@staticmethod` decoration. - **This method should have the `@staticmethod` decoration.**
- Arguments: - Arguments:
- `config` - A `dict` representing the parsed content of the - `config` - A `dict` representing the parsed content of the
`saml_config.user_mapping_provider.config` homeserver config option. `saml_config.user_mapping_provider.config` homeserver config option.
@ -141,15 +141,15 @@ A custom mapping provider must specify the following methods:
any option values they need here. any option values they need here.
- Whatever is returned will be passed back to the user mapping provider module's - Whatever is returned will be passed back to the user mapping provider module's
`__init__` method during construction. `__init__` method during construction.
* `get_saml_attributes(config)` * `def get_saml_attributes(config)`
- This method should have the `@staticmethod` decoration. - **This method should have the `@staticmethod` decoration.**
- Arguments: - Arguments:
- `config` - A object resulting from a call to `parse_config`. - `config` - A object resulting from a call to `parse_config`.
- Returns a tuple of two sets. The first set equates to the SAML auth - Returns a tuple of two sets. The first set equates to the SAML auth
response attributes that are required for the module to function, whereas response attributes that are required for the module to function, whereas
the second set consists of those attributes which can be used if available, the second set consists of those attributes which can be used if available,
but are not necessary. but are not necessary.
* `get_remote_user_id(self, saml_response, client_redirect_url)` * `def get_remote_user_id(self, saml_response, client_redirect_url)`
- Arguments: - Arguments:
- `saml_response` - A `saml2.response.AuthnResponse` object to extract user - `saml_response` - A `saml2.response.AuthnResponse` object to extract user
information from. information from.
@ -157,7 +157,7 @@ A custom mapping provider must specify the following methods:
redirected to. redirected to.
- This method must return a string, which is the unique, immutable identifier - This method must return a string, which is the unique, immutable identifier
for the user. Commonly the `uid` claim of the response. for the user. Commonly the `uid` claim of the response.
* `saml_response_to_user_attributes(self, saml_response, failures, client_redirect_url)` * `def saml_response_to_user_attributes(self, saml_response, failures, client_redirect_url)`
- Arguments: - Arguments:
- `saml_response` - A `saml2.response.AuthnResponse` object to extract user - `saml_response` - A `saml2.response.AuthnResponse` object to extract user
information from. information from.