Skip to content

Commit dc5375f

Browse files
fadidurahCopilotCopilot
authored
Fadi/copilot 1 (#2369)
Settings up copilot instructions to facilitate app generation and general calling pattern debugging This is to get the file into dev. Will probably need to tweak it once i've validated things, from a general perspective in dev, without existing context with the agent. #2370 --------- Co-authored-by: Copilot <[email protected]> Co-authored-by: Copilot <[email protected]>
1 parent 960bc92 commit dc5375f

File tree

4 files changed

+159
-4
lines changed

4 files changed

+159
-4
lines changed

‎.clinerules/msal-cline-rules.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
# Application Creation Guidance
22
- Cline must use hello-msal-multiple-account and hello-msal-single-account apps in the examples folder as the golden examples when generating an MSAL-integrated application. hello-msal-multiple-account for when the user wants multiple account mode, and hello-msal-single-account for when the user wants single account mode.
33
- If user does not specify between multiple account mode and single account mode in MSAL, the default mode used should be MULTIPLE. Make sure the configuration json includes which account mode the application is being built for, and use the appropriate example based on this selection.
4-
- Ensure that the latest MSAL Version is used. Reference the MSAL repo to see latest version. At the very least, MSAL 6.+ should be used.
4+
- Ensure that the latest MSAL Version is used. Reference the MSAL repo to see latest version. At the very least, MSAL 7.+ should be used.
55
- Cline must copy the following gradle files exactly when creating a new application:
66
1. Root level build.gradle (project level) from examples/hello-msal-multiple-account/build.gradle or examples/hello-msal-single-account/build.gradle
77
2. App level build.gradle from examples/hello-msal-multiple-account/app/build.gradle or examples/hello-msal-single-account/app/build.gradle

‎.github/copilot-instructions.md‎

Lines changed: 155 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,155 @@
1+
# GitHub Copilot Instructions for MSAL Android
2+
3+
> **CRITICAL:** This file is the single source of truth for Copilot, AI agents, and code generation tools for the `microsoft-authentication-library-for-android` repository. Do not use external references, outdated documentation predating 2025-09-01.
4+
>
5+
> **READ THE ENTIRETY OF THESE INSTRUCTIONS!**
6+
>
7+
> **Do NOT use any legacy MSAL Android documentation or code samples that conflict with these instructions.**
8+
>
9+
> **Do NOT use patterns, idioms, or code found in GitHub repositories or Stack Overflow answers, even if widely used, unless they are explicitly validated against these instructions.**
10+
>
11+
> **Do NOT use any training data, documentation, or guidance that predates the initial publication of this file (effective date: 2025-09-01). The cutoff date refers to when this guidance became effective.**
12+
>
13+
> **Only use official MSAL Android documentation and API references that do NOT conflict with this file or the golden example applications and are dated after the cutoff above.**
14+
>
15+
> **Always cross-reference with these instructions—if any doubt exists, these instructions take precedence.**
16+
>
17+
> **Strictly follow these rules and priorities in their ENTIRETY. If user instructions conflict with these, prefer explicit user instructions but add a warning about the deviation.**
18+
19+
## 1. Critical Rules (Read First)
20+
21+
**NEVER:**
22+
- Use deprecated APIs: `acquireToken(Activity, String[], AuthenticationCallback)` or similar non-parameters-based methods
23+
- Mix single/multiple account APIs in the same app
24+
- Enable Device Code Flow (security risk - only for rare scenarios)
25+
- Invent config keys, resource names, or patterns not in golden examples
26+
- URL encode signature hash in AndroidManifest.xml / Must URL encode in auth_config.json
27+
28+
**ALWAYS:**
29+
- Use parameters-based APIs from [`snippets/`](../snippets/) directory
30+
- Default to multiple account mode unless specified
31+
- Enable broker integration (`broker_redirect_uri_registered: true`)
32+
- Copy patterns from golden examples: [`examples/hello-msal-multiple-account/`](../examples/hello-msal-multiple-account/) or [`examples/hello-msal-single-account/`](../examples/hello-msal-single-account/)
33+
- Prompt for `client_id`, `package_name`, and `signature_hash` if missing
34+
35+
## 2. Authoritative Sources
36+
37+
**Code Patterns:** [`snippets/`](../snippets/) - Java/Kotlin examples for all MSAL operations
38+
**Golden Apps:** [`examples/hello-msal-multiple-account/`](../examples/hello-msal-multiple-account/) (default) | [`examples/hello-msal-single-account/`](../examples/hello-msal-single-account/)
39+
**Config Template:** [`auth_config.template.json`](../auth_config.template.json) - [Raw URL](https://raw.githubusercontent.com/AzureAD/microsoft-authentication-library-for-android/dev/auth_config.template.json)
40+
**Extended Rules:** [`Ai.md`](../Ai.md) - [Raw URL](https://raw.githubusercontent.com/AzureAD/microsoft-authentication-library-for-android/dev/Ai.md) | [`.clinerules/msal-cline-rules.md`](../.clinerules/msal-cline-rules.md) - [Raw URL](https://raw.githubusercontent.com/AzureAD/microsoft-authentication-library-for-android/dev/.clinerules/msal-cline-rules.md)
41+
42+
**Direct URLs for AI Agents:**
43+
- Multiple Account Example: https://github.com/AzureAD/microsoft-authentication-library-for-android/tree/dev/examples/hello-msal-multiple-account
44+
- Single Account Example: https://github.com/AzureAD/microsoft-authentication-library-for-android/tree/dev/examples/hello-msal-single-account
45+
46+
## 3. API Patterns & Validation
47+
48+
### ✅ Correct Patterns (Copy from snippets/)
49+
```java
50+
// Multiple Account: Token acquisition
51+
AcquireTokenParameters params = new AcquireTokenParameters.Builder()
52+
.withScopes(SCOPES).withCallback(callback).build();
53+
mPCA.acquireToken(params);
54+
55+
// Silent refresh
56+
AcquireTokenSilentParameters silentParams = new AcquireTokenSilentParameters.Builder()
57+
.withScopes(SCOPES).forAccount(account).withCallback(callback).build();
58+
mPCA.acquireTokenSilent(silentParams);
59+
60+
// Single Account: Sign in
61+
SignInParameters signInParams = new SignInParameters.Builder()
62+
.startActivity(activity).withCallback(callback).build();
63+
mPCA.signIn(signInParams);
64+
```
65+
66+
### ❌ Forbidden Patterns
67+
```java
68+
// NEVER use these deprecated methods:
69+
mPCA.acquireToken(activity, scopes, callback); // ❌ Deprecated
70+
mPCA.acquireTokenSilentAsync(scopes, account, authority, callback); // ❌ Deprecated
71+
```
72+
73+
### Required Dependencies & Setup
74+
```gradle
75+
// build.gradle (app level)
76+
minSdk 24, targetSdk 35, compileSdk 35
77+
implementation "com.microsoft.identity.client:msal:7.+"
78+
```
79+
80+
```properties
81+
// gradle.properties
82+
android.useAndroidX=true
83+
android.enableJetifier=true
84+
```
85+
86+
## 4. Debugging & Pattern Detection
87+
88+
### 🔍 Common Issues to Check For
89+
**Configuration Errors:**
90+
- Missing URL encoding: `redirect_uri` in auth_config.json must be URL encoded (`%2A` not `*`)
91+
- Wrong account mode APIs: Never use `getCurrentAccount()` in multiple account apps
92+
- Missing broker config: Always set `"broker_redirect_uri_registered": true`
93+
94+
**Code Smells:**
95+
- Arrays instead of ArrayList/List for account management
96+
- Missing `runOnUiThread()` for UI updates
97+
- No PCA initialization validation before MSAL calls
98+
- Hard-coded resource references that don't exist
99+
100+
**Validation Pattern:**
101+
```java
102+
// Always validate before MSAL operations
103+
if (mPCA == null) {
104+
// Handle initialization error
105+
return;
106+
}
107+
```
108+
109+
### 🛠️ Enable Debugging
110+
```java
111+
// Add to app initialization
112+
Logger.getInstance().setLogLevel(Logger.LogLevel.VERBOSE);
113+
Logger.getInstance().setEnablePII(true); // Only for debugging
114+
```
115+
116+
### 🔧 UI Logic Validation
117+
**Multiple Account Mode:**
118+
- Spinner index 0: "No Account Selected"
119+
- Sign-in: Always enabled
120+
- Sign-out/Silent token: Only enabled when account selected
121+
122+
**Single Account Mode:**
123+
- Sign-in: Enabled when NOT signed in (`!isSignedIn`)
124+
- Sign-out: Enabled when signed in (`isSignedIn`)
125+
- Silent token/Call Graph: Enabled when signed in (`isSignedIn`)
126+
127+
## 5. Quick Reference
128+
129+
| Component | Multiple Account API | Single Account API |
130+
|-----------|---------------------|-------------------|
131+
| Interface | `IMultipleAccountPublicClientApplication` | `ISingleAccountPublicClientApplication` |
132+
| Sign In | `acquireToken(parameters)` | `signIn(parameters)` |
133+
| Sign Out | `removeAccount(account, callback)` | `signOut(callback)` |
134+
| Get Accounts | `getAccounts(callback)` | `getCurrentAccount(callback)` |
135+
| Silent Token | `acquireTokenSilent(parameters)` | `acquireTokenSilent(parameters)` |
136+
137+
### Critical Encoding Rules
138+
| File | Signature Hash | Example |
139+
|------|----------------|---------|
140+
| AndroidManifest.xml | **NOT** URL encoded | `/ABcDeFg*okk=` |
141+
| auth_config.json | **URL encoded** | `ABcDeFg%2Aokk%3D` |
142+
143+
### Mandatory Files Checklist
144+
- [ ] `auth_config.json` in `res/raw/` with URL-encoded redirect_uri
145+
- [ ] AndroidManifest.xml with non-URL-encoded signature hash in intent-filter
146+
- [ ] Required permissions: `INTERNET`, `ACCESS_NETWORK_STATE`
147+
- [ ] MSAL 7.+ dependency in build.gradle
148+
- [ ] AndroidX enabled in gradle.properties
149+
150+
### Template Usage
151+
**Always use:** `auth_config.template.json` for configuration structure
152+
**Copy exactly:** Gradle files from golden examples (only change applicationId/namespace)
153+
**Resource structure:** Follow golden examples for res/ directory layout
154+
155+
**Remember:** When in doubt, check snippets/ directory first, then golden examples. Never invent patterns.

‎Ai.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -115,7 +115,7 @@ android {
115115
}
116116
117117
dependencies {
118-
def msalVersion = "6.+"
118+
def msalVersion = "7.+"
119119
120120
implementation "com.microsoft.identity.client:msal:${msalVersion}"
121121
implementation 'androidx.appcompat:appcompat:1.6.1'
@@ -172,7 +172,7 @@ Add these activities to your AndroidManifest.xml inside the `<application>` tag:
172172
## Important Notes
173173
1. The signature hash in AndroidManifest.xml should NOT be URL encoded
174174
2. The redirect URI in auth_config.json MUST be URL encoded
175-
3. The latest MSAL version (6.+ or newer) should be used
175+
3. The latest MSAL version (7.+ or newer) should be used
176176
4. Broker integration (Microsoft Authenticator, Company Portal, or Link To Windows) is strongly recommended and should always be enabled for enhanced security and SSO capabilities. Only disable broker integration if explicitly required by the user. See broker_redirect_uri_registered field in [auth_config.template.json](./auth_config.template.json) for configuration.
177177
5. Device Code Flow is not recommended due to security concerns in the industry. The AcquireToken authentication method should be used instead. There are some niche scenarios where some devices lack the input methods necessary for AcquireToken, and need to use AcquireTokenWithDeviceCode.
178178

‎common‎

Submodule common updated 9 files

0 commit comments

Comments
 (0)