diff --git a/.vitepress/sidebars/dashboard/concepts.ts b/.vitepress/sidebars/dashboard/concepts.ts index c3067145..1fe01d7c 100644 --- a/.vitepress/sidebars/dashboard/concepts.ts +++ b/.vitepress/sidebars/dashboard/concepts.ts @@ -8,6 +8,10 @@ export const conceptsSidebar: DefaultTheme.SidebarItem[] = [ text: "Introduction", link: "/dashboard/concepts/", }, + { + text: "Personal Access Token", + link: "/dashboard/concepts/pat", + }, { text: "Workspace", link: "/dashboard/concepts/workspace", diff --git a/.vitepress/sidebars/dashboard/guides.ts b/.vitepress/sidebars/dashboard/guides.ts index 6eed75ac..9c43abde 100644 --- a/.vitepress/sidebars/dashboard/guides.ts +++ b/.vitepress/sidebars/dashboard/guides.ts @@ -10,6 +10,15 @@ export const guidesSidebar: DefaultTheme.SidebarItem[] = [ }, ], }, + { + text: "Users", + items: [ + { + text: "Creating a Personal Access Token", + link: "/dashboard/guides/create_pat", + }, + ], + }, { text: "Teams", items: [ diff --git a/src/_images/authentication_consent.png b/src/_images/authentication_consent.png new file mode 100644 index 00000000..3d699c5a Binary files /dev/null and b/src/_images/authentication_consent.png differ diff --git a/src/_images/new_pat.png b/src/_images/new_pat.png new file mode 100644 index 00000000..01c176dd Binary files /dev/null and b/src/_images/new_pat.png differ diff --git a/src/_images/pat_page.png b/src/_images/pat_page.png new file mode 100644 index 00000000..d429f378 Binary files /dev/null and b/src/_images/pat_page.png differ diff --git a/src/_images/pat_team.png b/src/_images/pat_team.png new file mode 100644 index 00000000..55a24ed9 Binary files /dev/null and b/src/_images/pat_team.png differ diff --git a/src/_images/pat_user.png b/src/_images/pat_user.png new file mode 100644 index 00000000..2f1b1872 Binary files /dev/null and b/src/_images/pat_user.png differ diff --git a/src/app/concepts/instance_authentication.md b/src/app/concepts/instance_authentication.md index 37b08c2d..417e52e7 100644 --- a/src/app/concepts/instance_authentication.md +++ b/src/app/concepts/instance_authentication.md @@ -12,10 +12,15 @@ Authentication in Caido is based on [OAuth 2.0](https://www.rfc-editor.org/rfc/r Like we mentioned in [instance registration](./instance_registration.md), each Caido instance registers itself with our Cloud as an `OAuth 2.0 client`. -When you click on `Login` on the instance, it performs a Device Authorization flow. Currently this flow requires a human approval via the website (we are working on removing this limitation). +When you click on `Login` on the instance, it performs a Device Authorization flow. Authenticate user flow. +This flow is usually approved with the consent form on the [Dashboard](https://dashboard.caido.io). +It can also be approved using [Personal Access Tokens](/dashboard/concepts/pat) if you want to interact with the instance in headless mode (CICD for example). + +Consent form for authentication + ::: warning NOTE We do not make any guarantees on the lifetime of the tokens. Currently the access token is valid for 7 days and the refresh token is valid for 3 months. diff --git a/src/dashboard/concepts/pat.md b/src/dashboard/concepts/pat.md new file mode 100644 index 00000000..7f541b8c --- /dev/null +++ b/src/dashboard/concepts/pat.md @@ -0,0 +1,22 @@ +# Personal Access Token + +Personal Access Tokens (PAT) are used to access the public [API of Caido Cloud](https://developer.caido.io/reference/api.html). +For example, they can be used to invite new members to a Team or approve an headless login to a Caido instance. + +You can easily recognize a Caido PAT as they start with `caido_`. + +::: info +Each PAT is tied to a user and will act with the same level of permissions as that user. +::: + +Pat view for users + +A PAT can either be created to access resources for your own account or a specific Team (the resource owner). + +::: info +PATs created for a Team will be visible by the admins of that Team, but they won't be able to revoke them. +::: + +Pat view for team admins + +To get started with PAT, [learn how to create one](/dashboard/guides/create_pat). diff --git a/src/dashboard/guides/create_pat.md b/src/dashboard/guides/create_pat.md new file mode 100644 index 00000000..a16f386c --- /dev/null +++ b/src/dashboard/guides/create_pat.md @@ -0,0 +1,22 @@ +# Creating a Personal Access Token + +[PAT](/dashboard/concepts/pat) can be used as the authentication method for the [Caido Cloud API](https://developer.caido.io/reference/api.html). + +To create a new PAT, visit the Developer page on your account. + +PAT Page for user + +You can then click on `+ Create Token`. You will be presented with a form. + +The options are: + +- `Name`: A descriptive name for the PAT +- `Resource Owner`: Either Yourself or one of the Teams you belong to. +- `Expiration`: When will the PAT expire, we strongly recommend setting an expiration date + +::: tip +If you want to access resources (instances, users, subscription, etc.) for a Team, you need to select that Team as the resource owner. +On the contrary, if you want to access resources for your own account, choose `Yourself` as the owner. +::: + +New PAT Form