Authentication
OpenWeb's single sign on (SSO) enables your registered users to participate in members-only conversations without an extra registration. Learn how to implement iOS authentication.
OpenWeb's single sign on (SSO) enables your registered users to participate in members-only conversations without an extra registration. To provide this user experience, your backend user management system must securely inform OpenWeb that a user is actively logged into your site.
SSO Authentication
SSO Handshake Overview
- Initiate an OpenWeb SSO session. The OpenWeb SDK generates an SSO session ID (
codeA). - Send the SSO session ID to your backend user management system.
- Validate that a user is logged into your system. You must ensure that the current user logged into your site will also be the current user in the OpenWeb user session.
- From your backend user management system, make a
GET /sso/v1/register-usercall to OpenWeb's backend. The API call must include the following information:- Your secret access token (
access_token) - Session ID generated after initiating the SSO session (
code_a) - Required user details from your backend user management system (
primary_key,user_name).
OpenWeb's backend logs in the user and returns a success response (codeB).
- Your secret access token (
- Pass
codeBto the OpenWeb SDK. Successfully completing this process results in logging in a user.
Implementation
For the Standard Authentication and Third-party Provider SSO approaches, the OWAuthentication protocol is used.
public protocol OWAuthentication {
func sso(_ flowType: OWSSOFlowType)
func userStatus(completion: @escaping OWUserAuthenticationStatusCompletion)
func userStatus() async throws -> OWUserAuthenticationStatus
func logout(completion: @escaping OWDefaultCompletion)
func logout() async throws
var renewSSO: OWRenewSSOCallback? { get set }
var shouldDisplayLoginPrompt: Bool { get set }
}Standard Authentication
Use the following recipe to implement SSO authentication for known users.
If the user is already known and has saved persistence on the publisher's end, the user can be automatically logged into the publisher system and then logged in through theOWAuthenticationSSO methods.
Third-party Provider SSO
Use the following recipe to implement third-party provider SSO.
In some scenarios, you may need to trigger a login interface before a user can perform an action, such as posting or replying to a comment.
In these scenarios, the OWUIAuthentication protocol is used.
public protocol OWUIAuthentication {
var displayAuthenticationFlow: OWAuthenticationFlowCallback? { get set }
}Actions Requiring Login
Authentication must be completed in the following way:
- The app displays the iOS SDK UI.
- The unauthenticated user attempts to perform an action that requires login, such as posting, liking, or disliking a comment.
- A closure
displayAuthenticationFlowClosureunderOWUIAuthenticationis triggered to present a login UI. - The user logs in using the app credentials.
- The backend for the app logs in the user.
- The app initiates the steps described above at
OWAuthenticationprotocol for SSO authentication. - Upon successful SSO authentication, the the app closes the login UI which was shown by
displayAuthenticationFlowClosuretriggering .
Use combination of the following code AND recipe to implement this authentication scenario.
let manager: OWManagerProtocol = OpenWeb.manager
let authenticationUI: OWUIAuthentication = manager.ui.authenticationUI
let displayAuthenticationFlowClosure: OWAuthenticationFlowCallback = { routeringMode, completion in
// Implement your custom login flow or use a popup for standalone components.
// After a successful login, initiate and complete the SSO flow.
// In flow mode, adjust the UI, such as popping up or dismissing the login view from `navController`.
// Call `completion()` after your UI adjustments. Since the SDK progresses to the next screen once `completion()`
// is called, call `completion()` only after fully dismissing the UI or adding a 250ms delay.
completion()
// Login prompt other items inside the SDK will be auto-handled and dismissed.
}
authenticationUI.displayAuthenticationFlow = displayAuthenticationFlowClosureRenew SSO
Regardless of the SSO approach used, you must implement
OWRenewSSOCallback.
Renewing SSO ensures uninterrupted user connectivity. It is triggered when the existing authenticator for a previously connected user becomes invalid. This process silently re-establishes the user's connection without requiring any direct action.
// Renew SSO
let renewSSOClosure: OWRenewSSOCallback = { userId, completion in
// Follow the SSO authentication steps.
// Remember to invoke `completion()` after the renewal process.
completion()
}
authentication.renewSSO = renewSSOClosureLogout
// Logout
let logoutCompletionClosure: OWDefaultCompletion = { result in
switch result {
case .success(_):
// All good
case .failure(let error):
// Handle the error / Show appropriate user UI
break
}
}
authentication.logout(completion: logoutCompletionClosure)do {
try await authentication.logout()
} catch {
// Handle the error / Show appropriate user UI
}
User Status
// User status
let userStatusCompletionClosure: OWUserAuthenticationStatusCompletion = {
switch result {
case .success(let status):
switch status {
case .guest:
// Handle guest status
break
case .ssoLoggedIn(let userId):
// Handle logged in status
break
}
case .failure(let error):
// Handle the error / Show appropriate user UI
break
}
}
authentication.userStatus(completion: userStatusCompletionClosure)// User status
do {
switch try await authentication.userStatus() {
case .guest:
// Handle guest status
break
case .ssoLoggedIn(let userId):
// Handle logged in status
break
}
} catch {
// Handle the error / Show appropriate user UI
}Start or Complete SSO Process
authentication.sso(OWSSOFlowType)| Argument | Description |
|---|---|
| OWSSOFlowType OWSSOFlowType | Defines the start or completion of the SSO authentication process See: OWSSOFlowType |
Enumerations, Structs and Type Aliases
OWAuthenticationFlowCallback
typealias OWAuthenticationFlowCallback = (
OWRouteringMode,
completion: @escaping OWBasicCompletion
) -> Void| Property | Description |
|---|---|
| completion OWBasicCompletion | Termination of the callback See: OWBasicCompletion |
| OWRouteringMode OWRouteringMode | Determines the UI navigation strategy See: OWRouteringMode |
OWBasicCompletion
Termination of the callback
typealias OWBasicCompletion = () -> VoidOWDefaultCompletion
Empty completion that returns an error if one occurs
typealias OWDefaultCompletion = (Result<Void, OWError>) -> VoidOWProviderSSOHandler
public typealias OWProviderSSOHandler = (Result<OWSSOProviderModel, OWError>) -> Void| Property | Description |
|---|---|
| OWSSOProviderModel OWSSOProviderModel | Struct containing the third-party user ID. The user ID enables the user to be logged into OpenWeb. |
OWRenewSSOCallback
typealias OWRenewSSOCallback = (
userId: String,
completion: @escaping OWBasicCompletion
) -> Void| Property | Description |
|---|---|
| completion OWBasicCompletion | Termination of the callback. See: OWBasicCompletion |
| userId String | OpenWeb-provided user ID |
OWRouteringMode
| Property | Description |
|---|---|
| OWRouteringMode OWRouteringMode | UI navigation strategy. Possible Values: .flow(navigationController: UINavigationController) for flow implementation, .none for view implementation |
OWSSOCompletionHandler
typealias OWSSOCompletionHandler = (Result<OWSSOCompletionModel, OWError>) -> Void| Property | Description |
|---|---|
| OWSSOCompletionModel OWSSOCompletionModel | Struct containing the user ID. The user ID enables the user to be logged into OpenWeb. |
OWSSOFlowType
authentication.sso(OWSSOFlowType)| Property | Description |
|---|---|
| OWSSOFlowType OWSSOFlowType | Single sign on flow. Possible Values: .start(completion: OWSSOStartHandler), .complete(codeB: String, completion: OWSSOCompletionHandler), .usingProvider(provider: OWSSOProvider, token: String, completion: OWProviderSSOHandler) |
OWSSOProvider
| Property | Description |
|---|---|
| OWSSOProvider String | Third-party identity management providers for single sign on. Possible Values: .auth0, .foxid, .gigya, .hearst, .janrain, .piano |
OWSSOStartHandler
typealias OWSSOStartHandler = (Result<OWSSOStartModel, OWError>) -> Void| Property | Description |
|---|---|
| OWSSOStartModel OWSSOStartModel | Struct containing codeA. The codeA string value is the OpenWeb SSO session ID. |
OWUserAuthenticationStatus
| Property | Description |
|---|---|
| OWUserAuthenticationStatus OWUserAuthenticationStatus | Access status of the user. Possible Values: .guest, .ssoLoggedIn(userId: String) |
OWUserAuthenticationStatusCompletion
typealias OWUserAuthenticationStatusCompletion = (Result<OWUserAuthenticationStatus, OWError>) -> Void| Property | Description |
|---|---|
| OWUserAuthenticationStatus OWUserAuthenticationStatus | Access status of the user. See: OWUserAuthenticationStatus |
Updated 8 days ago
