New command: `m365 spo site membership list`

mkm17 commented 2 months ago

Usage

m365 spo site membership list

Description

Retrieve information about default site groups' membership.

Options

Option	Description
`-u, --siteUrl <siteUrl>`	The URL of the site
`-r, --role [role]`	Filter the results to only users with the given role: 'Owner', 'Member', 'Visitor'.

Examples

Retrieves information about default site groups' owners, members, and visitors of the site.

m365 spo site membership list--siteUrl https://contoso.sharepoint.com

Retrieves information about site owners.

m365 spo site membership list --siteUrl https://contoso.sharepoint.com --role Owner

Default properties

Email
LoginName
Name
UserPrincipalName
Role

Additional Info

This command could be helpful for SharePoint administrators, It would allow getting information about membership of a site using the _api/SPO.Tenant/sites/GetSiteUserGroups endpoint, like in the SP admin page.

The benefit here is that administrators can access this information with SharePoint admin permission only, without needing site collection admin permission.

Remarks

To execute this command successfully, ensure that you are logged in to the CLI for M365 with an account that has SharePoint admin permissions. In other scenarios, please check the spo web get --withGroups and spo group member list commands.

milanholemans commented 2 months ago

Hi @mkm17 thank you for creating this issue. Could you give some more context about what this command actually does? What will it return?

If it lists memberships of default groups, I think that's already possible using spo web get --withGroups and spo group member list.

mkm17 commented 2 months ago

Hi, @milanholemans To be honest, it will retrieve the same data as in the provided examples by you. The only difference is that to execute spo web get, the current user must have permission to the web. However, when using _api/SPO.Tenant/sites/GetSiteUserGroups, a user can have 'just' SharePoint Global Admin permission.

The use case can be when there's a need to generate a report on the membership of multiple webs without direct access for current user. To address this scenario,

we can utilize an app with application permissions for all sites,
temporarily add a user as a site collection admin, or
use the _api/SPO.Tenant/sites/GetSiteUserGroups endpoint.

The similar case is mentioned here https://github.com/pnp/cli-microsoft365/issues/5882#issuecomment-1981160284

If adding a new command is not the best solution, maybe we can extend spo group member list with --asAdmin flag?

Then the command execution should cover only default groups and the execution would be like m365 spo group member list --associatedmembers --asAdmin

milanholemans commented 2 months ago

Hi @mkm17 thanks for clarifying. Does this endpoint only return the SharePoint groups? Could you give an example of a possible output? This would make it a bit clearer I guess.

mkm17 commented 2 months ago

Hi @milanholemans, for example the GET request https://<tenant>-admin.sharepoint.com/_api/SPO.Tenant/sites/GetSiteUserGroups?siteId='<SiteId>'&userGroupIds=[0,1,2]

returns

[
        {
            "userGroup": [
                {
                    "email": "login@tenant.onmicrosoft.com",
                    "loginName": "i:0#.f|membership|login@tenant.onmicrosoft.com",
                    "name": "<Display Name>",
                    "userPrincipalName": "login@tenant.onmicrosoft.com"
                }
            ]
        },
        {
            "userGroup": []
        },
        {
            "userGroup": []
        }
    ]

The first user group corresponds to Owners, the next one to Members, and the last one to visitors. As I mentioned before, the real case scenario could be generating a membership report while the user is only a SharePoint admin without access to the Site as a Site collection admin. Of course, it's just an idea. Honestly, I've already used this scenario, so I thought it might be useful for someone else :)

Adam-it commented 1 month ago

hi all, sorry for coming late to the party 🙏.

@mkm17 isn't this more like a list command rather than a get command? As we are more like listing the groups along with the members not getting a single item. What do you think?
usually, we try not to modify the API response and return the result the same way as the API we use under the hood in the command, but in this case it is sooo confusing I would do that. First of all It is totally unclear that the first group returned are owners, the second are members and the third are visitors. Either we make it super clear in the docs (which not everybody reads) or we could change the response to return this as 3 objects, the first with name AssociatedOwnerGroup the second with AssociatedMemberGroup etc. So it would a bit align with spo web get command with withGroups option
in general, I don't see any risk in adding this command. It does create more opportunities for CLI to be used by an admin and the response is different than other commands. Even though it is possible to get the same info using two other commands but as @mkm17 mentioned we would still need permissions to the web which for the mentioned scenario: "Create a report with groups and members from all sites" is a kinda pain and would require for that user to have access to each web. With this new command we would have this covered.
@mkm17 for the role the allowed values are 'Owner', 'Member', 'Visitor'. but in one of the examples you use ... --role Owners . Should be Owner.

@pnp/cli-for-microsoft-365-maintainers any other feedback? on this? I see potential in this command and I would review the spec and open it up 👍

waldekmastykarz commented 1 month ago

Interesting idea @mkm17. Thanks for bringing it up. I see a use case for adding this command, especially as it's meant to be used slightly different than the existing commands that we have (ie. tenant admin who's not a site collection admin). If we're to add it, I suggest we ensure that the docs are clear when to use this command vs. the existing groups commands that Milan mentioned, and in both commands we add references to the other commands so that folks easily discover other, and maybe for them more suitable, commands.

mkm17 commented 1 month ago

Thanks, @Adam-it, for the recommendations. I have updated the specification accordingly :)

@waldekmastykarz , good point. I will add the information in the remarks section of the new command, as well as the 'spo web get --withGroups' and 'spo group member list' commands mentioned by @milanholemans .

Thank you all for your inputs. Do you have any other suggestions what should be included?

Jwaegebaert commented 1 month ago

I don't have any more feedback, the specs look clear to me. One small detail, include Waldek's remark in the initial spec so we don't forget it. 😉

Do you want to work on it @mkm17 or should we open it up?

Adam-it commented 1 month ago

yes lets open it up 💪 thanks, @pnp/cli-for-microsoft-365-maintainers for your double check on this issue. @mkm17 wanna take the lead on this or leave it for someone else?

mkm17 commented 1 month ago

@Jwaegebaert, thanks! I have added remarks to the specification of the command. @Adam-it, yes, I can take it. If you can wait a little bit for the result, as I am already assigned to some other commands :)

milanholemans commented 3 weeks ago

Sorry for rejoining the discussion this late. In my opinion, this command should be called spo tenant site membership list. As discussed before, we try to move all admin-related commands under the spo tenant umbrella.

@pnp/cli-for-microsoft-365-maintainers do you agree?

mkm17 commented 3 weeks ago

Hi @milanholemans, ok I will change the current PR accordingly.

mkm17 commented 3 weeks ago

@milanholemans , Ok, I have updated the PR.

Adam-it commented 3 weeks ago

Sorry for rejoining the discussion this late. In my opinion, this command should be called spo tenant site membership list. As discussed before, we try to move all admin-related commands under the spo tenant umbrella.

@pnp/cli-for-microsoft-365-maintainers do you agree?

good idea. Let's do that

pnp / cli-microsoft365