UserIdentityObserver

open class UserIdentityObserver

extension UserIdentityObserver: SAPURLSessionObserving

User Identity Observer

The UserIdentityObserver is a SAPURLSessionObserver that can be used to automatically handle cases where communication requires a User Identity certificate. The component listens on the didReceive challenge SAPURLSession delegate method. The UserIdentityObserver uses two delegates:

• UserIdentityStoring– manages identity storage
• UserIdentityObtaining– manages identity creation

You can implement the UserIdentityStoring to manage the identity storage. Usually this is performed in the application itself:

1. The observer calls the delegate to store, retrieve and delete the identity.
2. The implementer stores the identity in a secure way.
3. The URL can be used to distinguish identities if the application uses more resource servers using, for example, the host from the URL as a key.

func store(identity: Data, for: URL) -> Void {
    // save the identity to a secure storage
}

func identity(for: URL) -> Data? {
    // return the identity from the secure storage
}

func delete(for: URL) -> Void {
    // delete the identity from the secure storage
}

When an authentication challenge occurs, UserIdentityObserver first calls the UserIdentityStoring delegate to retrieve the identity. If this step fails it calls the UserIdentityObtaining delegate to create a new identity.

When the store delegate provides an identity but the request results in an authentication challenge, the observer calls the delete(for:) method on the store to delete the identity, and then again calls the obtaining delegate to create a new identity.

The observer automatically handles multiple requests and calls obtainIdentity only once. All other running requests handle the result of the first request.

If an authentication challenge occurs, despite the creation of a new identity that is passed in response to the challenge, the UserIdentityObserver does not attempt to obtain a new identity again but cancels the request and it fails. All other tasks waiting for the end of authentication fail as well. However, if a new request is started, the UserIdentityObserver attempts to obtain a new identity in the event of another authentication challenge.

Usage

Initialization and registration

Initialize a UserIdentityObserver with Discovery Service

let userIdentityObserver = UserIdentityObserver(userIdentityDiscovery: <#userIdentityDiscovery instance#>, identityStore: <#Identity Store instance#>)
sapURLSessionForResource.register(userIdentityObserver)

SAPFoundation currently supports two types of user identity discovery:

• [SAPcpmsUserIdentityDiscovery]()
• [SLSUserIdentityDiscovery]()

See the referenced components for more detail about the initialization and usage.

Start request to Resource URL

let request = URLRequest(url: <#resourceURL#>)
let dataTask = sapURLSessionForResource.dataTask(with: request) { data, response, error in
    // Handle the error and the response
}
dataTask.resume()

Listens to authentication challenges using the SAPURLSessionObserving didReceive challenge method. In case an Identity needed the observer calls its IdentityStore to get the Identity. In case there is no certificate the Task will be called by resend which stop the current request and restarts it. During the initialization of the request the UserIdentityObtaining is called to obtain a new Identity.