openmobilehub / android-omh-auth

Apache License 2.0
4 stars 1 forks source link

Clarification and Simplification Needed in "Set up your Microsoft application" Documentation for Account Types #36

Closed dzuluaga closed 8 months ago

dzuluaga commented 8 months ago

I've encountered a significant issue while following the "Set up your Microsoft application" section of the documentation, specifically regarding the configuration of supported account types for authentication. The current documentation does not clearly specify which type of account (e.g., personal, work, or school) should be used during the setup process. This omission leads to confusion and potential errors when developers assume the wrong account type.

Issue Description: When setting up an application to use Microsoft's authentication, the documentation fails to mention the necessity of specifying the account type. If a developer selects a personal account without proper guidance, they encounter an error. The resolution involves a complex process of editing the application's manifest in the Microsoft manifest editor to change the signInAudience to "AzureADandPersonalMicrosoftAccount". This process is not straightforward and can be daunting for developers, especially if they are not familiar with the manifest editor or the specific requirement.

Steps to Reproduce:

  1. Follow the current "Set up your Microsoft application" documentation without specifying the account type.
  2. Select a personal account for the application setup.
  3. Encounter an error due to incorrect signInAudience configuration.

Expected Behavior: The documentation should clearly guide the developer through selecting the correct account type and configuring the signInAudience appropriately to avoid errors and the need for complex manifest editing.

Suggested Fixes:

  1. Update the "Set up your Microsoft application" section to include detailed steps on how to select the correct account type and configure the signInAudience accordingly.
  2. Simplify the process for changing the supported account type, if possible, to avoid direct editing of the manifest file.
  3. Implement a review process where a different DX (Developer Experience) team, other than the one who developed the sample app, tests the documentation steps to ensure clarity, accuracy, and ease of use.

This issue creates unnecessary hurdles for developers trying to integrate Microsoft authentication into their applications. A clear, concise, and accurate documentation will significantly improve the developer experience and reduce setup errors.

Thank you for your attention to this matter. I look forward to the updated documentation.

Snapshots of the issue within the app and Azure Console:

image image image
andrei-zgirvaci commented 8 months ago

Thanks Diego for pointing this out! I have added the note about the "Account Type" in https://github.com/openmobilehub/android-omh-auth/pull/38/commits/8a1702ca05fe3562dffd454967993f4b344fa888.