SAMLAuthenticator

public class SAMLAuthenticator : SAMLAuthentication

SAMLAuthenticator

The SAMLAuthenticator provides SAML-enabled registration.

Note: It is rare for a developer to access the SAMLAuthenticator directly — you typically use the SAMLObserver.

SAML is based on session cookies, the SAMLAuthenticator uses a seperate web view to present a login page. The SAML in the SAP CP SDK for iOS supports WKWebView for authentication.

Default web view presenter is provided by the SDK: WKWebViewPresenter. Custom web view presenter implementation is also possible with the use of WKWebViewPresenting protocol.

Important: WKWebView based SAML only works with SAPHTTPCookieStorage! Make sure you have your SAPURLSession instance configured with the right HTTP cookie store!

Links

• SAML 2.0 specification
  
• The overall SAML 2.0 authentication flow across client and server is described here: SAML 2.0 at SAP.

Setting up a SAMLAuthenticator

Using SAPcpms

1. Create or obtain the SAPcpmsSettingsParameters.
2. Create SAMLAuthenticator with the settings parameters.
3. (recommended) If you want to use the authenticator automatically on requests, then create a SAMLObserver instance with the authenticator and register it to the SAPURLSession using the SAPURLSession‘s func register(_ observer: SAPURLSessionObserving ) method.

This sample code demonstrates how to set up the authenticator for custom usage:

let settingsParameters = SAPcpmsSettingsParameters( ... )
let authenticator = SAMLAuthenticator(settingsParameters: settingsParameters, webViewPresenter: WKWebViewPresenter())

Using advanced

1. Create the SAMLAuthenticationParameters with the required configuration.
2. Create SAMLAuthenticator with the authentication parameters.
3. (recommended) If you want to use the authenticator automatically on requests, then create a SAMLObserver instance with the authenticator and register it to the SAPURLSession using the SAPURLSession’s func register(_ observer: SAPURLSessionObserving ) method.

This sample code demonstrates how to set up the authenticator for custom usage:

let authenticationParameters = SAMLAuthenticationParameters(authorizationEndpointURL: <#your authorizationEndpointURL#>, finishEndpointURL: <#your finishEndpointURL#>)
let authenticator = SAMLAuthenticator(authenticationParameters: authenticationParameters, webViewPresenter: WKWebViewPresenter())

// recommended step (3.)
let observer = SAMLObserver(authenticator: authenticator)

// obtain urlSession
urlSession.register(observer)

Authorization endpoint URL

The authorizationEndpointURL is the URL which will be loaded in the web view. The required behaviour for this URL is to load the login page where the user can enter his / her credentials.

Finish endpoint URL

The finishEndpointURL is the URL which (when encountered in the web view) signals the end of the successful authentication flow. This means that the mechanism implemented on the authorizationEndpointURL has to make a redirect to the finishEndpointURL upon successful authentication. When encountered with this URL in the web view, the web view will disappear and the authenticate method’s completionHandler will be called.

Usage

Starting the authentication flow

Calling the SAMLAuthenticator’s func authenticate(session:completionHandler:) method authenticates the user at the given server. If there is an error during the process it is received in the completionHandler. If there is no error (the error property is nil) then the authentication was successful.

The authenticator will put up a web view (using the default or custom-set web view presenter) on top of the view hierarchy to show the login page. This happens on the main queue.

authenticator.authenticate(session: session) { error in
    if let error = error {
        // If there was an error during the authentication process (web view presentation, or network related), it can be handled here.
        return
    }
    // If there was no error (error is `nil`) then the authentication was successful and the following requests to this endpoint should not encounter SAML challenges.
}

Note:

• The first parameter must be an instance of SAPURLSession. The authentication process will put the acquired credentials (cookies) into this session’s cookie store.
• There could be only one ongoing authentication process. This is guarded internally by the SAMLAuthenticator. Simultaneous calls to the authenticate method will result in a SAMLError.authenticationInProgress error which is received in the completionHandler.

Cancelling an ongoing authentication

You can cancel an ongoing authentication flow. The ongoing authentication will receive a SAMLError.cancelled error through the completionHandler and the web view will disappear. This method does nothing if there was no ongoing authentication.

authenticator.cancel()

Using your own web view presenter implementation

The SAML authentication requires a web view to present the login page. For this the authenticator needs to put a web view on the top of the current view hierarchy. The authenticator uses the WKWebViewPresenting protocol to achieve this which is implemented by default (WKWebViewPresenter).

If there is a custom requirement for presenting and designing a web view then you can use your own implementation of WKWebViewPresenting:

class MyWebViewPresenter: WKWebViewPresenting {
    weak var delegate: WebViewPresenterDelegate?
    public func presentWebView(completionHandler: @escaping (WKWebView?, Error?) -> Void) {
        // TODO:
        // - acquire reference to `UIViewController`
        // - present the view controller which contains a `WKWebView`
        // - pass the `WKWebView` instance to the completionHandler
        // - pass an `Error` instance to the completionHandler if there was an error during presentation
    }

    func dismissWebView() {
        // TODO:
        // - acquire reference to presented `UIViewController` (or the presenting view controller)
        // - dismiss the presented view controller
    }
}

let presenter: WKWebViewPresenting = MyWebViewPresenter()
// Use the initializer which accepts custom web view presenters
let authenticator = SAMLAuthenticator(authenticationParameters: <#SAMLAuthenticationParameters#>, webViewPresenter: presenter)

From this point forward, the authenticator uses the newly set presenter to load the web view login page.

WKWebView based SAML only works with SAPHTTPCookieStorage. Make sure you have your SAPURLSession instance configured with it!

All calls to the web view presenter inside the authenticator happen on the main thread. You must call the completionHandler of your web view presenter implementation on the main thread!

Important: Be sure you call the completionHandler with the applicable objects when finished with the presentation.

The SAMLAuthenticator component provides an API to conduct SAML authentication using a web view. Currently only the WKWebView is supported. By default the SAMLAuthenticator will present a default ViewController which contains a web view to perform authentication. This can be replaced by a custom implementation of the WKWebViewPresenting protocol.

## This class is for advanced usage only! The SDK preferred way of implementing SAML authentication is the use of the SAMLObserver. The direct usage or instantiation of this class is required only when:

• the authentication is not against SAPcpms, therefore a custom authorization endpoint and finish endpoint URL is given
• the authentication and network request has to be handled seperatly

Example of instantiating SAMLAuthenticator with custom URLs:

 let samlAuthenticationParameters = SAMLAuthenticationParameters(authorizationEndpointURL: <#your authorizationEndpointURL#>, finishEndpointURL: <#your finishEndpointURL#>)

 let authenticator = SAMLAuthenticator(authenticationParameters: samlAuthenticationParameters)

Example of authenticating with custom SAMLAuthenticator:

 authenticator.authenticate { error in
     if let error = error {
         // If there was an error during the authentication process (web view presentation, or network related), it can be handled here.
         return
     }
     // If there was no error (error is `nil`) then the authentication was successful and the following requests to this endpoint should not encounter SAML challenges.
 }