Add emphemeral browser option to macOS user agent.

Adds BOOL arguments to macOS-related methods which allow setting the ASWebAuthenticationSession property prefersEphemeralWebBrowserSession.

Author: danblakemore

Source/AppAuth/macOS/OIDAuthState+Mac.h

@@ -41,13 +41,39 @@ NS_ASSUME_NONNULL_BEGIN
     @return A @c OIDExternalUserAgentSession instance which will terminate when it
         receives a @c OIDExternalUserAgentSession.cancel message, or after processing a
         @c OIDExternalUserAgentSession.resumeExternalUserAgentFlowWithURL: message.
-    @discussion This method adopts ASWebAuthenticationSession for macOS 10.15 and above or the default browser otherwise.
+    @discussion This method adopts ASWebAuthenticationSession for macOS 10.15 and above or the
+        default browser otherwise.
  */
 + (id<OIDExternalUserAgentSession>)
     authStateByPresentingAuthorizationRequest:(OIDAuthorizationRequest *)authorizationRequest
                              presentingWindow:(NSWindow *)presentingWindow
                                      callback:(OIDAuthStateAuthorizationCallback)callback;
 
+/*! @brief Convenience method to create a @c OIDAuthState by presenting an authorization request
+        (optionally using an emphemeral browser session that shares no cookies or data with the
+        normal browser session) and performing the authorization code exchange in the case of code
+        flow requests. For the hybrid flow, the caller should validate the id_token and c_hash, then
+        perform the token request (@c OIDAuthorizationService.performTokenRequest:callback:)
+        and update the OIDAuthState with the results using
+        @c OIDAuthState.updateWithTokenResponse:error:.
+    @param authorizationRequest The authorization request to present.
+    @param presentingWindow The window to present the authentication flow.
+    @param prefersEphemeralSession Whether the caller prefers to use a private authentication
+        session. See @c ASWebAuthenticationSession.prefersEphemeralWebBrowserSession for more.
+    @param callback The method called when the request has completed or failed.
+    @return A @c OIDExternalUserAgentSession instance which will terminate when it
+        receives a @c OIDExternalUserAgentSession.cancel message, or after processing a
+        @c OIDExternalUserAgentSession.resumeExternalUserAgentFlowWithURL: message.
+    @discussion This method adopts ASWebAuthenticationSession for macOS 10.15 and above or the
+        default browser otherwise.
+ */
++ (id<OIDExternalUserAgentSession>)
+    authStateByPresentingAuthorizationRequest:(OIDAuthorizationRequest *)authorizationRequest
+                             presentingWindow:(NSWindow *)presentingWindow
+                      prefersEphemeralSession:(BOOL)prefersEphemeralSession
+                                     callback:(OIDAuthStateAuthorizationCallback)callback
+    API_AVAILABLE(macos(10.15));
+
 /*! @param authorizationRequest The authorization request to present.
     @param callback The method called when the request has completed or failed.
     @return A @c OIDExternalUserAgentSession instance which will terminate when it

Source/AppAuth/macOS/OIDAuthState+Mac.m

@@ -35,6 +35,18 @@ @implementation OIDAuthState (Mac)
                                        externalUserAgent:externalUserAgent
                                                 callback:callback];
 }
++ (id<OIDExternalUserAgentSession>)
+    authStateByPresentingAuthorizationRequest:(OIDAuthorizationRequest *)authorizationRequest
+                             presentingWindow:(NSWindow *)presentingWindow
+                      prefersEphemeralSession:(BOOL)prefersEphemeralSession
+                                     callback:(OIDAuthStateAuthorizationCallback)callback {
+  OIDExternalUserAgentMac *externalUserAgent =
+      [[OIDExternalUserAgentMac alloc] initWithPresentingWindow:presentingWindow
+                                        prefersEphemeralSession:prefersEphemeralSession];
+  return [self authStateByPresentingAuthorizationRequest:authorizationRequest
+                                       externalUserAgent:externalUserAgent
+                                                callback:callback];
+}
 
 + (id<OIDExternalUserAgentSession>)
     authStateByPresentingAuthorizationRequest:(OIDAuthorizationRequest *)authorizationRequest

Source/AppAuth/macOS/OIDAuthorizationService+Mac.h

@@ -42,6 +42,24 @@ NS_ASSUME_NONNULL_BEGIN
                                                presentingWindow:(NSWindow *)presentingWindow
                                                        callback:(OIDAuthorizationCallback)callback;
 
+/*! @brief Perform an authorization flow using the @c ASWebAuthenticationSession optionally using an
+        emphemeral browser session that shares no cookies or data with the normal browser session.
+    @param request The authorization request.
+    @param presentingWindow The window to present the authentication flow.
+    @param prefersEphemeralSession Whether the caller prefers to use a private authentication
+        session. See @c ASWebAuthenticationSession.prefersEphemeralWebBrowserSession for more.
+    @param callback The method called when the request has completed or failed.
+    @return A @c OIDExternalUserAgentSession instance which will terminate when it
+        receives a @c OIDExternalUserAgentSession.cancel message, or after processing a
+        @c OIDExternalUserAgentSession.resumeExternalUserAgentFlowWithURL: message.
+    @discussion This method adopts  ASWebAuthenticationSession for macOS 10.15 and above or the default browser otherwise.
+ */
++ (id<OIDExternalUserAgentSession>) presentAuthorizationRequest:(OIDAuthorizationRequest *)request
+                                               presentingWindow:(NSWindow *)presentingWindow
+                                        prefersEphemeralSession:(BOOL)prefersEphemeralSession
+                                                       callback:(OIDAuthorizationCallback)callback
+    API_AVAILABLE(macos(10.15));
+
 /*! @brief Perform an authorization flow using the default browser.
     @param request The authorization request.
     @param callback The method called when the request has completed or failed.

Source/AppAuth/macOS/OIDAuthorizationService+Mac.m

@@ -37,6 +37,18 @@ @implementation OIDAuthorizationService (Mac)
                                   callback:callback];
 }
 
++ (id<OIDExternalUserAgentSession>) presentAuthorizationRequest:(OIDAuthorizationRequest *)request
+                                               presentingWindow:(NSWindow *)presentingWindow
+                                        prefersEphemeralSession:(BOOL)prefersEphemeralSession
+                                                       callback:(OIDAuthorizationCallback)callback {
+  OIDExternalUserAgentMac *externalUserAgent =
+      [[OIDExternalUserAgentMac alloc] initWithPresentingWindow:presentingWindow
+                                        prefersEphemeralSession:prefersEphemeralSession];
+  return [self presentAuthorizationRequest:request
+                         externalUserAgent:externalUserAgent
+                                  callback:callback];
+}
+
 + (id<OIDExternalUserAgentSession>) presentAuthorizationRequest:(OIDAuthorizationRequest *)request
                                                        callback:(OIDAuthorizationCallback)callback {
   OIDExternalUserAgentMac *externalUserAgent = [[OIDExternalUserAgentMac alloc] init];

Source/AppAuth/macOS/OIDExternalUserAgentMac.h

@@ -35,6 +35,15 @@ NS_ASSUME_NONNULL_BEGIN
  */
 - (instancetype)initWithPresentingWindow:(NSWindow *)presentingWindow NS_DESIGNATED_INITIALIZER;
 
+/*! @brief Create an iOS user-agent which optionally uses a private authentication session.
+ @param presentingWindow The window from which to present the ASWebAuthenticationSession.
+ @param prefersEphemeralSession Whether the caller prefers to use a private authentication
+ session. See @c ASWebAuthenticationSession.prefersEphemeralWebBrowserSession for more.
+ */
+- (nullable instancetype)initWithPresentingWindow:(NSWindow *)presentingWindow
+                          prefersEphemeralSession:(BOOL)prefersEphemeralSession
+    API_AVAILABLE(macos(10.15));
+
 - (instancetype)init __deprecated_msg("Use initWithPresentingWindow for macOS 10.15 and above.");
 
 @end

Source/AppAuth/macOS/OIDExternalUserAgentMac.m

@@ -38,6 +38,7 @@ @interface OIDExternalUserAgentMac ()<ASWebAuthenticationPresentationContextProv
 @implementation OIDExternalUserAgentMac {
   BOOL _externalUserAgentFlowInProgress;
   __weak id<OIDExternalUserAgentSession> _session;
+  BOOL _prefersEphemeralSession;
 
   NSWindow *_presentingWindow;
 #pragma clang diagnostic push
@@ -54,6 +55,15 @@ - (instancetype)initWithPresentingWindow:(NSWindow *)presentingWindow {
   return self;
 }
 
+- (nullable instancetype)initWithPresentingWindow:(NSWindow *)presentingWindow
+                          prefersEphemeralSession:(BOOL)prefersEphemeralSession {
+  self = [self initWithPresentingWindow:presentingWindow];
+  if (self) {
+    _prefersEphemeralSession = prefersEphemeralSession;
+  }
+  return self;
+}
+
 - (instancetype)init {
 #pragma clang diagnostic push
 #pragma clang diagnostic ignored "-Wnonnull"
@@ -100,6 +110,7 @@ - (BOOL)presentExternalUserAgentRequest:(id<OIDExternalUserAgentRequest>)request
       authenticationSession.presentationContextProvider = self;
 
       _webAuthenticationSession = authenticationSession;
+      _webAuthenticationSession.prefersEphemeralWebBrowserSession = _prefersEphemeralSession;
       return [authenticationSession start];
     }
   }