New command: List authentication methods registered for users

[MartinM85]

Usage

m365 entra user registrationdetails list

Description

Retrieves a list of the authentication methods registered for users.

Options

Option	Description
--isAdmin [isAdmin]	Filter for users who are admins. Allowed values are true or false. If not specified, returns all users.
--userType [userType]	Filter for members or guest users. Allowed values are member or guest. If not specified, returns all users.
--userPreferredMethodForSecondaryAuthentication [userPreferredMethodForSecondaryAuthentication]	Filter users by selected method as default second-factor authentication. Allowed values are push, oath, voiceMobile, voiceAlternateMobile, voiceOffice, sms or none. Specify either one method or more methods separated by a comma.
--systemPreferredAuthenticationMethods [systemPreferredAuthenticationMethods]	Filter users by most secure authentication methods registered for second-factor authentication. Allowed values are push, oath, voiceMobile, voiceAlternateMobile, voiceOffice, sms or none. Specify either one method or more methods separated by a comma.
--isSelfServicePasswordResetRegistered [isSelfServicePasswordResetRegistered]	Filter for users who have registered for self-service password reset. Allowed values are true or false. If not specified, returns all users.
--isSelfServicePasswordResetEnabled [isSelfServicePasswordResetEnabled]	Filter for users who have been enabled for self-service password reset. Allowed values are true or false. If not specified, returns all users.
--isSelfServicePasswordResetCapable [isSelfServicePasswordResetCapable]	Filter for users who are ready to perform self-service password reset. Allowed values are true or false. If not specified, returns all users.
--isMfaRegistered [isMfaRegistered]	Filter for users who are registered for multi-factor authentication. Allowed values are true or false. If not specified, returns all users.
--isMfaCapable [isMfaCapable]	Filter for users who are ready to perform password reset or multi-factor authentication. Allowed values are true or false. If not specified, returns all users.
--isPasswordlessCapable [isPasswordlessCapable]	Filter for user who have registered a password less strong authentication method. Allowed values are true or false. If not specified, returns all users.
--isSystemPreferredAuthenticationMethodEnabled [isSystemPreferredAuthenticationMethodEnabled]	Filter for users who have enabled system preferred authentication method. Allowed values are true or false. If not specified, returns all users.
--methodsRegistered [methodsRegistered]	Filter users by registered methods used during registration. Allowed values are mobilePhone, email, fido2, microsoftAuthenticatorPush or softwareOneTimePasscode. Specify either one method or more methods separated by a comma.
--userIds [userIds]	Filter users by ids. Specify at most 20 ids separated by a comma.
--userPrincipalNames [userPrincipalNames]	Filter users by user principal names. Specify at most 20 UPN separated by a comma.
-p, --properties [properties]	Comma-separated list of properties to retrieve.

Examples

Retrieve registration details for all users

m365 entra user registrationdetails list

Retrieve user registration details and returns only specific properties

m365 entra user registrationdetails list --properties 'id,isAdmin'

Retrieve registration details for admins

m365 entra user registrationdetails list --isAdmin true

Retrieve registration details for guest users

m365 entra user registrationdetails list --userType guest

Retrieve registration details for users who selected push authentication method as the default second-factor for performing multifactor authentication

m365 entra user registrationdetails list --userPreferredMethodForSecondaryAuthentication push

Retrieve registration details for users who selected either sms or push authentication method as the default second-factor for performing multifactor authentication

m365 entra user registrationdetails list --userPreferredMethodForSecondaryAuthentication sms,push

Retrieve registration details for users with push authentication method as the most secure authentication method among the registered methods for second factor authentication determined by the system

m365 entra user registrationdetails list --systemPreferredAuthenticationMethods push

Retrieve registration details for users with either sms or push authentication method as the most secure authentication methods among the registered methods for second factor authentication determined by the system

m365 entra user registrationdetails list --systemPreferredAuthenticationMethods sms,push

Retrieve registration details for users who have used Microsoft Authenticator app during registration

m365 entra user registrationdetails list --registeredMethods microsoftAuthenticatorPush

Retrieve registration details for users who have used either Microsoft Authenticator app or mobile phone during registration

m365 entra user registrationdetails list --registeredMethods microsoftAuthenticatorPush,mobilePhone

Retrieve registration details for users who are not registered for multi-factor authentication

m365 entra user registrationdetails list --isMfaRegistered false

Retrieve registration details for users specified by id

m365 entra user registrationdetails list --userIds '121bca22-1a6b-455b-9e5d-64c5ef5e471d,fec200ce-a7a9-42cd-9717-3a3179a99b72'

Retrieve registration details for users specified by user principal names

m365 entra user registrationdetails list --userPrincipalNames 'AdeleV@contoso.com,johndoe@contoso.com'

Default properties

• userPrincipalName
• methodsRegistered
• lastUpdatedDateTime

Additional Info

It is quite useful report at least for administrators.

API: https://learn.microsoft.com/en-us/graph/api/authenticationmethodsroot-list-userregistrationdetails?view=graph-rest-1.0&tabs=http

The same report is in the Entra admin center

Filtering by userPrincipalNames and userDisplayNames is supported by default by the endpoint. When userIds option is specified, the command will find userPrincipalNames first.

The endpoint requires AuditLog.Read.All permission.

Add remark to the documentation about the behavior when multiple values for the options userPreferredMethodForSecondaryAuthentication, systemPreferredAuthenticationMethods, and registeredMethods are set.

When multiple values are specified for userPreferredMethodForSecondaryAuthentication option, the command returns registration details with at least one specified selected method as default second-factor authentication.

When multiple values are specified for systemPreferredAuthenticationMethods option, the command returns registration details with at least one specified most secure authentication methods registered for second-factor authentication.

When multiple values are specified for registeredMethods option, the command returns registration details with at least one specified registered methods used during registration.

I will work on it.

[Jwaegebaert]

Nice suggestion @MartinM85, I've a few pointers we should discuss before delving into it.

• We can simplify userregistrationdetails to registrationdetails as we're aware that it'll be registration details about the user object because you're already using m365 entra user.
• Wouldn't we make it overly complex if we allow multiple values for the options userPrefferedMethodForSecondaryAuthentication, systemPreferredAuthenticationMethods, and registeredMethods?
• For the option descriptions, let's refer to Allowed values instead of Possible values.
• For the option descriptions, when we refer to Specify either, it refers to options that are required for executing the command. As these are optional, let's make it more clear that these are optional. I think for userIds, userPrincipalNames, and userDisplayNames it's already clear what it does so doesn't require the Specify either anymore.
• In default properties, registeredMethods should be methodsRegistered

[MartinM85]

@Jwaegebaert Spec. updated.

Not sure about the second point

Wouldn't we make it overly complex if we allow multiple values for the options userPrefferedMethodForSecondaryAuthentication , systemPreferredAuthenticationMethods, and registeredMethods

It can be real use-case to filter by more than one value. By for me it's ok allow only one value.

Right now, I'm not sure about the separator for the userDisplayNames option. In my tenant, display names are without the comma, but I've already seen user display name like Doe, John. Maybe get rid off the userDisplayNames option.

[MartinM85]

@Jwaegebaert I've removed userDisplayNames option.

[MartinM85]

@Jwaegebaert @milanholemans Any other thoughts?

[waldekmastykarz]

In the list of examples, I find it confusing that some examples say Retrieve registration details and other Retrieve users. Let's make them consistent.

For bool options, let's consider if we can make them into flags to make them easier to use. For example isAdmin: should it have two or three states?

1. --isAdmin true - returns only users who are admin
2. --isAdmin false - returns only users who aren't admin
3. not specified - returns all users

or

1. --isAdmin - returns only users who are admin
2. not specified - returns all users

Let's consider this design for all other bool options that you proposed.

[MartinM85]

@waldekmastykarz All bool options have three states true/false/not specified. I will update the descriptions for those options. Those two examples say Retrieve users, because the filters are applied on registered methods to find out which users meet the conditions. In other examples, you filter users to get their authentication methods.

If the endpoint allow multiple values for the options userPreferredMethodForSecondaryAuthentication, systemPreferredAuthenticationMethods, and registeredMethods why to make a restriction for only one value?

[waldekmastykarz]

Those two examples say Retrieve users, because the filters are applied on registered methods to find out which users meet the conditions. In other examples, you filter users to get their authentication methods.

Right, but the command is not retrieving users. It's retrieving their auth methods, right? So the filters apply to users, but in the end, you get auth methods.

If the endpoint allow multiple values for the options userPreferredMethodForSecondaryAuthentication, systemPreferredAuthenticationMethods, and registeredMethods why to make a restriction for only one value?

Are we passing the specified values as-is to the API or are we considering them an OR filter? Ideally, let's clarify this with descriptions/remarks/examples so that users won't have to wonder/guess how the command works.

[MartinM85]

The OR filter will be applied when multiple values for the options userPreferredMethodForSecondaryAuthentication, systemPreferredAuthenticationMethods, and registeredMethods are set. I will add remark to the spec and to the doc.

[Jwaegebaert]

Okaj, I think the specs are clear enough now. So let's ship it 😄