Setting Up OTP Authentication

This guide will walk you through the steps to set up OTP (One-Time Password) authentication for facility users using GraphQL.

Steps

1. Setup OTP Authentication

To initiate the OTP setup, the facility needs to request OTP setup. This can be done using the following GraphQL query:

query FacilitySetupOtpAuth($forceSetup: Boolean) {
  facilitySetupOtpAuth(forceSetup: $forceSetup) {
    otpQrCode
    otpSecretText
    otpUri
    id
    otpEnabled 
    otpStatus
  }
}

Variables:

{
  "forceSetup": false // Set to true if you want to force setup
}

Response

{
  "data": {
    "facilitySetupOtpAuth": {
      "otpQrCode": "svg_string_qr_code",
      "otpSecretText": "secret",
      "otpUri": "otpauth://totp/...",
      "id": "facility_id",
      "otpEnabled": false,
      "otpStatus": "initiated"
    }
  }
}

2. Display OTP QR Code

The response from the facilitySetupOtpAuth query will include the otpQrCode, otpSecretText, and otpUri. Display the otpQrCode to the facility so they can scan it using an OTP app like Google Authenticator (or any other OTP app).

3. Complete OTP setup

Once the facility has scanned the QR code and generated an OTP code, they need to verify it. This can be done using the following GraphQL mutation:

mutation CompleteFacilityOtpSetup($id: ID!, $input: CompleteFacilityOtpSetupInput!) {
  completeFacilityOtpSetup(id: $id, input: $input) {
    result {
      id
      otpEnabled
      otpStatus
    }
  }
}

Variables:

{
  "id": "facility_id",
  "input": {
    "otpCode": "123456"
  }
}

Response

{
  "data": {
    "completeFacilityOtpSetup": {
      "result": {
        "id": "facility_id",
        "otpEnabled": true,
        "otpStatus": "enabled"
      }
    }
  }
}

If the OTP code is verified successfully, the OTP setup is complete. The facility can now use OTP for authentication.

Next time the facility signs in, you'll need to prompt them for the OTP code.

4. Sign In with OTP

When the facility signs in, they will receive an OTP token, if OTP is enabled, instead of the regular login token. They will need to verify and complete the sign in process using the OTP token and an OTP code.

4a. Normal Sign-In will return an OTP token.

query FacilitySignIn($email: String!, $password: String!) {
  facilitySignIn(email: $email, password: $password) {
    token
    id    
  }
}

Variables:

{
  "email": "facility@example.com", // Replace with the facility's email
  "password": "password123" // Replace with the facility's password
}

Response will include token with prefix otp_.

{
  "data": {
    "facilitySignIn": {
      "token": "otp_SomeOtpToken",
      "id": "facility_id"
    }
  }
}

4b. Verify Sign-In with OTP Code

To complete the sign-in process, the facility must provide the OTP code from their OTP app. Use the OTP code and the token received in the previous step to verify the sign-in.

query FacilityVerifySignInWithOtpCode($otpCode: String!, $signInOtpToken: String!) {
  facilityVerifySignInWithOtpCode(otpCode: $otpCode, signInOtpToken: $signInOtpToken) {
    token
    id
  }
}

Variables:

{
  "otpCode": "123456",
  "signInOtpToken": "otp_SomeOtpToken" // Replace with the OTP token received during sign-in
}

Response

{
  "data": {
    "facilityVerifySignInWithOtpCode": {    
      "token": "login_token",
      "id": "facility_id"
    }
  }
}

Conclusion

By following these steps, facility users can set up OTP authentication using GraphQL. Ensure to handle errors and edge cases appropriately in your frontend application.