Authentication and MFA

Machine clients skip this page: they sign in with their client credentials (Getting started → Services and integrations).

Use sdk.auth to sign in and complete authentication challenges. Start with a configured sdk from Getting started. Kotlin examples run in a coroutine; TypeScript examples run in an async function.

Authentication flows

Password login

Password login uses SRP by default. fcmDevice tells Solibo Home which kind of client is signing in, so it knows where push notifications may go: ANDROID or IOS in mobile apps, WEB for browsers, servers and command-line tools.

import no.solibo.oss.sdk.api.gen.models.FcmDeviceType
import no.solibo.oss.sdk.auth.Credentials

val result = sdk.auth.initiateAuth(
    fcmDevice = FcmDeviceType.ANDROID, // Use IOS on iOS
    creds = Credentials(login = "user@example.com", pwd = "your-password")
)

import { Credentials, FcmDeviceType } from '@solibo/solibo-sdk';

const result = await sdk.auth.initiateAuth(
  FcmDeviceType.WEB,
  new Credentials('user@example.com', 'your-password'),
);

Email or SMS code

Request a code, then submit it after the user receives it.

sdk.auth.initiateAuth(
    fcmDevice = FcmDeviceType.ANDROID,
    creds = Credentials(login = "user@example.com"),
    usePassword = false
)

// After the user enters the code:
val result = sdk.auth.loginByCode(
    login = "user@example.com",
    code = "123456",
    fcmDevice = FcmDeviceType.ANDROID
)

import { Credentials, FcmDeviceType } from '@solibo/solibo-sdk';

await sdk.auth.initiateAuth(
  FcmDeviceType.WEB,
  new Credentials('user@example.com'),
  false /* usePassword: send a one-time code instead */,
);

// After the user enters the code:
const result = await sdk.auth.loginByCode(
  'user@example.com',
  '123456',
  FcmDeviceType.WEB,
);

OAuth

Pass the authorization code and state from your configured provider’s callback.

val result = sdk.auth.loginByOAuth(code, state, FcmDeviceType.ANDROID)

import { FcmDeviceType } from '@solibo/solibo-sdk';

const result = await sdk.auth.loginByOAuth(code, state, FcmDeviceType.WEB);

Handling authentication results

Check the returned SoliboAuthentication: tokens indicates a completed login; challenge requires another step. A missing result is not a successful login. Handle thrown errors in your login UI too.

Challenge type Next step
NEW_PASSWORD Ask for a new password, confirm it, then log in again.
SMS_MFA, TOTF_MFA, EMAIL_TOTF_MFA Ask for the verification code and call answerMfaChallenge.
SELECT_MFA Let the user choose a method with createMfaSelection.
SETUP_MFA Start MFA enrollment.

TOTF_MFA and EMAIL_TOTF_MFA are the contract’s names for authenticator-app (TOTP) and email one-time codes.

Call sdk.auth.clearSession() when the user cancels a challenge.

Two sign-in failures are not wrong credentials. DeviceRegistrationException means the device Cognito issued could not be registered. DeviceRejectedException means the server could not verify the device the sign-in was challenged for, after the code was accepted. The code is spent, so start the sign-in again: the SDK has forgotten that device, and the next email or SMS sign-in finishes without a device challenge.

Required new password (NEW_PASSWORD)

Use the same login that started the challenge. Confirmation returns a Boolean, so start a fresh login after success. The form supplies login and newPassword below.

if (sdk.auth.confirmNewPassword(login, newPassword)) {
    val result = sdk.auth.initiateAuth(
        FcmDeviceType.ANDROID,
        Credentials(login, newPassword)
    )
    // Check result for tokens or another challenge.
}

import { Credentials, FcmDeviceType } from '@solibo/solibo-sdk';

if (await sdk.auth.confirmNewPassword(login, newPassword)) {
  const result = await sdk.auth.initiateAuth(
    FcmDeviceType.WEB,
    new Credentials(login, newPassword),
  );
  // Check result for tokens or another challenge.
}

If confirmation fails, start a fresh login before retrying.

Forgotten password

forgotPassword sends a reset code by email or SMS, depending on the login. Pass that code to confirmNewPassword, then log in again with the new password.

if (sdk.auth.forgotPassword(login)) {
    // After the user enters the code:
    sdk.auth.confirmNewPassword(login, newPassword, code)
}

if (await sdk.auth.forgotPassword(login)) {
  // After the user enters the code:
  await sdk.auth.confirmNewPassword(login, newPassword, code);
}

Multi-factor authentication (MFA)

Answering an MFA challenge

The SDK remembers the current challenge type. Check the returned authentication result before continuing.

val result = sdk.auth.answerMfaChallenge(code = "123456")

const result = await sdk.auth.answerMfaChallenge('123456');

MFA management (enrolling and disabling)

For TOTP, show the association secret in your authenticator setup UI, then verify a code from the user’s authenticator app. Pass the returned session to verification.

val association = sdk.auth.createTOTPMfa()
// Show association.secret in your setup UI.

// After the user enters a code:
sdk.auth.verifyCreateTOTPMfa(
    code = "123456",
    deviceName = "My Phone",
    session = association.session
)

const association = await sdk.auth.createTOTPMfa();
// Show association.secret in your setup UI.

// After the user enters a code:
await sdk.auth.verifyCreateTOTPMfa('123456', 'My Phone', association.session);

Use createMfaPreference(MfaType.TOTP) to set the preferred method and removeMfa() to disable MFA. TypeScript imports MfaType from @solibo/solibo-sdk.

Sign out

logout() revokes the session’s refresh token, if it holds one, and clears the stored session. It returns false when no one is signed in, or when the server could not revoke the token; the stored tokens are then kept. A cookie session holds no refresh token, so logout() only clears the SDK’s own state; the Solibo Home cookies stay until the person signs out at home.solibo.no.

val signedOut = sdk.auth.logout()

const signedOut = await sdk.auth.logout();

A cookie session relies on the HttpOnly SOLIBO_HOME_* cookies that Solibo Home sets for home.solibo.no under /api; your code never sees them. Configure the client as in Pages Solibo hosts on solibo.no (the raw builder’s switch is setCredentials('include')). Sign-in itself happens on home.solibo.no: send people to https://home.solibo.no/auth/login?next=<page URL> and they return signed in. The login page returns only to pages on developers, swagger and async.solibo.no.

React integration (solibo-react)

Inside a SoliboProvider, access sdk.auth through useSoliboApi(). MFA hooks are also available from @solibo/solibo-react:

  • useAnswerMfaChallenge() submits a login verification code.
  • useCreateTOTPMfa() and useVerifyCreateTOTPMfa() manage enrollment.
  • useCreateMfaPreference() and useRemoveMfa() manage the user’s preference.

See Getting started for provider setup.

Solibo AS