Single Sign-On

Implement SSO for the OpenWeb React Native SDK

OpenWeb's React Native SDK supports single sign-on (SSO) for streamlined authentication across services. SSO offers the following benefits to users:

  • Simplify access with a single login
  • Enhance security by reducing password fatigue
  • Improve user experience with less login friction
  • Integrate with existing systems


Implement SSO

OpenWeb offers both standard and third-party SSO implementations. To learn which implementation is best for you, contact your OpenWeb PSM.

Standard SSO

Follow these steps to implement OpenWeb’s standard SSO with the React Native SDK:

  1. Authenticate the user with your backend user management system.

    const onStartLoginFlow = (event) => {
        ...
    }
    const subscription = SpotIMEventEmitter.addListener('startLoginFlow', onStartLoginFlow);
    
  2. Call the startSSO function and retrieve codeA (session ID).

    SpotIMAPI.startSSO()
        .then(response => {
            console.log(response);
        })
        .catch(error => {
            console.error(error);
        })
    
  3. Make a GET /sso/v1/register-user call to OpenWeb.
    The API call must include the following parameters:

    • Secret access token (access_token)

    • Session ID generated after initiating the SSO session (codeA)

    • Required user details from the backend user management system (primary_key, user_name)

      📘

      Learn more about user registration parameters here.

    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 the completeSSO function with codeB.

    💡

    In the callback, we recommend checking the success and error properties to ensure correct function.

    SpotIMAPI.completeSSO("<CODE_B>")
        .then(response => {
            console.log(response);
        })
        .catch(error => {
            console.error(error);
        })
    

Third-party SSO

Follow these steps to implement a third-party SSO service with the React Native SDK:

  1. Authenticate the user with your third-party user management vendor.
  2. Call the sso(JWTSecret) function with the user JWT secret.

    📘

    If no error occurs in the callback and response?.success is true, the authentication process has finished successfully.

    SpotIMAPI.sso("<SECRET_JWT>")
        .then(response => {
            console.log(response);
          })
        .catch(error => {
            console.error(error);
          })
    


Renew SSO

Renewing SSO ensures uninterrupted user connectivity. SSO renewal is triggered when the existing authenticator for a connected user becomes invalid. SSO renewal silently re-establishes the user's connection without requiring any direct action.

Follow this step to renew SSO:

  1. Listen for the renewSSOAuthentication event.

    const onRenewSSOAuthentication = (e) => {
        // Follow the SSO authentication steps.
    		const userId = e.userId
    		console.log("Renew SSO for user", userId)
    }
    const subscription = SpotIMEventEmitter.addListener('renewSSOAuthentication', onRenewSSOAuthentication);