Single Sign-on for Android

There are two types of SSO available: Standard and third-party single sign on. Please contact your OpenWeb PSM if you are unsure which implementation method is applicable to you.

Implementation Options

Standard

1. Authenticate a user with your backend user management system.
2. Call startSSO function and get codeA.
   
   
   Kotlin: Using startSSO

   SpotIm.startSSO(object: SpotCallback<StartSSOResponse>() {
       override fun onSuccess(response:StartSSOResponse) {
           val codeA = response.getCodeA()
       }
     
       override fun onFailure(exception:SpotException) { 
           //doSomething...
       }
   })
   

   
   
3. Make a GET /sso/v1/register-user call to OpenWeb. The API call must include your secret access token (access_token), the session ID generated after initiating the SSO session (codeA), and required user details from your backend user management system (primary_key, user_name). Each of these parameters is defined in Add user information.
   
   
   GET /sso/v1/register-user

   GET https://www.spot.im/api/sso/v1/register-user?code_a={CODE_A}&access_token={ACCESS_TOKEN}&primary_key={PRIMARY_KEY}&user_name={USER_NAME}
   

4. Call completeSSO with the codeB.
   
   
   Kotlin: Using completeSSO()

   SpotIm.completeSSO("CODE_B", object: SpotCallback<String>() {
       override fun onSuccess(response: String) {
         	val userId = response
           // You can save the userId in case you support multiple users logged in at the same time in the application side
           // Later on this userId can be checked with `SpotIm.getUserLoginStatus` function
       }
     
       override fun onFailure(exception: SpotException){
           //doSomething... 
       }
   })
   

Third-party single sign on

1. Authenticate a user with your third-party user management vendor.
2. Call ssoWithJwt(JWT) with a user JWT secret.
   
   If there is no error in the callback and response?.success is true, the authentication process finished successfully.
   
   
   Kotlin: SSO with JWT secret example

   SpotIm.ssoWithJwt("JWT_SECRET", object: SpotCallback<SsoWithJwtResponse>() {
       override fun onSuccess(response: SsoWithJwtResponse) { 
           //doSomething... 
       }
          
     	override fun onFailure(exception: SpotException) {
           //doSomething...
       }
   })
   

Supporting signup/login flow

❗

Regardless of the SSO approach used, you must call renewSSOAuthentication().

You can support instantiating a signup/login flow from the OpenWeb SDK UI by providing LoginDelegateto the OpenWeb SDK.

SpotIm.setLoginDelegate(object:LoginDelegate() {
    override fun startLoginUIFlow(activityContext:Context) {
        // Show your login UI flow here.
    }
  
  	override fun renewSSOAuthentication(userId: String) {
        // Renew SSO - Basically silent SSO again to keep the user connected
        // This function will be called once a token is no longer valid and a user was connected from before
        // Follow the above steps to renew the SSO
    }
})

When the startLoginUIFlow delegate method is called, a UI should appear that allows the user to sign up or log in to the app. Upon successful login, the full SSO flow is performed using the OpenWeb SDK API. This process ensures that the user is logged in to the OpenWeb commenting system as well.

When the renewSSOAuthentication delegate function is called, a silent SSO flow is performed. This re-authentication ensures the user remains logged in. This function is called in two primary situations:

• An authentication token has expired.
• An authentication error occurred, and a user was previously logged in.

The userId field tracks which user was previously logged in. This tracking enables multiple logged-in users in the application using the SDK.

Logout

Call the OpenWeb logout API whenever a user logs out of your system.

SpotIm.logout(object: SpotVoidCallback {
    override fun onSuccess() { 
        //doSomething... 
    }
    
  	override fun onFailure(exception: SpotException) {
        //doSomething... 
    }
})

Login status

The OpenWeb login status API enables you to understand the status of the current OpenWeb user.

The status of a current user will be either UserStatus.Guest or UserStatus.SSOLoggedIn(userId: String).

getUserLoginStatus()

Retrieve the login status of the current user.

SpotIm.getUserLoginStatus(object: SpotCallback<UserStatus>() {
    override fun onSuccess(status:UserStatus) {
			// val isLoggedIn = status != UserStatus.Guest
			// Do something... 
    }
  	
  	override fun onFailure(exception: SpotException) {
			// Do something... 
    }
})