Classes

AuthService represents Authentication Tree in OpenAM to initiate authentication flow with OpenAM. Initiating AuthService returns one of following:

• Result of expected type, if available
• A Node object instance to continue on the authentication flow
• An error, if occurred during the authentication flow

Notes

* Any Callback type returned from AM must be supported within CallbackFactory.shared.supportedCallbacks.
* Any custom Callback must be implemented by inheriting Callback class, and be registered through CallbackFactory.shared.registerCallback(callbackType:callbackClass:).

Node class is the core abstraction within an authentication tree. Trees are made up of nodes, which may modify the shared state and/or request input from the user via Callbacks. Node is also a representation of each step in the authentication flow, and keeps unique identifier and its state of the authentication flow. Node must be submitted to OpenAM to proceed or finish the authentication flow. Submitting the Node object returns one of following:

• Result of expected type, if available
• Another Node object instance to continue on the authentication flow
• An error, if occurred during the authentication flow

PolicyAdvice is a representation of Authorization Policy advice response from AM’s policy engine

PolicyAdviceCreator helps create a Authorization PolicyAdvice based on different response types (xml, base64XML, json) that receive from AM’s policy engine

Callback that accepts user input often need to validate that input either on the client side, the server side or both. Such callback should extend this base class.

FailedPolicy that describes reason, and additional information for user input validation failure

Base implementation of a Callback for collection of a single identity object attribute from a user.

BooleanAttributeInputCallback is a representation of OpenAM’s BooleanAttributeInputCallback to collect single boolean value with OpenAM validation and given policies.

Callback class is base class, and is a representation of Callback implementation that OpenAM presents as par to of authentication flow. All Callback class must inherit from this class, and implement its own logic to handle interaction(s) with OpenAM.

Important Note

All inherited Callback class must implement and override following method as Callback is just a base class implementation due to Objective-C compatibility:

• init method that parses raw JSON response, and assign any value accordingly to its properties
• buildResponse() method that prepares, and builds request JSON payload for this specific Callback

CallbackFactory is a representation of class responsible for managing and maintaining supported OpenAM callback in FRAuth SDK.

Notes

* Any Callback type returned from OpenAM **must** be supported within CallbackFactory.shared.supportedCallbacks.
* Any custom Callback must be implemented custom Callback class, and be registered through CallbackFactory.shared.registerCallback(callbackType:callbackClass:).
* FRAuth SDK currently supports following Callback types:
    1. NameCallback
    2. PasswordCallback
    3. ChoiceCallback
    4. ValidatedCreateUsernameCallback
    5. ValidatedCreatePasswordCallback
    6. StringAttributeInputCallback
    7. TermsAndConditionsCallback
    8. KbaCreateCallback
    9. PollingWaitCallback
    10. ConfirmationCallback
    11. TextOutputCallback
    12. ReCaptchaCallback
    13. MetadataCallback
    14. DeviceProfileCallback
    15. BooleanAttributeInputCallback
    16. NumberAttributeInputCallback
    17. SuspendedTextOutputCallback
    18. WebAuthnRegistrationCallback
    19. WebAuthnAuthenticationCallback
    20. IdPCallback
    21. SelectIdPCallback
    22. FRAppIntegrityCallback
    23. TextInputCallback

ChoiceCallback is a representation of OpenAM’s ChoiceCallback to collect single user input from available choices, and with predefined default choice, and to retrieve selected choice from user interaction.

ConfirmationCallback is a representation of ConfirmationCallback in OpenAM to ask user for YES/NO, OK/CANCEL, YES/NO/CANCEL or other similar confirmations.

DeviceProfileCallback is a callback class that collects Device Information using DeviceCollector(s) in FRAuth SDK.

IdPCallback is a representation of Social Provider Handler Node in AM when Client Type option specified as NATIVE (only available in AM 7.1 and above)

KbaCreateCallback is a representation of OpenAM’s KbaCreateCallback which is responsible to define, and create Knowledge Based Authentication question and answer for a user.

MultipleValuesCallback is a base Callback implementation that has one or more user input values. Any Callback that accepts multiple values from user interaction without OpenAM’s validation with policies may inherit from this class.

NameCallback is a representation of OpenAM’s NameCallback to collect single user input; NameCallback is typically used to collect Username for the authentication flow.

NumberAttributeInputCallback is a representation of OpenAM’s NumberAttributeInputCallback to collect double value with OpenAM validation and given policies.

PasswordCallback is a representation of OpenAM’s PasswordCallback to collect single user input; PasswordCallback is typically used to collect user or OTP credentials for the authentication flow.

PollingWaitCallback is a representation of a PollingWaitCallback Callback Object in OpenAM which instructs an application to wait for the given period and resubmit the request.

Parent Callback used by Ping One Protect callbacks

ReCaptchaCallback is a representation of ReCaptchaCallback Callback in OpenAM which provides ReCaptcha credentials to process ReCaptcha in native application.

SelectIdPCallback is a representation of AM’s Select Identity Provider Node to select a specific Identity Provider from given options (local authentication, or list of social login providers)

SingleValueCallback is a base Callback implementation that has single user input value. Any Callback that accepts single value from user interaction without OpenAM’s validation with policies may inherit from this class.

StringAttributeInputCallback is a representation of OpenAM’s StringAttributeInputCallback to collect single value of string user attribute with OpenAM validation with given policies.

SuspendedTextOutputCallback is a representation of AM’s SuspendedTextOutputCallback to notify user that the authentication flow is suspended and can be resumed with Resume URI sent to user’s email.

TermsAndConditionsCallback is a callback to collect a user’s acceptance of the configured Terms & Conditions.

TextInputCallback is a representation of OpenAM’s TextInputCallback to collect single user input; It is typically used to collect any text input for the authentication flow.

TextOutputCallback is a representation of TextOutputCallback Callback in OpenAM which provides a message to be displayed to a user with given message type.

ValidatedCreatePasswordCallback is a representation of OpenAM’s ValidatedCreatePasswordCallback to collect single value of Password with OpenAM validation with given policies.

ValidatedCreateUsernameCallback is a representation of OpenAM’s ValidatedCreateUsernameCallback to collect single value of Username with OpenAM validation with given policies.

WebAuthnAuthenticationCallback is a representation of AM’s WebAuthn Authentication Node to generate WebAuthn assertion based on given credentials, and optionally set the WebAuthn outcome value in Node‘s designated HiddenValueCallback

WebAuthnCallback represents AM’s WebAuthn MetadataCallback, and is a parent class of WebAuthnRegistrationCallback and WebAuthnAuthenticationCallback

WebAuthnRegistrationCallback is a representation of AM’s WebAuthn Registration Node to generate WebAuthn attestation based on given credentials, and optionally set the WebAuthn outcome value in Node‘s designated HiddenValueCallback

FROptions represents a configuration object for the SDK. It can be used for passing configuration options in the FRAuth.start() method.

OAuth2 client object represents OAuth2 client, and provides methods related to OAuth2 protocol

Configuration object represents OpenAM, or FRaaS environment information

BrowserCollector is responsible for collecting browser information of the device.

FRDevice represents a device locally managed, and persisted in FRAuth SDK

FRDeviceCollector class manages, and collects Device related information with given DeviceCollector objects and returns JSON result of all Device Collectors

HardwareCollector is responsible for collecting hardware information of the device using ProcessInfo.

NetworkCollector is responsible for collecting network information of the device using FRAuth.NetworkReachabilityMonitor.

PlatformCollector is responsible for collecting platform information of the device using UIDevice, and system information.

TelephonyCollector is responsible for collecting telephony information of the device using CTCarrier.

FRAuth is an abstraction of authentication and/or registration with OpenAM through FRAuth SDK.

Note

• In order to use abstraction layer of FRAuth SDK, you must initiate SDK using FRAuth.start(). Upon completion of SDK initialization, object models (FRDevice and/or FRUser) become available.
• For SDK initialization, you must have proper configuration file as in .plist; default .plist that FRAuth SDK looks for is ‘FRAuthConfig.plist’, and the config file name can be changed through FRAuth.configPlistFileName property, or create an FROptions object and pass it in the FRAuth.start(options: FROptions? = nil) “options” parameter.

FRLog is a class responsible for Logging functionalities of FRAuth SDK. FRLog can also be used in the application layer which then be displayed through FRAuth SDK, and through OSLog with FRAuth SDK’s system label and LogLevel.

Note

By default, FRLog uses OSLog to display the log entry in the debug console, and in the log system of iOS; however, when OS_ACTIVITY_MODE is disabled in the environment variable, FRLog then uses default system print() method to display the log entry in the console only.

FRRequestInterceptorRegistry is a wrapper of FRCore.RequestInterceptorRegistry and is responsible to maintain, and manage an array of RequestInterceptor for FRCore’s network layer

FRRestclient is FRCore’s RestClient wrapper with additional functionalities for Cookie management

AccessToken class represents access_token data inheriting from Token class

Token class represents any token object type

AuthorizationPolicy is mainly responsible to handle Authorization Policy process in AM. AuthorizationPolicy evaluates responses of each request, try to recognize Authorization Policy process as much as possible, and also delegates to the application layer to determine whether or not the response is Authorization Process or not.

AuthorizationPolicy proceeds following major steps:

   1. Upon receiving request response, or redirected request, it invokes `AuthorizationPolicy.evaluateAuthorizationPolicy` to evaluate whether or not the response is required for Authorization process. If the response is automatically recognizable by SDK (IG redirect, or response payload containing `Advice` json structure, SDK automatically parses the response into `PolicyAdvice`.
   2. If `PolicyAdvice` is found, it invokes `AuthorizationPolicyDelegate.onPolicyAdviseReceived` for the application layer to perform authorization process with given `PolicyAdvice`. The application layer should use `FRSession.authenticate` with `PolicyAdvice` to walk through authentication tree, and notify SDK with `completion` callback with the result of the authorization process.
   3. If the authorization process was successful, it invokes `AuthorizationPolicyDelegate.updateRequest` to decorate the new request with transactionId (if found). If `AuthorizationPolicyDelegate.updateRequest` is not implemented, SDK automatically injects `_txId` in URL query parameter to the original request, and retry the request with updated one. If `transactionId` is not found, then retry with the original request.

Note AuthorizationPolicyDelegate only enforces its policy for given URLs. If given URLRequest does not match any of given URLs, then it proceeds as it is.

Usage

 // Step 1 - Register FRURLProtocol
 URLProtocol.registerClass(FRURLProtocol.self)

 // Step 2 - Initialize AuthorizationPolicy object
 let authorizationPolicy = AuthorizationPolicy(validatingURL: [URL, URL,...], delegate: self)

 // Step 3 - Implement delegate method if needed; `AuthorizationPolicyDelegate.onPolicyAdviseReceived` is mandatory whereas others are optional

 // Step 4 - Assign AuthorizationPolicy in FRURLProtocol
 FRURLProtocol.authorizationPolicy = authorizationPolicy

 // Step 5 - Configure URLProtocol in the application's URLSessionConfiguration
 let config = URLSessionConfiguration.default
 config.protocolClasses = [FRURLProtocol.self]
 let urlSession = URLSession(configuration: config)

TokenManagementPolicy is mainly responsible to determine to inject OAuth2 authorization header in the request, and whether or not response of the request is OAuth2 token validation failure, so that SDK should renew OAuth2 token, and retry request with updated OAuth2 token

TokenManagementPolicy performs two major responsibilities:

    1. Automatically injects `Authorization` header in the request with currently authenticated `FRUser.currentUser.token` value; if no currently authenticated user session is found, then it continues with the original request
    2. Upon receiving request response, it invokes `TokenManagementPolicyDelegate.evaluateTokenRefresh` to evaluate whether or not the response is due to OAuth2 token validation failure (i.e. token expired). The application layer can determine if the response is required to renew OAuth2 token set, and return `true` in the delegation method which then enforce SDK to renew OAuth2 token set with `refresh_token`, and/or `SSOToken`, and retry the original request with updated OAuth2 token set. If OAuth2 token renewal fails, or same response is returned after renewing OAuth2 tokens, SDK terminates the request, and returns the failure response.

**Note** TokenManagementPolicy only enforces its policy for given URLs. If given URLRequest does not match any of given URLs, then it proceeds as it is.

Usage

 // Step 1 - Register FRURLProtocol
 URLProtocol.registerClass(FRURLProtocol.self)

 // Step 2 - Initialize TokenManagementPolicy object
 let tokenManagementPolicy = TokenManagementPolicy(validatingURL: [URL, URL,...], delegate: self)

 // Step 3 - Implement delegate method if needed

 // Step 4 - Assign TokenManagementPolicy in FRURLProtocol
 FRURLProtocol.tokenManagementPolicy = tokenManagementPolicy

 // Step 5 - Configure URLProtocol in the application's URLSessionConfiguration
 let config = URLSessionConfiguration.default
 config.protocolClasses = [FRURLProtocol.self]
 let urlSession = URLSession(configuration: config)

FRSession represents a session authenticated by AM’s Authentication Tree

AppleSignInHandler is responsible to perform authorization/signing-in a user using Apple ID, and AuthenticationServices framework; Sign-in With Apple is only available for iOS 13 and above.

Address class is a representation of a user’s Address data according to OAuth2 and OIDC spec. Address is retrieved using /userinfo endpoint and is part of UserInfo object.

Browser is a representation of external user-agent (using Authentication Service, Native Browser Application, or SFSafariViewController)

BrowserBuilder is a builder class for progressive construction of Browser object.

FRUser represents authenticated user session as FRUser object

UserInfo class is a representation of a user’s UserInfo data according to OAuth2 and OIDC spec. UserInfo is retrieved using /userinfo endpoint.

FRWebAuthn is a utility class providing helper methods for listing and deleting WebAuthn keys stored on the device. The provided static methods are: public static func deleteCredentials(by rpId: String) public static func loadAllCredentials(by rpId: String) -> [PublicKeyCredentialSource] public static func deleteCredential(with publicKeyCredentialSource: PublicKeyCredentialSource) public static func deleteCredential(with publicKeyCredentialSource: PublicKeyCredentialSource, forceDelete: Bool)

FRWebAuthnManager is a class handling WebAuthn Registation and Authentication using Apple’s ASAuthorization libraries. Used by the SDK, it is called by the WebAuthnRegistration and WebAuthnAuthenticaton callbacks and sets the outcome in the HiddenValueCallback. This comes with the FRWebAuthnManagerDelegate that offers callbacks in the calling class for Success, Error and Cancel scenarios.