Skip to content

Commit a593fcc

Browse files
author
Angela Fleischmann
authored
Merge pull request #8320 from Erikre/erikre-oob2208-15363982
Erikre-oob2208-15363982
2 parents 66f86b3 + 58faef1 commit a593fcc

15 files changed

Lines changed: 3893 additions & 2466 deletions

‎.openpublishing.redirection.json‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,15 @@
11
{
22
"redirections": [
3+
{
4+
"source_path": "memdocs/intune/developer/app-sdk-android.md",
5+
"redirect_url": "/mem/intune/developer/app-sdk-android-phase1",
6+
"redirect_document_id": false
7+
},
8+
{
9+
"source_path": "memdocs/intune/developer/app-sdk-android-testing-guide.md",
10+
"redirect_url": "/mem/intune/developer/app-sdk-android-phase1",
11+
"redirect_document_id": false
12+
},
313
{
414
"source_path": "memdocs/intune/fundamentals/end-user-company-portal-messages.md",
515
"redirect_url": "/mem/intune/user-help/sign-in-to-the-company-portal",

‎memdocs/intune/developer/app-sdk-android-appendix.md‎

Lines changed: 334 additions & 0 deletions
Large diffs are not rendered by default.

‎memdocs/intune/developer/app-sdk-android-phase1.md‎

Lines changed: 282 additions & 0 deletions
Large diffs are not rendered by default.

‎memdocs/intune/developer/app-sdk-android-phase2.md‎

Lines changed: 204 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,204 @@
1+
---
2+
# required metadata
3+
4+
title: Microsoft Intune App SDK for Android developer integration and testing guide - MSAL Prerequisite
5+
description: Understand the MSAL prerequisite to incorporate Intune mobile app management (MAM) into your Android app.
6+
keywords: SDK
7+
author: Erikre
8+
ms.author: erikre
9+
manager: dougeby
10+
ms.date: 08/24/2022
11+
ms.topic: reference
12+
ms.service: microsoft-intune
13+
ms.subservice: developer
14+
ms.localizationpriority: medium
15+
ms.technology:
16+
ms.assetid: 0100e1b5-5edd-4541-95f1-aec301fb96af
17+
18+
# optional metadata
19+
20+
#ROBOTS:
21+
#audience:
22+
23+
ms.reviewer: jamiesil
24+
ms.suite: ems
25+
search.appverid: MET150
26+
#ms.tgt_pltfrm:
27+
ms.collection:
28+
- M365-identity-device-management
29+
- Android
30+
ms.custom: intune-classic
31+
---
32+
33+
# Intune App SDK for Android - Understand the MSAL Prerequisite
34+
35+
The Microsoft Intune App SDK for Android lets you incorporate Intune app protection policies (also known as **APP** or MAM policies) into your native Java/Kotlin Android app. An Intune-managed application is one that is integrated with the Intune App SDK. Intune administrators can easily deploy app protection policies to your Intune-managed app when Intune actively manages the app.
36+
37+
> [!NOTE]
38+
> This guide is divided into several distinct stages. Start by reviewing [Plan the Integration](..\developer\app-sdk-android-phase1.md).
39+
40+
## Stage 2: The MSAL Prerequisite
41+
42+
## Stage Goals
43+
44+
- Register your application with Azure Active Directory (AAD).
45+
- Integrate MSAL into your Android application.
46+
- Verify that your application can obtain a token that grants access to protected resources.
47+
48+
## Background
49+
50+
The [Microsoft Authentication Library (MSAL)] gives your application the ability to use the Microsoft Cloud by supporting [Microsoft Azure Active Directory (AAD)] and [Microsoft accounts].
51+
52+
MSAL isn't- specific to Intune.
53+
Intune has a dependency on AAD; all Intune user accounts are AAD accounts.
54+
**As a result, the vast majority of Android applications that integrate the Intune App SDK will need to integrate MSAL as a prerequisite.**
55+
56+
This stage of the SDK guide overviews the MSAL integration process as it relates to Intune; **follow the linked MSAL guides in their entirety**.
57+
58+
To simplify the Intune App SDK integration process, **Android app developers are strongly encouraged to fully integrate and test MSAL before downloading the Intune App SDK.**
59+
The Intune App SDK integration process *does- require code changes around MSAL token acquisition.
60+
It will be significantly easier to test the Intune-specific token acquisition changes if you've already confirmed your app's original token acquisition implementation works as expected.
61+
62+
To learn more about AAD, see [What is Azure Active Directory?]
63+
64+
To learn more about MSAL, see the [MSAL Wiki] and [list of MSAL libraries].
65+
66+
## Register your Application with AAD
67+
68+
Before integrating MSAL into your Android application, follow the instructions to [register your application with Azure Active Directory].
69+
This will generate a **Client ID** for your application.
70+
71+
Next, follow the instructions to [give your app access to the Intune app protection service].
72+
73+
## Configure Microsoft Authentication Library (MSAL)
74+
75+
First, read the MSAL integration guidelines found in the [MSAL repository on GitHub], specifically the section [using MSAL].
76+
77+
This guide describes how to:
78+
79+
- Add MSAL as a dependency to your Android application.
80+
- Create an MSAL configuration file.
81+
- Configure your application's `AndoridManifest.xml`.
82+
- Add code to acquire a token.
83+
84+
### Brokered Authentication
85+
86+
Single sign-on (SSO) allows users to only enter their credentials once and have those credentials automatically work across applications.
87+
MSAL can enable SSO across your suite of apps; by using a broker application (either the Microsoft Authenticator or Microsoft Intune Company Portal), you can extend SSO across the entire device.
88+
Brokered authentication is also required for Conditional Access.
89+
See [Enable cross-app SSO on Android using MSAL] for more details on brokered authentication.
90+
91+
This guide assumes that you're enabling brokered authentication within your application(s) following the steps at the link above, especially [Generate a redirect URI for a broker] and [Configure MSAL to use a broker] for configuration and [Verify broker integration] for testing.
92+
93+
**If you are not enabling brokered authentication in your application, pay extra attention to [Intune-specific MSAL configuration]**.
94+
95+
### Intune-specific MSAL configuration
96+
97+
Intune has up to four settings you may need to add to your application's `AndroidManifest.xml`.
98+
These settings help ensure that Intune's authentication policy can be properly enforced and prevent unnecessary authentication prompts for end users.
99+
100+
These settings include:
101+
102+
```xml
103+
<meta-data
104+
android:name="com.microsoft.intune.mam.aad.ClientID"
105+
android:value="your-client-ID-GUID" />
106+
<meta-data
107+
android:name="com.microsoft.intune.mam.aad.Authority"
108+
android:value="https://AAD authority/" />
109+
<meta-data
110+
android:name="com.microsoft.intune.mam.aad.SkipBroker"
111+
android:value="[true | false]" />
112+
<meta-data
113+
android:name="com.microsoft.intune.mam.aad.NonBrokerRedirectURI"
114+
android:value="your-redirect-URI" />
115+
```
116+
117+
| Setting | Description | Required for MSAL? | Required by Intune? |
118+
| - | - | - | - |
119+
| `ClientID` | The AAD ClientID (also known as the "Application ID") for your app. <br> There's no default `ClientID`. Use the `ClientID` from [Register your Application with AAD] for your app. | Yes | No |
120+
| `Authority` | The AAD authority to issue a token. <br> By default, this value is the AAD public environment. If overridden, the AAD authority entered will issue the token for your application, which allows authentication to non-default environments, such as Sovereign clouds. | No | If your application requires a non-default authority, yes. **Most apps should not set the Authority parameter.** |
121+
| `SkipBroker` | Boolean value for altering the default MSAL SSO behavior. <br> By default, this value is "false". | No | If your app doesn't support brokered authentication/device-wide SSO, yes and set `SkipBroker` to "true". **Most apps should not set the SkipBroker parameter.** |
122+
| `NonBrokerRedirectURI` | [AAD redirect URI] to use in broker-less cases. By default, this value isn't present. | No | If the `SkipBroker` setting is set to "true" and your app requires a redirect URI, yes. **Most apps should not set the NonBrokerRedirectURI parameter.** |
123+
124+
> [!CAUTION]
125+
> Applications that do not integrate MSAL **must not** include any of these 4 properties in the manifest.
126+
127+
For more detail on non-Intune-specific MSAL configuration options, see [Android Microsoft Authentication Library configuration file].
128+
129+
For more detail on Sovereign clouds, see [Use MSAL in a national cloud environment].
130+
131+
132+
## Exit Criteria
133+
134+
- Have you integrated MSAL into your application?
135+
- Have you enabled broker authentication by generating a redirect URI and setting it in the MSAL configuration file?
136+
- Have you configured the Intune-specific MSAL settings in the `AndroidManifest.xml`?
137+
- Have you tested brokered authentication, confirmed that a work account is added to Android's Account Manager, and tested SSO with other Microsoft 365 apps?
138+
- If you implemented Conditional Access, have you tested both device-based CA and app-based CA to validate your CA implementation?
139+
140+
## FAQ
141+
142+
### What about ADAL?
143+
144+
Microsoft's previous authentication library, [Azure Active Directory Authentication Library (ADAL)], is **deprecated**.
145+
146+
If your application has already integrated ADAL, see [Update your applications to use Microsoft Authentication Library (MSAL)].
147+
To migrate your app from ADAL to MSAL, see [Migrate Android ADAL to MSAL] and [Differences between ADAL and MSAL].
148+
149+
**It is recommended to migrate from ADAL to MSAL prior to integrating the Intune App SDK.**
150+
151+
## Next Steps
152+
153+
After you've completed all the [Exit Criteria] above, continue to [Stage 3: Getting Started with MAM].
154+
155+
<!-- Stage 2 links -->
156+
<!-- internal links -->
157+
[Register your Application with AAD]:#register-your-application-with-aad
158+
[Intune-specific MSAL configuration]:#intune-specific-msal-configuration
159+
[Exit Criteria]:#exit-criteria
160+
161+
<!-- Other SDK Guide Markdown docs -->
162+
[Stage 1: Planning the Integration]:app-sdk-android-phase1.md
163+
[Stage 3: Getting Started with MAM]:app-sdk-android-phase3.md
164+
165+
<!-- Microsoft docs: AAD -->
166+
[Microsoft Azure Active Directory (AAD)]:https://azure.microsoft.com/services/active-directory/
167+
[Microsoft accounts]:https://account.microsoft.com/
168+
[What is Azure Active Directory?]:/azure/active-directory/fundamentals/active-directory-whatis
169+
[register your application with Azure Active Directory]:/azure/active-directory/active-directory-app-registration
170+
171+
<!-- Microsoft docs: MSAL-->
172+
[Microsoft Authentication Library (MSAL)]:/azure/active-directory/develop/msal-overview
173+
[list of MSAL libraries]:/azure/active-directory/develop/reference-v2-libraries
174+
[MSAL Wiki]:https://github.com/AzureAD/
175+
[using MSAL]: https://github.com/AzureAD/microsoft-authentication-library-for-android#using-msal
176+
[Enable cross-app SSO on Android using MSAL]:/azure/active-directory/develop/msal-android-single-sign-on
177+
[Generate a redirect URI for a broker]:/azure/active-directory/develop/msal-android-single-sign-on#generate-a-redirect-uri-for-a-broker
178+
[Configure MSAL to use a broker]:/azure/active-directory/develop/brokered-auth#configure-msal-to-use-a-broker
179+
[Verify broker integration]:/azure/active-directory/develop/msal-android-single-sign-on#verify-broker-integration
180+
[AAD redirect URI]:/azure/active-directory/develop/msal-client-application-configuration#redirect-uri
181+
[Use MSAL in a national cloud environment]:/azure/active-directory/develop/msal-national-cloud
182+
[Android Microsoft Authentication Library configuration file]:/azure/active-directory/develop/msal-configuration
183+
[MSAL repository on GitHub]: https://github.com/AzureAD/microsoft-authentication-library-for-android
184+
185+
<!-- Microsoft docs: ADAL -->
186+
[Azure Active Directory Authentication Library (ADAL)]:/azure/active-directory/azuread-dev/active-directory-authentication-libraries
187+
188+
<!-- Microsoft docs: ADAL to MSAL -->
189+
[Update your applications to use Microsoft Authentication Library (MSAL)]:https://techcommunity.microsoft.com/t5/azure-active-directory-identity/update-your-applications-to-use-microsoft-authentication-library/ba-p/1257363
190+
[Migrate Android ADAL to MSAL]:/azure/active-directory/develop/migrate-android-adal-msal
191+
[Differences between ADAL and MSAL]:/azure/active-directory/develop/msal-overview#differences-between-adal-and-msal
192+
193+
<!-- Microsoft docs: CA -->
194+
[Conditional Access (CA)]:/azure/active-directory/develop/active-directory-conditional-access-developer
195+
[device-based CA]:/mem/intune/protect/conditional-access-intune-common-ways-use#device-based-conditional-access
196+
[app-based CA]:/mem/intune/conditional-access-intune-common-ways-use#app-based-conditional-access
197+
[configuring app-based CA]:/mem/intune/protect/app-based-conditional-access-intune-create
198+
199+
200+
<!-- Microsoft docs -->
201+
[give your app access to the Intune app protection service]:/mem/intune/developer/app-sdk-get-started#give-your-app-access-to-the-intune-app-protection-service-optional
202+
203+
<!-- Other Microsoft links -->
204+
[Microsoft Endpoint Manager admin center]:https://go.microsoft.com/fwlink/?linkid=2109431

0 commit comments

Comments
 (0)