From 8187b0639f86f58020fe3f2ce5863a04a46c5ea6 Mon Sep 17 00:00:00 2001 From: Alex Nachbaur Date: Thu, 14 Nov 2024 13:54:38 -0800 Subject: [PATCH] Expose a public initializer for the WebAuthn response object, and clean up API doc errors --- .../AuthFoundation/AuthFoundation.docc/APIClient.md | 4 ---- .../AuthFoundation/AuthFoundation.docc/Credential.md | 4 ---- .../AuthFoundation/AuthFoundation.docc/Keychain.md | 4 ---- .../AuthFoundation.docc/OAuth2Client.md | 4 ---- Sources/AuthFoundation/JWT/JWT.swift | 2 +- Sources/AuthFoundation/JWT/Protocols/Claim.swift | 2 +- Sources/AuthFoundation/Responses/TokenInfo.swift | 2 +- Sources/AuthFoundation/Responses/UserInfo.swift | 2 +- Sources/AuthFoundation/Security/Keychain.swift | 5 ++++- Sources/AuthFoundation/Token Management/Token.swift | 4 +++- .../AuthFoundation/User Management/Credential.swift | 10 +++++++--- Sources/OktaDirectAuth/DirectAuthFlow.swift | 12 ++++++------ .../Extensions/DirectAuthenticationFlow.md | 12 +++++------- Sources/OktaDirectAuth/WebAuthn/WebAuthn.swift | 9 ++++++++- 14 files changed, 37 insertions(+), 39 deletions(-) diff --git a/Sources/AuthFoundation/AuthFoundation.docc/APIClient.md b/Sources/AuthFoundation/AuthFoundation.docc/APIClient.md index edae74186..38eb560a1 100644 --- a/Sources/AuthFoundation/AuthFoundation.docc/APIClient.md +++ b/Sources/AuthFoundation/AuthFoundation.docc/APIClient.md @@ -1,9 +1,5 @@ # ``AuthFoundation/APIClient`` -@Metadata { - @DocumentationExtension(mergeBehavior: append) -} - ## Subclassing Notes Many features of the APIClient protocol have default implementations that should serve most purposes, but there are some methods that either must be implemented in concrete instances of APIClient, or may need to be customized for special behavior. diff --git a/Sources/AuthFoundation/AuthFoundation.docc/Credential.md b/Sources/AuthFoundation/AuthFoundation.docc/Credential.md index 2e0a250b3..b10e7bf0e 100644 --- a/Sources/AuthFoundation/AuthFoundation.docc/Credential.md +++ b/Sources/AuthFoundation/AuthFoundation.docc/Credential.md @@ -1,9 +1,5 @@ # ``AuthFoundation/Credential`` -@Metadata { - @DocumentationExtension(mergeBehavior: append) -} - ## Storing Credentials The Credential class fundamentally is used as a convenience to simplify access and storage of ``Token``s. Regardless of how the token is created, it can be securely stored by using ``store(_:tags:security:)``. This saves the token for later use. diff --git a/Sources/AuthFoundation/AuthFoundation.docc/Keychain.md b/Sources/AuthFoundation/AuthFoundation.docc/Keychain.md index 409a6070c..bd3bfac96 100644 --- a/Sources/AuthFoundation/AuthFoundation.docc/Keychain.md +++ b/Sources/AuthFoundation/AuthFoundation.docc/Keychain.md @@ -1,9 +1,5 @@ # ``AuthFoundation/Keychain`` -@Metadata { - @DocumentationExtension(mergeBehavior: append) -} - ## Creating Keychain Items The ``Keychain/Item`` struct represents individual items in the keychain. It can be used to create new items, and is returned as a result when getting an existing item. diff --git a/Sources/AuthFoundation/AuthFoundation.docc/OAuth2Client.md b/Sources/AuthFoundation/AuthFoundation.docc/OAuth2Client.md index 18519e98a..61c15caa8 100644 --- a/Sources/AuthFoundation/AuthFoundation.docc/OAuth2Client.md +++ b/Sources/AuthFoundation/AuthFoundation.docc/OAuth2Client.md @@ -1,9 +1,5 @@ # ``AuthFoundation/OAuth2Client`` -@Metadata { - @DocumentationExtension(mergeBehavior: append) -} - This class serves two purposes: 1. Expose high-level actions a client can perform against an OAuth2 service. 2. Connect authentication flows to the OAuth2 servers they intend to authenticate against. diff --git a/Sources/AuthFoundation/JWT/JWT.swift b/Sources/AuthFoundation/JWT/JWT.swift index 64b6f7632..e697b0ca2 100644 --- a/Sources/AuthFoundation/JWT/JWT.swift +++ b/Sources/AuthFoundation/JWT/JWT.swift @@ -72,7 +72,7 @@ public struct JWT: RawRepresentable, Codable, HasClaims, Expires { } /// Verifies the JWT token using the given ``JWK`` key. - /// - Parameter key: JWK key to use to verify this token. + /// - Parameter keySet: JWK key to use to verify this token. /// - Returns: Returns whether or not signing passes for this token/key combination. /// - Throws: ``JWTError`` public func validate(using keySet: JWKS) throws -> Bool { diff --git a/Sources/AuthFoundation/JWT/Protocols/Claim.swift b/Sources/AuthFoundation/JWT/Protocols/Claim.swift index a49784c6e..c7d58df0e 100644 --- a/Sources/AuthFoundation/JWT/Protocols/Claim.swift +++ b/Sources/AuthFoundation/JWT/Protocols/Claim.swift @@ -21,7 +21,7 @@ public protocol IsClaim { /// Used by classes that contains OAuth2 claims. /// -/// This provides common conveniences for interacting with user or token information within those claims. For example, iterating through ``allClaims-4c54a`` or using keyed subscripting to access specific claims. +/// This provides common conveniences for interacting with user or token information within those claims. For example, iterating through ``allClaims`` or using keyed subscripting to access specific claims. public protocol HasClaims { associatedtype ClaimType: IsClaim diff --git a/Sources/AuthFoundation/Responses/TokenInfo.swift b/Sources/AuthFoundation/Responses/TokenInfo.swift index 8a5e20832..b5c00c671 100644 --- a/Sources/AuthFoundation/Responses/TokenInfo.swift +++ b/Sources/AuthFoundation/Responses/TokenInfo.swift @@ -16,7 +16,7 @@ import Foundation /// /// This provides a convenience mechanism for accessing information related to a token. It supports the ``HasClaims`` protocol, to simplify common operations against introspected information, and to provide consistency with the ``JWT`` class. /// -/// For more information about the members to use, please refer to ``ClaimContainer``. +/// For more information about the members to use, please refer to ``JSONClaimContainer``. public struct TokenInfo: Codable, JSONClaimContainer { public typealias ClaimType = JWTClaim diff --git a/Sources/AuthFoundation/Responses/UserInfo.swift b/Sources/AuthFoundation/Responses/UserInfo.swift index 65617800c..21c0388c8 100644 --- a/Sources/AuthFoundation/Responses/UserInfo.swift +++ b/Sources/AuthFoundation/Responses/UserInfo.swift @@ -16,7 +16,7 @@ import Foundation /// /// This provides a convenience mechanism for accessing information related to a user. It supports the ``HasClaims`` protocol, to simplify common operations against user information, and to provide consistency with the ``JWT`` class. /// -/// For more information about the members to use, please refer to ``ClaimContainer``. +/// For more information about the members to use, please refer to ``JSONClaimContainer``. public struct UserInfo: Codable, JSONClaimContainer { public typealias ClaimType = JWTClaim diff --git a/Sources/AuthFoundation/Security/Keychain.swift b/Sources/AuthFoundation/Security/Keychain.swift index cc8c080f1..42b878b0f 100644 --- a/Sources/AuthFoundation/Security/Keychain.swift +++ b/Sources/AuthFoundation/Security/Keychain.swift @@ -115,13 +115,15 @@ public struct Keychain { /// - Parameters: /// - account: The account ID or key to use for this item. /// - service: The service to group similar items together. + /// - server: The server to group similar items together. /// - accessibility: Defines when the item may be retrieved, based on device state. /// - accessGroup: The access group to store this item within. + /// - accessControl: Optional keychain security access control reference. /// - synchronizable: Indicates if this keychain item may be synchronized to iCloud Keychain. /// - label: The human-readable label to summarize this item. /// - description: The human-readable description to add notes related to this item. /// - generic: Generic data associated with this item, which may always be read and is not restricted by the ``accessibility`` option. - /// - valueData: The secret value for this item. + /// - value: The secret value for this item. public init(account: String, service: String? = nil, server: String? = nil, @@ -246,6 +248,7 @@ public struct Keychain { /// - Parameters: /// - account: The account to search for, or `nil` to return all accounts. /// - service: The service to search for, or `nil` to return all services. + /// - server: The server to search for, or `nil` to return all servers. /// - accessGroup: The access group to search within, or `nil` to return all access groups. public init(account: String? = nil, service: String? = nil, server: String? = nil, accessGroup: String? = nil) { self.account = account diff --git a/Sources/AuthFoundation/Token Management/Token.swift b/Sources/AuthFoundation/Token Management/Token.swift index 423618401..0290caed4 100644 --- a/Sources/AuthFoundation/Token Management/Token.swift +++ b/Sources/AuthFoundation/Token Management/Token.swift @@ -79,7 +79,9 @@ public final class Token: Codable, Equatable, Hashable, Expires { } /// Validates the claims within this JWT token, to ensure it matches the given ``OAuth2Client``. - /// - Parameter client: Client to validate the token's claims against. + /// - Parameters: + /// - client: Client to validate the token's claims against. + /// - context: Optional ``IDTokenValidatorContext`` context for the validation. public func validate(using client: OAuth2Client, with context: IDTokenValidatorContext?) throws { guard let idToken = idToken else { return diff --git a/Sources/AuthFoundation/User Management/Credential.swift b/Sources/AuthFoundation/User Management/Credential.swift index 05aa18466..b473939be 100644 --- a/Sources/AuthFoundation/User Management/Credential.swift +++ b/Sources/AuthFoundation/User Management/Credential.swift @@ -128,7 +128,7 @@ public final class Credential: Equatable, OAuth2ClientDelegate { /// Updates the metadata associated with this credential. /// /// This is used internally by the ``tags`` setter, except the use of this function allows you to catch errors. - /// - Parameter metadata: Metadata to set. + /// - Parameter tags: Tags to set. public func setTags(_ tags: [String: String]) throws { guard let coordinator = coordinator else { throw CredentialError.missingCoordinator @@ -196,7 +196,9 @@ public final class Credential: Equatable, OAuth2ClientDelegate { } /// Attempt to refresh the token if it either has expired, or is about to expire. - /// - Parameter completion: Completion block invoked to indicate the status of the token, if the refresh was successful or if an error occurred. + /// - Parameters: + /// - graceInterval: Grace period time interval to permit. + /// - completion: Completion block invoked to indicate the status of the token, if the refresh was successful or if an error occurred public func refreshIfNeeded(graceInterval: TimeInterval = Credential.refreshGraceInterval, completion: @escaping (Result) -> Void) { @@ -249,7 +251,9 @@ public final class Credential: Equatable, OAuth2ClientDelegate { } /// Introspect the token to check it for validity, and read the additional information associated with it. - /// - Parameter completion: Completion block invoked when a result is returned. + /// - Parameters: + /// - type: Token type to introspect. + /// - completion: Completion block invoked when a result is returned. public func introspect(_ type: Token.Kind, completion: @escaping (Result) -> Void) { oauth2.introspect(token: token, type: type) { result in completion(result) diff --git a/Sources/OktaDirectAuth/DirectAuthFlow.swift b/Sources/OktaDirectAuth/DirectAuthFlow.swift index 312064d62..a8aab0cd5 100644 --- a/Sources/OktaDirectAuth/DirectAuthFlow.swift +++ b/Sources/OktaDirectAuth/DirectAuthFlow.swift @@ -19,7 +19,7 @@ import AuthFoundation public protocol DirectAuthenticationFlowDelegate: AuthenticationDelegate { /// Sent when an authentication session receives a new status response. /// - /// This function is invoked when a new status is returned either from ``DirectAuthenticationFlow/start(_:with:)`` or ``DirectAuthenticationFlow/resume(_:with:)`` (or their block-based counterparts). + /// This function is invoked when a new status is returned either from ``DirectAuthenticationFlow/start(_:with:)``, ``DirectAuthenticationFlow/resume(_:with:)-5nv5h``, or ``DirectAuthenticationFlow/resume(_:with:)-9i2pz`` (or their block-based counterparts). func authentication(flow: Flow, received status: DirectAuthenticationFlow.Status) } @@ -101,7 +101,7 @@ public class DirectAuthenticationFlow: AuthenticationFlow { /// Enumeration defining the list of possible secondary authentication factors. /// - /// These values are used by ``DirectAuthenticationFlow/resume(_:with:)``. + /// These values are used by ``DirectAuthenticationFlow/resume(_:with:)-5nv5h``. public enum SecondaryFactor: Equatable { /// Authenticate the user with the given OTP code. /// @@ -200,7 +200,7 @@ public class DirectAuthenticationFlow: AuthenticationFlow { /// The current status of the authentication flow. /// - /// This value is returned from ``DirectAuthenticationFlow/start(_:with:)`` and ``DirectAuthenticationFlow/resume(_:with:)`` to indicate the result of an individual authentication step. This can be used to drive your application's sign-in workflow. + /// This value is returned from ``DirectAuthenticationFlow/start(_:with:)`` and `resume(_:with:)` (both ``DirectAuthenticationFlow/resume(_:with:)-5nv5h`` and ``DirectAuthenticationFlow/resume(_:with:)-9i2pz``) to indicate the result of an individual authentication step. This can be used to drive your application's sign-in workflow. public enum Status: Equatable { /// Authentication was successful, returning the given token. case success(_ token: Token) @@ -212,7 +212,7 @@ public class DirectAuthenticationFlow: AuthenticationFlow { /// Indicates the user should be challenged with some other secondary factor. /// - /// When this status is returned, the developer should use the ``DirectAuthenticationFlow/resume(_:with:)`` function to supply a secondary factor to verify the user. + /// When this status is returned, the developer should use the ``DirectAuthenticationFlow/resume(_:with:)-5nv5h`` function to supply a secondary factor to verify the user. case mfaRequired(_ context: MFAContext) } @@ -270,7 +270,7 @@ public class DirectAuthenticationFlow: AuthenticationFlow { /// - issuer: The issuer URL. /// - clientId: The client ID /// - scopes: The scopes to request - /// - supportedGrants: The list of grants this application supports. Defaults to the full list of values supported by this SDK. + /// - grantTypes: The list of grants this application supports. Defaults to the full list of values supported by this SDK. public convenience init(issuer: URL, clientId: String, scopes: String, @@ -284,7 +284,7 @@ public class DirectAuthenticationFlow: AuthenticationFlow { /// Initializer to construct an authentication flow from a pre-defined configuration and client. /// - Parameters: - /// - configuration: The configuration to use for this authentication flow. + /// - grantTypes: The list of grants this application supports. Defaults to the full list of values supported by this SDK. /// - client: The `OAuth2Client` to use with this flow. public init(supportedGrants grantTypes: [GrantType] = .directAuth, client: OAuth2Client) diff --git a/Sources/OktaDirectAuth/OktaDirectAuth.docc/Extensions/DirectAuthenticationFlow.md b/Sources/OktaDirectAuth/OktaDirectAuth.docc/Extensions/DirectAuthenticationFlow.md index 2c9665335..13ac25a66 100644 --- a/Sources/OktaDirectAuth/OktaDirectAuth.docc/Extensions/DirectAuthenticationFlow.md +++ b/Sources/OktaDirectAuth/OktaDirectAuth.docc/Extensions/DirectAuthenticationFlow.md @@ -1,9 +1,5 @@ # ``OktaDirectAuth/DirectAuthenticationFlow`` -@Metadata { - @DocumentationExtension(mergeBehavior: append) -} - ## Usage You can create an instance of ``DirectAuthenticationFlow`` with your client settings, or you can use one of several convenience initializers to simplify the process. @@ -39,7 +35,7 @@ case .mfaRequired(_): Authentication factors are separated into two groups: * ``PrimaryFactor`` -- Used for initial authentication when calling ``start(_:with:)`` (or ``start(_:with:completion:)`` when using blocks) -* ``SecondaryFactor`` -- Used for supplying additional MFA factors, with the ``resume(_:with:)`` function (or ``resume(_:with:completion:)`` when using blocks) +* ``SecondaryFactor`` -- Used for supplying additional MFA factors, with the ``resume(_:with:)-5nv5h`` or ``resume(_:with:)-9i2pz`` functions (or ``resume(_:with:completion:)-7fbah`` / ``resume(_:with:completion:)-5nj0x`` when using blocks) Each of the fuctions using these factors returns an instance of ``Status``, which indicates whether or not authentication is successful, or if multiple factors are required. @@ -63,8 +59,10 @@ Each of the fuctions using these factors returns an instance of ``Status``, whic ### Continuing sign in with MFA -- ``DirectAuthenticationFlow/resume(_:with:)`` -- ``DirectAuthenticationFlow/resume(_:with:completion:)`` +- ``DirectAuthenticationFlow/resume(_:with:)-5nv5h`` +- ``DirectAuthenticationFlow/resume(_:with:)-9i2pz`` +- ``DirectAuthenticationFlow/resume(_:with:completion:)-7fbah`` +- ``DirectAuthenticationFlow/resume(_:with:completion:)-5nj0x`` - ``DirectAuthenticationFlow/SecondaryFactor`` - ``DirectAuthenticationFlow/OOBChannel`` diff --git a/Sources/OktaDirectAuth/WebAuthn/WebAuthn.swift b/Sources/OktaDirectAuth/WebAuthn/WebAuthn.swift index bad37091b..ba6ae05fb 100644 --- a/Sources/OktaDirectAuth/WebAuthn/WebAuthn.swift +++ b/Sources/OktaDirectAuth/WebAuthn/WebAuthn.swift @@ -59,7 +59,7 @@ public struct WebAuthn { /// Defines the set of data expected from the client in response to an authenticator challenge. /// - /// This value should be supplied to the ``DirectAuthenticationFlow/SecondaryFactor/webAuthnAssertion`` type. + /// This value should be supplied to the ``DirectAuthenticationFlow/ContinuationFactor/webAuthn(response:)`` type. public struct AuthenticatorAssertionResponse: Codable, Equatable { /// The client data JSON response, represented as a string. public let clientDataJSON: String @@ -72,6 +72,13 @@ public struct WebAuthn { /// The optional user handle to supply to the server, typically if the resident key is enabled. public let userHandle: String? + + public init(clientDataJSON: String, authenticatorData: String, signature: String, userHandle: String? = nil) { + self.clientDataJSON = clientDataJSON + self.authenticatorData = authenticatorData + self.signature = signature + self.userHandle = userHandle + } } }