Authenticate end users with OAuth

You can use Viam to manage your user authentication. This guide will show you how to create a branded login screen.

Example Oauth login screen

Prerequisites

1. Add your logo

Add a 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. Add support email

This is the 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 authentication

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 OAuth app

Create your 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

You can update any value after setup using viam organization auth-service oauth-app update.

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.

Previous

Permissions

Next

White-labelled Billing