Update SDK readme with native authentication content #2051
Conversation
|
Let's add some description to the PR explaining what we are changing here and why. |
Co-authored-by: iamgusain <75644120+iamgusain@users.noreply.github.com>
|
@negoe @iamgusain could you please have another look at this? |
Co-authored-by: Henry Mbugua <82150047+henrymbuguakiarie@users.noreply.github.com>
|
|
||
| To use MSAL Android in your application, you need to register your application in the Microsoft Entra Admin center and configure your Android project. Since MSAL Android supports both browser-delegated and native authentication experiences, follow the steps in the following tutorials based on your scenario. | ||
|
|
||
| * For browser-delegated authentication scenarios, refer to the quickstart, [Sign in users and call Microsoft Graph from an Android app](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-mobile-app-android-sign-in). |
There was a problem hiding this comment.
Some conceptual feedback: why are we repeating instructions here that are already documented in learn.microsoft.com?
I understood from @kaushikkislay that there's a push to have all developer journeys start on learn.microsoft.com, and if/where they start elsewhere (like Github) to guide them to learn.microsoft.com.
There was a problem hiding this comment.
Appreciate your feedback here.
In this SDK readme, we've updated the previous content to ensure it includes native auth capabilities. The content, like other SDKs, includes an overview of the SDK, installation steps, and getting started guidance. And for the most part, we're pointing developers to content on MS Learn, and leading them to where they'll find different pieces of content they'd need based on their scenarios.
I'd be happy to cut down some sections and replace with equivalent links to MS Learn if we all agree to take this approach.
README.md
Outdated
| } | ||
| }; | ||
| } | ||
| } |
There was a problem hiding this comment.
Missing closing );. @Dickson-Mwendia perhaps run this in Android Studio to see if it compiles.
There was a problem hiding this comment.
Good spot @SammyO. Tested and yes, it was missing the );
There was a problem hiding this comment.
Thanks, Dickson for the updates. I have provided my comments. The only main call out I have is the overall structure of the readme seems a bit confusing at the start. While reviewing, it's apparent that customers might become confused regarding the changes to Workforce identity support by MSAL. Previously, the term "Browser delegated auth" wasn't used, as it was the only default support for Workforce ID. Introducing this new term without initially clarifying what "browser delegated support" means, could be puzzling for customers. Also, please note that Ext ID supports both Browser delegated auth and Native Auth. Therefore, we need to explicitly clarify that here browser delegated auth is the original default support by MSAL for work/school and personal accounts.
Additionally, I would recommend setting the customer’s expectation from the beginning by stating that native auth is only supported in the case of Ext ID. You can pivot the document along the lines of: “To support External ID scenarios, we now offer Native authentication for better control over the design of the mobile application sign-in experiences.”
README.md
Outdated
|
|
||
| The Microsoft Authentication Library (MSAL) for Android is an auth SDK that can be used to seamlessly integrate authentication into your apps using industry standard OAuth2 and OpenID Connect protocols. It allows you to sign in users or apps with Microsoft identities. These identities include Microsoft Entra ID work and school accounts, personal Microsoft accounts, social accounts, and customer accounts. | ||
|
|
||
| The Microsoft Authentication Library (MSAL) for Android enables developers to acquire security tokens from the Microsoft identity platform using OAuth2 and OpenID Connect protocol to authenticate users and access secure web APIs for their Android based applications. The library supports multiple authentication scenarios such as single sign-on (SSO), Conditional Access, and brokered authentication. |
There was a problem hiding this comment.
In the past we have always been the term 'tokens' and not 'security tokens'. Is there a reason we are writing security token here?
There was a problem hiding this comment.
No specific reason per se, we could keep the usage of "tokens" to maintain consistency.
README.md
Outdated
|
|
||
| The Microsoft Authentication Library (MSAL) for Android is an auth SDK that can be used to seamlessly integrate authentication into your apps using industry standard OAuth2 and OpenID Connect protocols. It allows you to sign in users or apps with Microsoft identities. These identities include Microsoft Entra ID work and school accounts, personal Microsoft accounts, social accounts, and customer accounts. | ||
|
|
||
| The Microsoft Authentication Library (MSAL) for Android enables developers to acquire security tokens from the Microsoft identity platform using OAuth2 and OpenID Connect protocol to authenticate users and access secure web APIs for their Android based applications. The library supports multiple authentication scenarios such as single sign-on (SSO), Conditional Access, and brokered authentication. |
There was a problem hiding this comment.
Can we please add relevant links to Android related SSO, CA and brokered auth pages?
There was a problem hiding this comment.
Added, SSO and brokered auth content for MSAL Android is in the same article.
README.md
Outdated
| ### :exclamation: Migrating from ADAL | ||
| ## Overview | ||
|
|
||
| The Microsoft Authentication Library (MSAL) for Android is an auth SDK that can be used to seamlessly integrate authentication into your apps using industry standard OAuth2 and OpenID Connect protocols. It allows you to sign in users or apps with Microsoft identities. These identities include Microsoft Entra ID work and school accounts, personal Microsoft accounts, social accounts, and customer accounts. |
There was a problem hiding this comment.
to stay consistent across all docs, we should make it -> Microsoft personal accounts.
| MSAL Android also enables you to implement a native authentication experience with end-to-end customizable flows in mobile applications. With native authentication, users are guided through a rich, native, mobile-first sign-up and sign-in journey without leaving the app. The native authentication feature is only available for mobile apps on [External ID for customers](https://learn.microsoft.com/en-us/entra/external-id/customers/concept-native-authentication). | ||
|
|
||
|
|
||
| When implementing authentication for mobile apps on External ID, you can choose between browser-delegated authentication and native authentication. In browser-delegated authentication, users are taken to the browser for authentication and then redirected back to the app when the sign-in process is complete. Learn how you can [choose the right authentication option](https://learn.microsoft.com/en-us/entra/external-id/customers/concept-native-authentication#when-to-use-native-authentication) for your mobile app. |
There was a problem hiding this comment.
The link is for Native Authentication and not for the External Id landing page.
There was a problem hiding this comment.
Sure, @negoe. This was the intended destination as we have a table that compares the two authentication methods and could serve as a decision guide. Thoughts on this?
|
|
||
| ```gradle | ||
| dependencies { | ||
| implementation 'com.microsoft.identity.client:msal:4.9.+' |
There was a problem hiding this comment.
Please add a note for customer to utilize latest version by going to the release page. We sometimes dont update readme with every single major release.
There was a problem hiding this comment.
Great call-out here, thanks!
|
Thanks @negoe . I've updated the section that introduces native auth. Please have a look. Also, let me know what you think about renaming the H2 "Native authentication support in MSAL" and if this could bring more clarity to our customers. |
|
|
||
| By default, MSAL uses the standard, browser-delegated authentication flow where you rely on the user's browser to handle the sign-in experience. This browser-based experience is the default authentication method for work and school accounts as well as personal Microsoft accounts. | ||
|
|
||
| To support Microsoft Entra External ID scenarios, MSAL Android now offers Native authentication that allows you to customize the sign-in experiences within your mobile app. With native authentication, users are guided through a rich, native, mobile-first sign-up and sign-in journey without leaving the app. The native authentication feature is only available for mobile apps on [External ID for customers](https://learn.microsoft.com/en-us/entra/external-id/customers/concept-native-authentication). |
There was a problem hiding this comment.
nit: The native authentication feature is only available for mobile apps using External ID for customers.
|
|
||
| #### Native authentication support in MSAL | ||
|
|
||
| By default, MSAL uses the standard, browser-delegated authentication flow where you rely on the user's browser to handle the sign-in experience. This browser-based experience is the default authentication method for work and school accounts as well as personal Microsoft accounts. |
There was a problem hiding this comment.
Could we begin by discussing the default support provided by MSAL at a high level, and then divide the content into two distinct categories for browser-delegated and native authentication? The first paragraph under the Native Authentication heading is informative, but it should be positioned outside of this section for better clarity. Also it will align with your content below regarding App configuration.
Example:
Understanding Authentication User Experience in MSAL
MSAL primarily employs the standard, authentication flow, which leverages the user's browser to manage the sign-in experience. This approach is the default authentication method for both work and school accounts, as well as Microsoft personal accounts.
H1: Browser-Delegated Authentication : add your content
H2: Native authentication : add your content
Then provide link to choosing the appropriate authentication method.
This PR updates the readme to include the native authentication capabilities for MSAL Android.
For the documentation updates and links:
We point to the official MSAL Android docs on MS Learn - https://learn.microsoft.com/en-us/entra/msal/android
Within the getting started section of the readme, we provide links to the different quickstarts/tutorials that devs can follow, based on their scenario and type of app they're building (workforce/customer)
I've also removed much of the content that's duplicated in the official docs (configuration, initialize client app, and acquire tokens) and instead pointed to the guidance on MS Learn, i.e:
As for the code samples, we also need to differentiate the between workforce and customer sample apps, that's why we have two links. Eventually, the links will point to the code samples browser, such as (https://learn.microsoft.com/en-us/samples/browse/?products=microsoft-authentication-library) I'm working to get all code samples for Android onboarded there.