|
| 1 | +--- |
| 2 | +title: "Authenticate end users with OAuth" |
| 3 | +linkTitle: "OAuth" |
| 4 | +weight: 60 |
| 5 | +layout: "docs" |
| 6 | +type: "docs" |
| 7 | +description: "Create a branded login screen for your application." |
| 8 | +images: ["/general/code.png"] |
| 9 | +date: "2025-01-22" |
| 10 | +--- |
| 11 | + |
| 12 | +You can use Viam to manage your user authentication. |
| 13 | +This guide will show you how to create a branded login screen. |
| 14 | + |
| 15 | +{{<imgproc src="/operate/oauth.png" resize="1000x" declaredimensions=true alt="Example Oauth screenshot" style="width:600px" class="imgzoom">}} |
| 16 | + |
| 17 | +## Prerequisites |
| 18 | + |
| 19 | +{{< table >}} |
| 20 | +{{% tablestep link="/dev/tools/cli/#organizations" %}} |
| 21 | +**1. Add your logo** |
| 22 | + |
| 23 | +Add a logo to be displayed on the login screen for your organization. |
| 24 | +Your logo can be up to 200KB in size and must be in PNG format. |
| 25 | + |
| 26 | +```sh {class="command-line" data-prompt="$" data-output="2-10"} |
| 27 | +viam organization logo set --logo-path=logo.png --org-id=<org-id> |
| 28 | +Successfully set the logo for organization <org-id> to logo at file-path: logo.png |
| 29 | +``` |
| 30 | + |
| 31 | +You must have [owner permissions](/manage/manage/rbac/#organization-settings-and-roles) on the organization. |
| 32 | + |
| 33 | +{{% /tablestep %}} |
| 34 | +{{% tablestep link="/dev/tools/cli/#organizations" %}} |
| 35 | +**2. Add support email** |
| 36 | + |
| 37 | +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. |
| 38 | + |
| 39 | +```sh {class="command-line" data-prompt="$" data-output="2-10"} |
| 40 | +viam organization support-email set [email protected] --org-id= <org-id > |
| 41 | +Successfully set support email for organization "<org-id>" to "[email protected]" |
| 42 | +``` |
| 43 | + |
| 44 | +{{% /tablestep %}} |
| 45 | +{{< /table >}} |
| 46 | + |
| 47 | +## Set up auth app |
| 48 | + |
| 49 | +{{< table >}} |
| 50 | +{{% tablestep link="/dev/tools/cli/#organizations" %}} |
| 51 | +**1. Enable authentication** |
| 52 | + |
| 53 | +Enable the authentication service for your organization: |
| 54 | + |
| 55 | +```sh {class="command-line" data-prompt="$" data-output="2-10"} |
| 56 | +viam organization auth-service enable --org-id=<org-id> |
| 57 | +enabled auth service for organization "<org-id>": |
| 58 | +``` |
| 59 | + |
| 60 | +{{% /tablestep %}} |
| 61 | +{{% tablestep link="/dev/tools/cli/#organizations" %}} |
| 62 | +**2. Create OAuth app** |
| 63 | + |
| 64 | +Create your OAuth application for your organization: |
| 65 | + |
| 66 | +```sh {class="command-line" data-prompt="$" data-output="6-10"} |
| 67 | +viam organization auth-service oauth-app create --client-authentication=required \ |
| 68 | + --client-name="OAuth Test App" --enabled-grants="password, authorization_code" \ |
| 69 | + --logout-uri="https://logoipsum.com/logout" --origin-uris="https://logoipsum.com,http://localhost:3000" \ |
| 70 | + --pkce=not_required --redirect-uris="https://logoipsum.com/oauth-redirect,http://localhost:3000/oauth-redirect" \ |
| 71 | + --url-validation=allow_wildcards --org-id=<org-id> |
| 72 | +Successfully created OAuth app OAuth Test App with client ID <client-id> and client secret <secret-token> |
| 73 | +``` |
| 74 | + |
| 75 | +{{% expand "Click to view more information about arguments." %}} |
| 76 | + |
| 77 | +<!-- prettier-ignore --> |
| 78 | +| Argument | Description | Required? | |
| 79 | +| -------- | ----------- | --------- | |
| 80 | +| `--client-authentication` | The client authentication policy for the OAuth application. Options: `unspecified`, `required`, `not_required`, `not_required_when_using_pkce`. Default: `unspecified`. | **Required** | |
| 81 | +| `--client-name` | The name for the OAuth application. | **Required** | |
| 82 | +| `--enabled-grants` | Comma-separated enabled grants for the OAuth application. Options: `unspecified`, `refresh_token`, `password`, `implicit`, `device_code`, `authorization_code`. | **Required** | |
| 83 | +| `--logout-uri` | The logout uri for the OAuth application. | **Required** | |
| 84 | +| `--org-id` | The organization ID that is tied to the OAuth application. | **Required** | |
| 85 | +| `--origin-uris` | Comma-separated origin URIs for the OAuth application. | **Required** | |
| 86 | +| `--pkce` | Proof Key for Code Exchange (PKCE) for the OAuth application. Options: `unspecified`, `required`, `not_required`, `not_required_when_using_client_authentication`. Default: `unspecified`. | **Required** | |
| 87 | +| `--redirect-uris` | Comma-separated redirect URIs for the OAuth application. | **Required** | |
| 88 | +| `--url-validation` | URL validation for the OAuth application. Options: `unspecified`, `exact_match`, `allow_wildcards`. Default: `unspecified`. | **Required** | |
| 89 | + |
| 90 | +{{% /expand%}} |
| 91 | + |
| 92 | +{{% /tablestep %}} |
| 93 | +{{% tablestep link="/dev/tools/cli/#organizations" %}} |
| 94 | +**3. See OAuth app** |
| 95 | + |
| 96 | +```sh {class="command-line" data-prompt="$" data-output="2-5,7-20"} |
| 97 | +viam organization auth-service oauth-app list --org-id=<org-id> |
| 98 | +OAuth apps for organization "<org-id>": |
| 99 | + |
| 100 | + - <client-id> |
| 101 | + |
| 102 | +viam organization auth-service oauth-app read --org-id=<org-id> --client-id=<client-id> |
| 103 | +OAuth config for client ID <client-id>: |
| 104 | + |
| 105 | +Client Authentication: required |
| 106 | +PKCE (Proof Key for Code Exchange): not_required |
| 107 | +URL Validation Policy: allow_wildcards |
| 108 | +Logout URL: https://logoipsum.com/logout |
| 109 | +Redirect URLs: https://logoipsum.com/oauth-redirect, http://localhost:3000/oauth-redirect |
| 110 | +Origin URLs: https://logoipsum.com, http://localhost:3000 |
| 111 | +Enabled Grants: authorization_code, password |
| 112 | +``` |
| 113 | + |
| 114 | +{{% /tablestep %}} |
| 115 | +{{< /table >}} |
| 116 | + |
| 117 | +You can update any value after setup using `viam organization auth-service oauth-app update`. |
| 118 | + |
| 119 | +## Use the generated client ID and secret in your app |
| 120 | + |
| 121 | +Your authentication is built on top of FusionAuth. |
| 122 | +To continue, use the generated client secret and client ID with the [Fusion Auth SDKs](https://fusionauth.io/docs/sdks/). |
| 123 | + |
| 124 | +For a quick example, see [Get started with FusionAuth in 5 minutes](https://github.com/FusionAuth/fusionauth-example-5-minute-guide). |
| 125 | + |
| 126 | +{{< alert title="Base URL" color="tip" >}} |
| 127 | + |
| 128 | +When using the client ID and client secret, the base URL for your OAuth application is `https://auth.viam.com`. |
| 129 | + |
| 130 | +{{< /alert >}} |
| 131 | + |
| 132 | +## FAQ |
| 133 | + |
| 134 | +### Can I customize my login screen further? |
| 135 | + |
| 136 | +If you need further customization, please [contact us ](mailto:[email protected]). |
0 commit comments