> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kubestacks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sign in with a token

> The default way to sign in: people paste a bearer token the cluster accepts, and every request they make carries it.

Signing in with a token is the default, and needs nothing set up besides KubeStacks itself. People paste a bearer token the cluster accepts, and KubeStacks sends their requests with it: the cluster checks the token, and applies its RBAC. KubeStacks' own service account needs no permissions at all.

<Frame caption="Signing in with a token.">
  <img className="block dark:hidden" loading="lazy" src="https://cdn.jsdelivr.net/gh/KubeStacks/KubeStacks@main/docs/screenshots/server-sign-in-light-1x.webp" alt="The KubeStacks sign-in page, with a field to paste a token, a Sign in button, and the kubectl command that creates a service account's token." />

  <img className="hidden dark:block" loading="lazy" src="https://cdn.jsdelivr.net/gh/KubeStacks/KubeStacks@main/docs/screenshots/server-sign-in-dark-1x.webp" alt="The KubeStacks sign-in page, with a field to paste a token, a Sign in button, and the kubectl command that creates a service account's token." />
</Frame>

```yaml values.yaml theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
auth:
  mode: token # the default
```

## How signing in works

<Steps>
  <Step title="Someone pastes a token">
    On the sign-in page, under **Token**, then **Sign in**.
  </Step>

  <Step title="KubeStacks asks the cluster whose it is">
    It sends a SelfSubjectReview with the token, and the API server answers with the user and groups the token belongs to. A token the cluster rejects gets **The cluster doesn't accept this token.**
  </Step>

  <Step title="A session starts">
    KubeStacks keeps the token in its memory, and gives the browser a random session ID in a cookie. From then on, every request that person makes carries their token.
  </Step>
</Steps>

<Warning>
  Signing in with a token needs Kubernetes 1.28 or later, where SelfSubjectReviews are generally available. On older clusters, use [single sign-on](/server/auth/single-sign-on) or an [authenticating proxy](/server/auth/proxy).
</Warning>

## Which tokens work

Any bearer token the API server accepts:

* **A service account's token.** Good for trying KubeStacks, for shared read-only access, or for automation. Bind the service account a role, then make a token for it:

  ```bash theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
  kubectl create serviceaccount alice --namespace kubestacks
  kubectl create clusterrolebinding alice-view --clusterrole view \
    --serviceaccount kubestacks:alice
  kubectl create token alice --namespace kubestacks
  ```

  The token is valid for an hour. `--duration` asks for a longer one, up to what your API server allows.

* **A token from your identity provider**, if the API server accepts it: through its `--oidc-*` flags, or a structured authentication configuration. Then people sign in as themselves.

The sign-in page shows people how to make a service account's token, with a button to copy the command.

## When sessions end

* **The token expires, or is revoked.** The next time the cluster refuses it, the session ends, and KubeStacks asks for another token: **Your session ended. Sign in again to carry on where you were.**
* **The session reaches its length.** Sessions last 12 hours unless `auth.sessionHours` says otherwise, at most a week.
* **Someone signs out**, from the account menu at the bottom of the sidebar. That ends their session in every tab.
* **KubeStacks restarts.** Sessions live in its memory, so an upgrade signs everyone out.

Once it's pasted, KubeStacks keeps the token in its memory and sends it only to the API server. The browser holds only the session ID, in a cookie scripts can't read.

## Give people the access they need

KubeStacks shows each person exactly what their token allows, and turns off the actions it doesn't, saying why. To let a team work in its own namespaces, bind its service account (or its people) a role there:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
kubectl create rolebinding shop-team-edit --clusterrole edit \
  --serviceaccount kubestacks:shop-team --namespace shop
```

See [Permissions](/clusters/permissions) for what each part of KubeStacks needs.

<Columns cols={2}>
  <Card title="Single sign-on" icon="log-in" href="/server/auth/single-sign-on">
    Let people sign in with your identity provider instead.
  </Card>

  <Card title="Signing in, for your team" icon="users" href="/get-started/sign-in">
    The page to send people who'll use KubeStacks.
  </Card>
</Columns>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.