Authenticate end users with OAuth

If you are building a product on Viam, you can set up branded authentication for your end users. This guide shows you how to create a branded login screen using Viam’s OAuth integration, which is built on FusionAuth.

Example Oauth login screen

Prerequisites

1

Add the logo to be displayed on the login screen for your organization. Your logo can be up to 200KB in size and must be in PNG format.

viam organization logo set --logo-path=logo.png --org-id=<org-id>
Successfully set the logo for organization <org-id> to logo at file-path: logo.png

You must have owner permissions on the organization.

2

The support email that will be shown when Viam sends emails to users on your behalf for email verification, password recovery, and other account related emails.

viam organization support-email set --support-email=support@logoipsum.com --org-id=<org-id>
Successfully set support email for organization "<org-id>" to "support@logoipsum.com"

Set up auth app

1

Enable the authentication service for your organization:

viam organization auth-service enable --org-id=<org-id>
enabled auth service for organization "<org-id>":
2

Create an OAuth application for your organization:

viam organization auth-service oauth-app create --client-authentication=required \
    --client-name="OAuth Test App" --enabled-grants="password, authorization_code" \
    --logout-uri="https://logoipsum.com/logout" --origin-uris="https://logoipsum.com,http://localhost:3000" \
    --pkce=not_required --redirect-uris="https://logoipsum.com/oauth-redirect,http://localhost:3000/oauth-redirect" \
    --url-validation=allow_wildcards --org-id=<org-id>
Successfully created OAuth app OAuth Test App with client ID <client-id> and client secret <secret-token>
Click to view more information about arguments.
ArgumentDescriptionRequired?
--client-authenticationThe client authentication policy for the OAuth application. Options: unspecified, required, not_required, not_required_when_using_pkce. Default: unspecified.Required
--client-nameThe name for the OAuth application.Required
--enabled-grantsComma-separated enabled grants for the OAuth application. Options: unspecified, refresh_token, password, implicit, device_code, authorization_code.Required
--logout-uriThe logout uri for the OAuth application.Required
--org-idThe organization ID that is tied to the OAuth application.Required
--origin-urisComma-separated origin URIs for the OAuth application.Required
--pkceProof Key for Code Exchange (PKCE) for the OAuth application. Options: unspecified, required, not_required, not_required_when_using_client_authentication. Default: unspecified.Required
--redirect-urisComma-separated redirect URIs for the OAuth application.Required
--url-validationURL validation for the OAuth application. Options: unspecified, exact_match, allow_wildcards. Default: unspecified.Required
3

See OAuth app:

viam organization auth-service oauth-app list --org-id=<org-id>
OAuth apps for organization "<org-id>":

 - <client-id>

viam organization auth-service oauth-app read --org-id=<org-id> --client-id=<client-id>
OAuth config for client ID <client-id>:

Client Authentication: required
PKCE (Proof Key for Code Exchange): not_required
URL Validation Policy: allow_wildcards
Logout URL: https://logoipsum.com/logout
Redirect URLs: https://logoipsum.com/oauth-redirect, http://localhost:3000/oauth-redirect
Origin URLs: https://logoipsum.com, http://localhost:3000
Enabled Grants: authorization_code, password

The generated client ID is unique to your OAuth app and linked to your organization. You can update any value after setup using viam organization auth-service oauth-app update.

Designate a login client ID

If your organization has one or more OAuth apps, designate which one is used for the login and invite flow. The designated client ID controls which branded login screen users see when they open an organization invite link.

  1. Open the organization dropdown in the top right of Viam, next to your initials.
  2. Click Settings and invites to open the organization settings menu.
  3. Under White Labeling, find Login client ID.
  4. Enter the client ID of one of your registered OAuth apps and click Save.

The client ID must match one of the OAuth apps created in the previous step. The OAuth app must also include the organization invite redirect URI in its redirect URIs list; otherwise the save fails with a validation error.

When this field is set, organization invite links redirect users to the custom login screen for the designated OAuth app and pass your organization’s logo URL to the login screen. When this field is empty, invite links use Viam’s default login screen instead.

Use the generated client ID and secret in your app

Your authentication is built on top of FusionAuth. To continue, use the generated client secret and client ID with the Fusion Auth SDKs.

For a quick example, see Get started with FusionAuth in 5 minutes.

FAQ

Can I customize my login screen further?

If you need further customization, please contact us.