UserIdentityObserver

open class UserIdentityObserver

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:

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.

  • when set the observer calls this handler after a new authentication but before the authentication process finishes and all other requests continues

    Declaration

    Swift

    public var authenticationHandler: AuthenticationHandling?
  • Initializes the UserIdentityObserver

    Declaration

    Swift

    public init(userIdentityDiscovery: UserIdentityObtaining, identityStore: UserIdentityStoring)

    Parameters

    userIdentityDiscovery

    component to retrieve a User certificate from Discovery Service

    identityStore

    UserIdentityStoring implementation to store and handle the stored identities. The observer stores the identityStore as a strong reference.

  • Initializes the SAPcpmsUserIdentityDiscoveryObserver in a convenience mode

    Declaration

    Swift

    public convenience init(userIdentityConfigurationParameters: SAPcpmsUserIdentityConfigurationParameters, oAuth2AuthenticationParameters: OAuth2AuthenticationParameters, identityStore: UserIdentityStoring, applicationID: String? = nil)

    Parameters

    userIdentityConfigurationParameters

    SAPcpmsUserIdentityConfigurationParameters instance with parameters to use Discovery Service

    oAuth2AuthenticationParameters

    contains the authentication configuration paramteres

    identityStore

    identity store implementation. This store handles the identity that received from the Discovery Service. The observer stores the identityStore as a strong reference.

    applicationID

    ID of the application that defined in SAP Cloud Platform Mobile Service

  • Initializes the SAPcpmsUserIdentityDiscoveryObserver in a convenience mode

    Declaration

    Swift

    public convenience init?(certificateDiscoveryConfiguration configuration: [String: Any], identityStore: UserIdentityStoring, applicationID: String? = nil)

    Parameters

    certificateDiscoveryConfiguration

    Dictionary that contains userIdentityConfigurationParameters and oAuth2AuthenticationParameters. The oAuth2AuthenticationParameters key should be com.sap.mobilesecure.certificateService.authType under userIdentityConfigurationParameters

    identityStore

    identity store implementation. This store handles the identity that received from the Discovery Service. The observer stores the identityStore as a strong reference.

    applicationID

    ID of the application that defined in SAP Cloud Platform Mobile Service