add command auth-provider for finding users by their external id on auth provider

[ashfame]

This PR adds support for admin endpoint for finding users by their external id on auth provider, which was added in Synapse v1.68.0

Unlike other endpoints, it requires 2 values:

• auth provider id
• external id for the user

Documentation for this admin api endpoint

Correct usage

$ synadm user auth-provider -p oidc ash
{"user_id": "@ashfame:synapse.dev"}

Incorrect usage

$ synadm user auth-provider ash
You must provide a value for provider using --provider

$ synadm user auth-provider
Usage: synadm user auth-provider [OPTIONS] EXTERNAL_ID
Try 'synadm user auth-provider -h' for help.

Error: Missing argument 'EXTERNAL_ID'.

Looking forward to your feedback!

Subsequent PR to follow up for similar lookup for 3PID that's merged but not released (Coming in Synapse v1.72.0) and then we can evaluate if we should add shortcuts for them under search or something else.

[JOJ0]

Hi, thanks a lot for the submission. Great addition to synadm!

First a high level suggestion / design question: Since both arguments (user, provider) are mandatory, they could be implemented as regular positional arguments or was there a special reason why you designed provider as an optional --option?

In any case (positional argument or --option), the handling of a missing argument can be handled by the Click library already. Pos Args handle it by default, --option you have to set the required flag: https://click.palletsprojects.com/en/7.x/options/#basic-value-options

It's on my todo list to finally write some contribution guidelines and even automate some auto-linting in PR's, so you couldn't possibly have known that: Please try to stay below 79 chars line length and use PEP 8 line continuation methods described in the PEP 8 styleguides.

Here you could shorten / rewrite the first sentence of your docstring so it is obvious to the user what this command is supposed to do. Just shorten it as good as possible so it makes sense and is not cut. A more detailed description can be added after a newline in the docstring.

(synadm) ~/git/ashfame_synadm (user_auth_provider_lookup) $ synadm user 
Usage: synadm user [OPTIONS] COMMAND [ARGS]...

  List, add, modify, deactivate/erase users, reset passwords

Options:
  -h, --help  Show this message and exit.

Commands:
  auth-provider  Finds a user based on their ID (external id) in auth...
  deactivate     Deactivate or gdpr-erase a user.
  details        View details of a user account.
  list           List and search for users
  login          Get an access token for a given user.
  media          List all local media uploaded by a user.
  membership     List all rooms a user is member of.
  modify         Create or modify a local user.
  password       Change a user's password.
  prune-devices  Delete devices and invalidate access tokens of a user.
  search         A shortcut to 'synadm user list -d -g -n <search-term>'.
  shadow-ban     Shadow-ban or unban a user.
  whois          Return information about the active sessions for a
                 specific...
(synadm) ~/git/ashfame_synadm (user_auth_provider_lookup) $ 

Suggestion: Find a user based on their auth-provider ID.

Also, but I'm not quite sure about that one: Do you think it would make sense to reveal some detail about what provider could possibly be in the --help already, so the user doesn't have to search for it in the admin api docs. I get there could possibly be a lot of different things but maybe give some reasonable defaults to start with.

I see you added added parts of this information from the api docs which I think is a good start:

provider - The ID of the authentication provider, as advertised by the GET /_matrix/client/v3/login API in the m.login.sso authentication method.

Maybe point to another synadm command that reveals what m.login.sso tells. I think user details or even user list do that.

[ashfame]

Hi @JOJ0

Thanks for the feedback! My responses are below:

First a high level suggestion / design question: Since both arguments (user, provider) are mandatory, they could be implemented as regular positional arguments or was there a special reason why you designed provider as an optional --option?

Mainly to be explicit about it. Invoking synadm user auth-provider oidc ashfame with 2 arguments like that felt odd. But that's just me. If you think that's more appropriate, I can make that change.

the handling of a missing argument can be handled by the Click library already

Great! I have made that change.

PEP 8 styleguides

Absolutely! I understand. I am pretty new to Python so still learning the ropes here. I have changed this manually by running flake8 locally. Definitely great to have a linter run automatically as you are doing it in #80 and some means of doing it easily automatically would be great, similar to how Synapse does it with poetry run black .

Here you could shorten / rewrite the first sentence of your docstring so it is obvious to the user what this command is supposed to do. Just shorten it as good as possible so it makes sense and is not cut. A more detailed description can be added after a newline in the docstring.

Excellent! Done!

I see you added added parts of this information from the api docs which I think is a good start. Maybe point to another synadm command that reveals what m.login.sso tells. I think user details or even user list do that.

I couldn't find an existing command to add to the description here, so improved the description slightly with an example.

[JOJ0]

First a high level suggestion / design question: Since both arguments (user, provider) are mandatory, they could be implemented as regular positional arguments or was there a special reason why you designed provider as an optional --option?

Mainly to be explicit about it. Invoking synadm user auth-provider oidc ashfame with 2 arguments like that felt odd. But that's just me. If you think that's more appropriate, I can make that change.

It's ok, I was not sure what's the best way either. We have mandatory --options somewhere else in synadm already, but there it's because you have to have at least one of many --option value things. I do agree that it looks a little odd, so I let the decisision with you what feels best for this command :-)

One new idea though, not sure if it makes sense: Could oidc be the default value vor --provider Does that make sense? Is it a very likely option. Also I just read this, which states something about a default mapping provider: https://matrix-org.github.io/synapse/latest/sso_mapping_providers.html#default-saml-mapping-provider

You could rename EXTERNAL_ID to EXTERNAL_USER_ID, it would clarify even more what the argument is about:

(synadm) ~/git/ashfame_synadm (user_auth_provider_lookup) $ synadm user auth-provider jojo -h
Usage: synadm user auth-provider [OPTIONS] EXTERNAL_ID

  Find a user based on their auth-provider ID. Finds a user based on their
  ID (external id) in auth provider represented by auth provider id
  (provider).

Options:
  -p, --provider TEXT  Provider ID as advertised in supported authenticated
                       methods in `m.login.sso` api response such as 'oidc' or
                       'google' or 'github'  [required]

  -h, --help           Show this message and exit.

PEP 8 styleguides

Absolutely! I understand. I am pretty new to Python so still learning the ropes here. I have changed this manually by running flake8 locally. Definitely great to have a linter run automatically as you are doing it in #80 and some means of doing it easily automatically would be great, similar to how Synapse does it with poetry run black .

Thanks for the changes. Great. To make sure and even test the new automatic linting you could just git pull --rebase upstream master and test the code in your PR already using the workflow.

Here you could shorten / rewrite the first sentence of your docstring so it is obvious to the user what this command is supposed to do. Just shorten it as good as possible so it makes sense and is not cut. A more detailed description can be added after a newline in the docstring.

Excellent! Done!

Please add an empty line after the very first sentence in the docstring and keep writing of ID/id consistent throughout. I suggest ID everywhere.

I see you added added parts of this information from the api docs which I think is a good start. Maybe point to another synadm command that reveals what m.login.sso tells. I think user details or even user list do that.

I couldn't find an existing command to add to the description here, so improved the description slightly with an example.

Yeah you're right, the user details command does not reveal that, I was mistaken, so yes: Your change is great. Having some examples what a provider could be helps a lot to a novice user like me that hadn't much to do with auth-providers and Matrix yet ;-)

[ashfame]

It's ok, I was not sure what's the best way either.

Ok, lets keep it as is then.

Could oidc be the default value for --provider

I don't believe so. EMS does call their OIDC config as 'oidc' and they may have 'github' and 'google' configurations for "Login via Github/Google", but I don't believe its safe to assume a default here. Its really what string you define it as in your Synapse config.

Mapping providers are a different thing. That's more like how to map out the response from these auth providers. They have a default one, but you can define a custom one as well.

You could rename EXTERNAL_ID to EXTERNAL_USER_ID

Done!

Please add an empty line after the very first sentence in the docstring and keep writing of ID/id consistent throughout. I suggest ID everywhere.

Done!

To make sure and even test the new automatic linting you could just git pull --rebase upstream master and test the code in your PR already using the workflow.

Ok, will rebase to trigger that.

Having some examples what a provider could be helps a lot to a novice user like me that hadn't much to do with auth-providers and Matrix yet ;-)

Sure! So, lets say you configured SSO with a custom auth provider (this could be an established service like Google or Github as well), but now you have an identifier for them in the external system (your own or Github's username) but you don't know what username they chose to create or was created for them on Synapse. So this lets you find that user by specifying that external ID. Like show the user who is "ashfame" on Github. Maybe "ashfame" was already taken and I got "@ashfame2:server.host" as my identity. Hope that's helpful :)

[ashfame]

Ok, looks like I don't need to rebase, it can already be triggered but require an approval from your side.

[ashfame]

ah oh, shouldn't it run automatically once approved? Atleast on the same PR? Please hit the button again.

[JOJ0]

I think it works as designed by github, once your first pr was merged, it will be automatic.
But I'll have a look in the actions setting later today to make sure.

[ashfame]

@JOJ0 Is this ready to be merged? :)

[JOJ0]

Yes it is! Thanks a lot for another great synadm feature and speak soon I guess. :-)