-
Notifications
You must be signed in to change notification settings - Fork 45
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
DOCS-3050: Add fusionauth instructions
- Loading branch information
Showing
2 changed files
with
153 additions
and
4 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,131 @@ | ||
| --- | ||
| title: "Authenticate end users with OAuth" | ||
| linkTitle: "OAuth" | ||
| weight: 60 | ||
| layout: "docs" | ||
| type: "docs" | ||
| description: "Create a branded login screen." | ||
| images: ["/general/code.png"] | ||
| date: "2025-01-22" | ||
| --- | ||
|
|
||
| If you want to set up a custom login screen, where Viam provides authentication and manages users for you but the branding is yours, follow these steps: | ||
|
|
||
| <!-- TODO screenshot of example unbranded login screen --> | ||
|
|
||
| ## Prerequisites | ||
|
|
||
| {{< table >}} | ||
| {{% tablestep link="/dev/tools/cli/#organizations" %}} | ||
| **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. | ||
|
|
||
| ```sh {class="command-line" data-prompt="$" data-output="2-10"} | ||
| 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](/manage/manage/rbac/#organization-settings-and-roles) on the organization. | ||
|
|
||
| {{% /tablestep %}} | ||
| {{% tablestep link="/dev/tools/cli/#organizations" %}} | ||
| **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. | ||
|
|
||
| ```sh {class="command-line" data-prompt="$" data-output="2-10"} | ||
| viam organization support-email set --support-email [email protected] --org-id <org-id> | ||
| Successfully set support email for organization "<org-id>" to "[email protected]" | ||
| ``` | ||
|
|
||
| {{% /tablestep %}} | ||
| {{< /table >}} | ||
|
|
||
| ## Set up auth app | ||
|
|
||
| {{< table >}} | ||
| {{% tablestep link="/dev/tools/cli/#organizations" %}} | ||
| **1. Enable authentication** | ||
|
|
||
| Enable the authentication service for your organization: | ||
|
|
||
| ```sh {class="command-line" data-prompt="$" data-output="2-10"} | ||
| viam organization auth-service enable --org-id <org-id> | ||
| enabled auth service for organization "<org-id>": | ||
| ``` | ||
|
|
||
| {{% /tablestep %}} | ||
| {{% tablestep link="/dev/tools/cli/#organizations" %}} | ||
| **2. Create OAuth app** | ||
|
|
||
| Create your OAuth application for your organization: | ||
|
|
||
| ```sh {class="command-line" data-prompt="$" data-output="6-10"} | ||
| viam organization auth-service oauth-app create --client-authentication required \ | ||
| --client-name "OAuth Test App" --enabled-grants password \ | ||
| --logout-uri "https://logoipsum.com/logout" --origin-uris https://logoipsum.com \ | ||
| --pkce not_required --redirect-uris https://logoipsum.com/callback \ | ||
| --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> | ||
| ``` | ||
|
|
||
| {{% expand "Click to view more information about arguments." %}} | ||
|
|
||
| <!-- prettier-ignore --> | ||
| | Argument | Description | Required? | | ||
| | -------- | ----------- | --------- | | ||
| | `--client-authentication` | The client authentication policy for the OAuth application. Options: `unspecified`, `required`, `not_required`, `not_required_when_using_pkce`. Default: `unspecified`. | **Required** | | ||
| | `--client-name` | The name for the OAuth application. | **Required** | | ||
| | `--enabled-grants` | Comma-separated enabled grants for the OAuth application. Options: `unspecified`, `refresh_token`, `password`, `implicit`, `device_code`, `authorization_code`. | **Required** | | ||
| | `--logout-uri` | The logout uri for the OAuth application. | **Required** | | ||
| | `--org-id` | The organization ID that is tied to the OAuth application. | **Required** | | ||
| | `--origin-uris` | Comma-separated origin URIs for the OAuth application. | **Required** | | ||
| | `--pkce` | pkce for the OAuth application. Options: `unspecified`, `required`, `not_required`, `not_required_when_using_client_authentication`. Default: `unspecified`. | **Required** | | ||
| | `--redirect-uris` | Comma-separated redirect URIs for the OAuth application. | **Required** | | ||
| | `--url-validation` | URL validation for the OAuth application. Options: `unspecified`, `exact_match`, `allow_wildcards`. Default: `unspecified`. | **Required** | | ||
|
|
||
| {{% /expand%}} | ||
|
|
||
| {{% /tablestep %}} | ||
| {{% tablestep link="/dev/tools/cli/#organizations" %}} | ||
| **3. See OAuth app** | ||
|
|
||
| ```sh {class="command-line" data-prompt="$" data-output="2-5,7-20"} | ||
| 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 | ||
| Redirect URLs: https://logoipsum.com/callback | ||
| Origin URLs: https://logoipsum.com | ||
| Enabled Grants: password | ||
| ``` | ||
|
|
||
| {{% /tablestep %}} | ||
| {{< /table >}} | ||
|
|
||
| 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](https://fusionauth.io/docs/sdks/). | ||
|
|
||
| ## FAQ | ||
|
|
||
| ### Can you update the link shown during authentication? | ||
|
|
||
| Currently it is not possible to update the link shown during authentication (`auth.viam.com`). | ||
|
|
||
| ### Can I customize my login screen further? | ||
|
|
||
| If you need further customization, please [contact us](mailto:[email protected]). |