Cline rules

1# MSAL API Usage Examples
2 
3This document provides code snippets for common MSAL authentication patterns in both Swift and Objective-C.
4 
5## Interactive Token Acquisition
6 
7Interactive token acquisition presents a UI to the user for authentication. This is typically used for initial sign-in or when a silent token acquisition fails.
8 
9### Swift
10 
11```swift
12import MSAL
13 
14// Configure the application
15let config = MSALPublicClientApplicationConfig(clientId: "YOUR_CLIENT_ID")
16let application = try MSALPublicClientApplication(configuration: config)
17 
18// Configure webview parameters
19let webViewParameters = MSALWebviewParameters(authPresentationViewController: self)
20 
21// Create interactive token parameters
22let interactiveParameters = MSALInteractiveTokenParameters(scopes: ["user.read"], 
23                                                           webviewParameters: webViewParameters)
24 
25// Acquire token interactively
26application.acquireToken(with: interactiveParameters) { (result, error) in
27    guard let result = result else {
28        print("Could not acquire token: \(error?.localizedDescription ?? "Unknown error")")
29        return
30    }
31    
32    let accessToken = result.accessToken
33    let account = result.account
34    print("Access token acquired: \(accessToken)")
35    print("Account: \(account.username ?? "Unknown")")
36}
37```
38 
39### Objective-C
40 
41```objc
42#import <MSAL/MSAL.h>
43 
44// Configure the application
45MSALPublicClientApplicationConfig *config = 
46    [[MSALPublicClientApplicationConfig alloc] initWithClientId:@"YOUR_CLIENT_ID"];
47 
48NSError *error = nil;
49MSALPublicClientApplication *application = 
50    [[MSALPublicClientApplication alloc] initWithConfiguration:config error:&error];
51 
52if (error) {
53    NSLog(@"Failed to create application: %@", error);
54    return;
55}
56 
57// Configure webview parameters
58MSALWebviewParameters *webViewParameters = 
59    [[MSALWebviewParameters alloc] initWithAuthPresentationViewController:self];
60 
61// Create interactive token parameters
62MSALInteractiveTokenParameters *interactiveParams = 
63    [[MSALInteractiveTokenParameters alloc] initWithScopes:@[@"user.read"]
64                                         webviewParameters:webViewParameters];
65 
66// Acquire token interactively
67[application acquireTokenWithParameters:interactiveParams 
68                        completionBlock:^(MSALResult * _Nullable result, NSError * _Nullable error) {
69    if (error) {
70        NSLog(@"Could not acquire token: %@", error);
71        return;
72    }
73    
74    NSString *accessToken = result.accessToken;
75    MSALAccount *account = result.account;
76    NSLog(@"Access token acquired: %@", accessToken);
77    NSLog(@"Account: %@", account.username);
78}];
79```
80 
81## Silent Token Acquisition
82 
83Silent token acquisition attempts to get a token without user interaction, using cached tokens or refresh tokens. This is the recommended approach for acquiring tokens in most scenarios.
84 
85### Swift
86 
87```swift
88import MSAL
89 
90// Configure the application
91let config = MSALPublicClientApplicationConfig(clientId: "YOUR_CLIENT_ID")
92let application = try MSALPublicClientApplication(configuration: config)
93 
94// Get the account (from previous interactive sign-in)
95guard let account = try application.accountForIdentifier("ACCOUNT_IDENTIFIER") else {
96    print("Account not found")
97    return
98}
99 
100// Create silent token parameters
101let silentParameters = MSALSilentTokenParameters(scopes: ["user.read"], 
102                                                 account: account)
103 
104// Acquire token silently
105application.acquireTokenSilent(with: silentParameters) { (result, error) in
106    if let error = error as NSError? {
107        // Check if interaction is required
108        if error.domain == MSALErrorDomain && 
109           error.code == MSALError.interactionRequired.rawValue {
110            // Fall back to interactive token acquisition
111            print("Interaction required, use interactive flow")
112        } else {
113            print("Could not acquire token silently: \(error.localizedDescription)")
114        }
115        return
116    }
117    
118    guard let result = result else {
119        print("No result returned")
120        return
121    }
122    
123    let accessToken = result.accessToken
124    print("Access token acquired silently: \(accessToken)")
125}
126```
127 
128### Objective-C
129 
130```objc
131#import <MSAL/MSAL.h>
132 
133// Configure the application
134MSALPublicClientApplicationConfig *config = 
135    [[MSALPublicClientApplicationConfig alloc] initWithClientId:@"YOUR_CLIENT_ID"];
136 
137NSError *error = nil;
138MSALPublicClientApplication *application = 
139    [[MSALPublicClientApplication alloc] initWithConfiguration:config error:&error];
140 
141if (error) {
142    NSLog(@"Failed to create application: %@", error);
143    return;
144}
145 
146// Get the account (from previous interactive sign-in)
147MSALAccount *account = [application accountForIdentifier:@"ACCOUNT_IDENTIFIER" error:&error];
148 
149if (!account) {
150    NSLog(@"Account not found");
151    return;
152}
153 
154// Create silent token parameters
155MSALSilentTokenParameters *silentParams = 
156    [[MSALSilentTokenParameters alloc] initWithScopes:@[@"user.read"] 
157                                              account:account];
158 
159// Acquire token silently
160[application acquireTokenSilentWithParameters:silentParams 
161                              completionBlock:^(MSALResult * _Nullable result, NSError * _Nullable error) {
162    if (error) {
163        // Check if interaction is required
164        if ([error.domain isEqualToString:MSALErrorDomain] && 
165            error.code == MSALErrorInteractionRequired) {
166            // Fall back to interactive token acquisition
167            NSLog(@"Interaction required, use interactive flow");
168        } else {
169            NSLog(@"Could not acquire token silently: %@", error);
170        }
171        return;
172    }
173    
174    NSString *accessToken = result.accessToken;
175    NSLog(@"Access token acquired silently: %@", accessToken);
176}];
177```
178 
179## Best Practices
180 
1811. **Always try silent acquisition first**: Before prompting the user, attempt to acquire a token silently using `acquireTokenSilentWithParameters:completionBlock:`.
182 
1832. **Handle interaction required errors**: When silent acquisition fails with `MSALErrorInteractionRequired`, fall back to interactive acquisition using `acquireTokenWithParameters:completionBlock:`.
184 
1853. **Cache the account identifier**: Store the account identifier (`account.identifier`) after successful interactive sign-in for use in subsequent silent token requests.
186 
1874. **Use appropriate scopes**: Request only the scopes your application needs. The Microsoft Graph API uses scopes like `user.read`, `mail.read`, etc.
188 
1895. **Configure the application once**: Create a single instance of `MSALPublicClientApplication` and reuse it throughout your app's lifecycle.
190 
1916. **Handle errors gracefully**: Implement proper error handling for network issues, user cancellations, and authentication failures.
192 
1937. **Use MSALPublicClientApplicationConfig**: Always initialize MSAL using `MSALPublicClientApplicationConfig` to take advantage of all configuration options.
194 
195## Additional Resources
196 
197- For more information about MSAL scopes, see the Microsoft Graph permissions reference
198- For authority configuration, see the Azure AD documentation on authentication endpoints
199- For broker integration on iOS, ensure your redirect URI is properly configured in the Azure portal
200