feat(auth): Add OIDC support types & docs (#3064) (#3082)

* feat(auth): Add definitions for supporting OIDC plugin
* chore: OIDC support API docs
* feat: Add default reset method for Plugins
* test: Add TaskQueue sync test; chore: Document TaskQueue
* feat: Add default conformance to AuthAWSCredentialsProvider.getAWSCredentials()
* feat: Add default conformance for AuthCognitoIdentityProvider methods

---------

Co-authored-by: Tim Schmelter <[email protected]>

Author: thisisabhash

Amplify/Categories/Auth/AuthCategoryBehavior.swift

@@ -49,7 +49,7 @@ public protocol AuthCategoryBehavior: AuthCategoryUserBehavior, AuthCategoryDevi
     /// SignIn to the authentication provider
     ///
     /// Username and password are optional values, check the plugin documentation to decide on what all values need to
-    /// passed. For example in a passwordless flow you just need to pass the username and the passwordcould be nil.
+    /// passed. For example in a passwordless flow you just need to pass the username and the password could be nil.
     ///
     /// - Parameters:
     ///   - username: Username to signIn the user

Amplify/Categories/Auth/Models/AuthSession.swift

@@ -10,10 +10,19 @@ import Foundation
 /// Defines the auth session behavior
 public protocol AuthSession {
 
-    /// Indicates whether a user is signed in or not
+    /// True if the current user has signed in
     ///
-    /// `true` if a user is authenticated. `isSignedIn` remains `true` till we call `Amplify.Auth.signOut`.
-    /// Please note that this value remains `true` even when the session is expired. Refer the underlying plugin
-    /// documentation regarding how to handle session expiry.
+    /// App developers can use this flag to make local decisions about the content to display (e.g., "Should I show this protected
+    /// page?") but cannot use it to make any further assertions about whether a network operation is likely to succeed or not.
+    ///
+    /// `true` if a user has authenticated, via any of:
+    /// - ``AuthCategoryBehavior/signIn(username:password:options:)``
+    /// - ``AuthCategoryBehavior/signInWithWebUI(presentationAnchor:options:)``
+    /// - ``AuthCategoryBehavior/signInWithWebUI(for:presentationAnchor:options:)``
+    /// - A plugin-specific sign in method like
+    ///   `AWSCognitoAuthPlugin.federateToIdentityPool(withProviderToken:for:options:)`
+    ///
+    /// `isSignedIn` remains `true` until we call `Amplify.Auth.signOut`. Notably, this value remains `true`
+    /// even when the session is expired. Refer the underlying plugin documentation regarding how to handle session expiry.
     var isSignedIn: Bool { get }
 }

Amplify/Core/Support/TaskQueue.swift

@@ -7,11 +7,23 @@
 
 import Foundation
 
+/// A helper for executing asynchronous work serially.
 public actor TaskQueue<Success> {
     private var previousTask: Task<Success, Error>?
 
     public init() {}
 
+    /// Serializes asynchronous requests made from an async context
+    ///
+    /// Given an invocation like
+    /// ```swift
+    /// let tq = TaskQueue<Int>()
+    /// let v1 = try await tq.sync { try await doAsync1() }
+    /// let v2 = try await tq.sync { try await doAsync2() }
+    /// let v3 = try await tq.sync { try await doAsync3() }
+    /// ```
+    /// TaskQueue serializes this work so that `doAsync1` is performed before `doAsync2`,
+    /// which is performed before `doAsync3`.
     public func sync(block: @Sendable @escaping () async throws -> Success) async throws -> Success {
         let currentTask: Task<Success, Error> = Task { [previousTask] in
             _ = await previousTask?.result

AmplifyPlugins/Core/AWSPluginsCore/Auth/AWSAuthSessionBehavior.swift

@@ -0,0 +1,55 @@
+//
+// Copyright Amazon.com Inc. or its affiliates.
+// All Rights Reserved.
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+
+import Foundation
+import Amplify
+
+/// Defines the contract for an AuthSession that can vend AWS credentials and store a user ID
+/// (`sub`) for the underlying OIDC-compliant authentication provider such as Cognito user pools.
+/// Concrete types that use Cognito identity pools to obtain AWS credentials can also vend the
+/// associated identityID.
+///
+/// **The `isSignedIn` property**
+///
+/// Types conforming to the `AuthSession` protocol support an `isSignedIn` flag. `isSignedIn` is true if a user has
+/// successfully completed a `signIn` flow, and has not subsequently signed out.
+public protocol AWSAuthSessionBehavior<Tokens> : AuthSession {
+
+    /// The concrete type holding the OIDC tokens from the authentication provider. Generally, this type will have at least
+    /// methods for retrieving an identity token and an access token.
+    associatedtype Tokens
+
+    /// The result of the most recent attempt to get AWS Credentials. There is no guarantee that the credentials
+    /// are not expired, but conforming types may have logic in place to automatically refresh the credentials.
+    /// The credentials may be fore either the unauthenticated or authenticated role, depending on the configuration of the
+    /// identity pool and the tokens used to retrieve the identity ID from Cognito.
+    ///
+    /// If the most recent attempt caused an error, the result will contain the details of the error.
+    var awsCredentialsResult: Result<AWSTemporaryCredentials, AuthError> { get }
+
+    /// The result of the most recent attempt to get a
+    /// [Cognito identity pool identity ID](https://docs.aws.amazon.com/cognitoidentity/latest/APIReference/API_GetId.html#CognitoIdentity-GetId-response-IdentityId).
+    /// The identityID may represent either an unauthenticated or authenticated identity, depending on the configuration of the
+    /// identity pool and the tokens used to retrieve the identity ID from Cognito.
+    ///
+    /// If the most recent attempt caused an error, the result will contain the details of the error.
+    var identityIdResult: Result<String, AuthError> { get }
+
+    /// The result of the most recent attempt to get the current user's `sub` (unique User ID). Depending on the underlying
+    /// implementation, the details of the user ID may vary, but it is expected that this value is the `sub` claim of the
+    /// OIDC identity and access tokens.
+    ///
+    /// If the most recent attempt caused an error, the result will contain the details of the error.
+    var userSubResult: Result<String, AuthError> { get }
+
+    /// The result of the most recent attempt to get the current user's `sub` (unique User ID). Depending on the underlying
+    /// implementation, the details of the tokens may vary, but it is expected that the type will have at least methods for
+    /// retrieving an identity token and an access token.
+    ///
+    /// If the most recent attempt caused an error, the result will contain the details of the error.
+    var oidcTokensResult: Result<Tokens, AuthError> { get }
+}

AmplifyPlugins/Core/AWSPluginsCore/Auth/Provider/AuthAWSCredentialsProvider.swift

@@ -9,9 +9,28 @@ import Amplify
 import Foundation
 
 public protocol AuthAWSCredentialsProvider {
+    /// Return the most recent Result of fetching the AWS Credentials
     func getAWSCredentials() -> Result<AWSCredentials, AuthError>
 }
 
+public extension AuthAWSCredentialsProvider where Self:AWSAuthSessionBehavior {
+    /// Return the most recent Result of fetching the AWS Credentials. If the temporary credentials are expired, returns
+    /// a `AuthError.sessionExpired` failure.
+    func getAWSCredentials() -> Result<AWSCredentials, AuthError> {
+        let result: Result<AWSCredentials, AuthError>
+        switch awsCredentialsResult {
+        case .failure(let error): result = .failure(error)
+        case .success(let tempCreds):
+            if tempCreds.expiration > Date() {
+                result = .success(tempCreds)
+            } else {
+                result = .failure(AuthError.sessionExpired("AWS Credentials are expired", ""))
+            }
+        }
+        return result
+    }
+}
+
 public protocol AWSCredentialsProvider {
     func fetchAWSCredentials() async throws -> AWSCredentials
 }

AmplifyPlugins/Core/AWSPluginsCore/Auth/Provider/AuthCognitoIdentityProvider.swift

@@ -8,7 +8,19 @@
 import Amplify
 
 public protocol AuthCognitoIdentityProvider {
+    /// Return the most recent Result of fetching the AWS Cognito Identity Pools identity ID
     func getIdentityId() -> Result<String, AuthError>
 
+    /// Return the most recent Result of the current user’s sub claim (user ID)
     func getUserSub() -> Result<String, AuthError>
 }
+
+public extension AuthCognitoIdentityProvider where Self:AWSAuthSessionBehavior {
+    func getIdentityId() -> Result<String, AuthError> {
+        identityIdResult
+    }
+
+    func getUserSub() -> Result<String, AuthError> {
+        userSubResult
+    }
+}

AmplifyTests/CoreTests/AmplifyTaskQueueTests.swift

@@ -0,0 +1,69 @@
+//
+// Copyright Amazon.com Inc. or its affiliates.
+// All Rights Reserved.
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+
+import XCTest
+import Amplify
+
+// As expected, running this work as straight up Task invocations:
+
+// ```
+// try await Task {
+//     try await Task.sleep(nanoseconds: 1)
+//     expectation1.fulfill()
+// }
+// try await Task {
+//     try await Task.sleep(nanoseconds: 1)
+//     expectation2.fulfill()
+// }
+// try await Task {
+//     try await Task.sleep(nanoseconds: 1)
+//     expectation3.fulfill()
+// }
+// await fulfillment(of: [expectation1, expectation2, expectation3], enforceOrder: true)
+// ```
+//
+// does not guarantee order of execution. TaskQueue is intended to serialize execution to guarantee
+// that the in-process task completes before the new one is executed.
+
+final class AmplifyTaskQueueTests: XCTestCase {
+
+    /// Test basic TaskQueue.sync behavior
+    ///
+    /// - Given: A task queue
+    /// - When: I add tasks to the queue using the `sync` method
+    /// - Then: The tasks execute in the order added
+    func testSync() async throws {
+        for _ in 1 ... 1_000 {
+            try await doSyncTest()
+        }
+    }
+
+    func doSyncTest() async throws {
+        let expectation1 = expectation(description: "expectation1")
+        let expectation2 = expectation(description: "expectation2")
+        let expectation3 = expectation(description: "expectation3")
+
+        let taskQueue = TaskQueue<Void>()
+        try await taskQueue.sync {
+            try await Task.sleep(nanoseconds: 1)
+            expectation1.fulfill()
+        }
+
+        try await taskQueue.sync {
+            try await Task.sleep(nanoseconds: 1)
+            expectation2.fulfill()
+        }
+
+        try await taskQueue.sync {
+            try await Task.sleep(nanoseconds: 1)
+            expectation3.fulfill()
+        }
+
+        await fulfillment(of: [expectation1, expectation2, expectation3], enforceOrder: true)
+    }
+
+}