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
- Create or obtain the
SAPcpmsSettingsParameters
. - Create
SAMLAuthenticator
with the settings parameters. - (recommended) If you want to use the authenticator automatically on requests, then create a
SAMLObserver
instance with the authenticator and register it to theSAPURLSession
using theSAPURLSession
‘sfunc 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
- Create the
SAMLAuthenticationParameters
with the required configuration. - Create
SAMLAuthenticator
with the authentication parameters. - (recommended) If you want to use the authenticator automatically on requests, then create a
SAMLObserver
instance with the authenticator and register it to theSAPURLSession
using theSAPURLSession
’sfunc 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 yourSAPURLSession
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.
}
-
Creates a SAMLAuthenticator instance.
Declaration
Swift
public init(authenticationParameters: SAMLAuthenticationParameters, webViewPresenter: WKWebViewPresenting)
Parameters
authenticationParameters
The necessary parameters to authenticate. Parameters contain server related information, see
SAMLAuthenticationParameters
.webViewPresenter
The
WKWebViewPresenting
instance to be used for presenting the login page. -
Creates an SAMLAuthenticator instance based on the SAPcpms settings parameters.
Declaration
Swift
public convenience init(settingsParameters: SAPcpmsSettingsParameters, webViewPresenter: WKWebViewPresenting)
Parameters
settingsParameters
The
SAPcpmsSettingsParameters
instance required to create the authentication parameters for the SAML authenticator. The required parameter is thebackendURL
.webViewPresenter
The
WKWebViewPresenting
instance to be used for presenting the login page.
-
Starts the SAML authentication process. This method will present a web view on the main thread.
Declaration
Swift
public func authenticate(session: SAPURLSession, completionHandler: @escaping (_ error: Error?) -> Void = SAMLAuthenticator.defaultCompletionHandler)
Parameters
completionHandler
The completion handler that gets invoked at the end of the authentication process. The default handler will log the error if there was any.
error
The
Error
happened during the process if there was any, otherwisenil
. SeeSAMLError
for the list of possible SAML related errors. -
Starts the SAML authentication process. This method will present a web view on the main thread.
Declaration
Swift
public func authenticate(cookies: [HTTPCookie], completionHandler: @escaping (_ credentials: [HTTPCookie]?, _ error: Error?) -> Void)
Parameters
cookies
The initial cookies required to do a SAML authentication - comes from the session’s cookie storage.
completionHandler
The completion handler that gets invoked at the end of the authentication process.
credentials
The acquired cookie credentials - comes from the web view. It is
nil
if there was an error.error
The
Error
happened during the process if there was any, otherwisenil
. SeeSAMLError
for the list of possible SAML related errors. -
Cancels the ongoing authentication process. The authenticate method’s
completionHandler
will be invoked withSAMLError.cancelled
error. Does nothing if there was no ongoing authentication.Declaration
Swift
public func cancelAuthentication()
-
The default completion handler for authentication. Logs the error with the root logger if there is any.
Declaration
Swift
public static func defaultCompletionHandler(error: Error?)
Parameters
error
The error happened during authentication.