SAMLObserver
open class SAMLObserver
extension SAMLObserver: SAPURLSessionObserving
SAMLObserver
The use of this component is the SDK-suggested way of implementing SAML authentication in the application.
The SAMLObserver
intercepts requests provided by SAPURLSession
and looks for SAML challenge indicating HTTP responses.
Upon detecting a SAML challenge, it uses its SAMLAuthenticator
to authenticate and resend the original request when the authentication is successful. The caller does not notice anything from the authentication flow.
SAML implementation is based on session cookies, so no additional values/tokens need to be stored. The SAML observer must be on the same url session as the other requests sent to the SAML protected server.
Usage
SDK-suggested usage
The SDK-suggested way of using the SAMLObserver is to use its convenience initializer which takes a SAPcpms settings parameters as parameter. This is most favorable when the authentication happens against SAPcpms.
Example:
// Create the SAPcpms settings parameter.
let settingsParameters: SAPcpmsSettingsParameters = <#Settings parameter#>
// Create the observer with the suitable initializer
let observer = SAMLObserver(settingsParameters: settingsParameters)
// Register the observer to an instance of `SAPURLSession`
sapURLSession.register(observer)
A SAPURLSession is required to register the observer. Be aware that an observer instance can be registered to the same SAPURLSession instance only once! Multiple registration will result in application termination!
Customization
There can be scenarios where the SDK supplied convenience implementation is not sufficient. The SDK supports multiple level of customizations. You can find examples at the Authentication section.
Detecting SAML challenges
SAPcpms signals SAML challenges through HTTP response headers. The default SAML challenge implemented by SAPcpms:
- HTTP response status code 200
- Custom header name “com.sap.cloud.security.login” with value “login-request”
The default SAMLObserver looks for these conditions on every received response to determine if there was a SAML challenge.
Overriding the default challenge detection logic
If your landscape signals SAML challenges differently then you need to customize the challenge detection logic. The SDK supports this kind of customization through the sub-classing of SAMLObserver and the overriding of the dedicated challenge detection method.
class MySAMLObserver: SAMLObserver {
// Override the default challenge detection method
override func isChallenge(dataTask: SAPURLSessionTask, response: URLResponse) -> Bool {
// Determine if the response contains a SAML challenge
// Return a boolean value accordingly.
// return true - the repsonse is a SAML challenge and authentication must take place
// return false - the response is not a SAML challenge, continue normally
}
}
// Create your observer with one of the available initializers
let mySAMLObserver = MySAMLObserver(settingsParameter: <#your SAPcpmsSettingsParameters#>)
// Register the created observer to an instance of the SAPURLSession
sapURLSession.register(mySAMLObserver)
Note - regarding the main thread
The observer is aware of the application state, and does not allow to run UI-required authentication in background state.
It uses the main thread synchronously to read the UIApplication.shared.applicationState
property.
Do not use the main thread to wait (block) for a network request which goes through this observer!
The use of this component is the SDK-suggested way of implementing SAML authentication in the application.
The SAMLObserver
intercepts requests provided by SAPURLSession
and looks for SAML challenge indicating HTTP responses.
Upon detecting a SAML challenge, it uses its SAMLAuthenticator
to authenticate and resend the original request when
the authentication is successful. The caller does not notice anything from the authentication flow.
Example use:
// create or acquire the SAPURLSession instance
let sapURLSession = SAPURLSession()
// perform other steps to initialize the session and the application
// create the SAPcpms settings parameter
let settingsParameters = SAPcpmsSettingsParameters(backendURL: <#your backendURL#>, applicationID: <#your applicationID#>)
// create the SAML observer
let samlObserver = SAMLObserver(settingsParameters: settingsParameters)
// register the observer on the URL session
sapURLSession.register(samlObserver)
// start to create requests
-
Determines the header name which indicates a SAML challenge.
Declaration
Swift
public let challengeHeaderName: String
-
Determines the header value which indicates a SAML challenge.
Declaration
Swift
public let challengeHeaderValue: String
-
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?
-
Instantiates the observer with the given authenticator.
Declaration
Swift
public init(authenticator: SAMLAuthentication, challengeHeaderName: String = SAMLChallengeHeaderName, challengeHeaderValue: String = SAMLChallengeHeaderValue)
Parameters
authenticator
the
SAMLAuthentication
instance to be used when encountered with an authentication challenge -
Instantiates the observer based on the SAML authentication parameters. The SAML authenticator is implicitly created with the default web view presenter.
Declaration
Swift
public convenience init(authenticationParameters: SAMLAuthenticationParameters)
Parameters
authenticationParameters
The necessary parameters to authenticate. Parameters contain server related information.
-
Instantiates the observer based on the SAPcpms settings parameters. The SAML authenticator is implicitly created with the default web view presenter.
Declaration
Swift
public convenience init(settingsParameters: SAPcpmsSettingsParameters)
Parameters
settingsParameters
The
SAPcpmsSettingsParameters
instance required to create the authentication parameters for the SAML authenticator. The required parameter is thebackendURL
. -
External SAML challenge decision logic. The default behaviour checks for authentication headers in the HTTPURLResponse, naming ‘com.sap.cloud.security.login: login-request’. When this header is present, the authentication flow will start, otherwise this observer is skipped. The method can be overriden if custom challenge decision logic is needed. The SAML observer will launch the authentication flow if this method returns
True
.Declaration
Swift
open func isChallenge(dataTask: SAPURLSessionTask, response: URLResponse) -> Bool
Parameters
dataTask
the resumed SAPURLSessionTask
response
the received URLResponse
Return Value
True
is the response indicates a SAML challenge,False
otherwise -
Declaration
Swift
public func sapURLSession(_ session: SAPURLSession, task: SAPURLSessionTask, willSend request: URLRequest, completionHandler: @escaping (SAPURLSession.RequestDisposition) -> Void)
-
Declaration
Swift
public func sapURLSession(_ session: SAPURLSession, dataTask: SAPURLSessionTask, didReceive response: URLResponse, completionHandler: @escaping (SAPURLSession.ResponseDisposition) -> Void)
-
Declaration
Swift
public func sapURLSession(_ session: SAPURLSession, downloadTask: SAPURLSessionTask, didFinishDownloadingTo location: URL, completionHandler: @escaping (SAPURLSession.DidCompleteDisposition) -> Void)
-
Declaration
Swift
public func sapURLSession(_ session: SAPURLSession, task: SAPURLSessionTask, didCompleteWithError error: Error?, completionHandler: @escaping (SAPURLSession.DidCompleteDisposition) -> Void)
-
Declaration
Swift
public func sapURLSession(_ session: SAPURLSession, task: SAPURLSessionTask, didCompleteWithError error: Error?)