# The sign-in flow

Sign in with Buun is OAuth 2.1 with OpenID Connect: an authorization code with PKCE S256, traded at the token endpoint for an access token, an ID token and, when asked for, a refresh token.

## The steps

1. Send the browser to `GET /oauth/authorize` with the parameters below.
2. Buun Identity signs the person in at the account portal, by an emailed code and their second step when they have one. A Buun Group product's own client skips the consent page; another company's client shows it.
3. The browser comes back to your `redirect_uri` with `code`, `state` and `iss`. Check `state` is yours and `iss` is the issuer.
4. Post the code to `POST /oauth/token` with the PKCE verifier.
5. Check the access token and the ID token, then find or make your own user by `sub`.

## Authorize parameters

| Parameter | Required | Value |
|---|---|---|
| `response_type` | Yes | `code`. Nothing else is supported |
| `client_id` | Yes | Your client's id, `cli_...` |
| `redirect_uri` | Yes | One of your registered addresses, exactly. Checked before anything else |
| `scope` | Yes | Space separated, from `openid profile email orgs offline_access`, within what your client may ask for |
| `state` | Recommended | A random value you check on return |
| `code_challenge` | Yes | The SHA-256 of your verifier, base64url, no padding |
| `code_challenge_method` | Yes | `S256` |
| `nonce` | No | Repeated in the ID token |
| `resource` | No | The API the access token is for (RFC 8707). Must be in your client's `resources`. Without it, the token's audience is your client |
| `prompt` | No | `none` never shows a page and answers `login_required` or `consent_required`. `login` and `consent` always show the portal |

A client or redirect address that cannot be trusted gets a page at Buun Identity, never a redirect. Every other mistake goes back to your `redirect_uri` as `error` and `error_description`.

## The token request

```http
POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&client_id=cli_your_product&code=buun_ac_...&redirect_uri=https%3A%2F%2Fapp.your-product.dev%2Fauth%2Fcallback&code_verifier=...
```

A confidential client also proves itself, with HTTP Basic (`client_secret_basic`) or `client_secret` in the body (`client_secret_post`). A public client sends no secret: PKCE is its proof.

```json
{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 900,
  "id_token": "eyJ...",
  "refresh_token": "buun_rt_...",
  "scope": "openid profile email offline_access"
}
```

## Refreshing

`grant_type=refresh_token&refresh_token=buun_rt_...&client_id=...` answers new tokens and a new refresh token. The old one is spent: use it again and the whole family ends, because a refresh token used twice was stolen. A refresh token lasts 30 days.

## Signing out

`POST /oauth/revoke` with `token=buun_rt_...` ends the refresh token and its family. It always answers 200 for a known client (RFC 7009).

## Linking a person to your own user

1. A user of yours already has this `sub`: that is them.
2. A user of yours has the same address, verified on your side, and the ID token says `email_verified: true`: link them.
3. Neither: make a new user.

Never link by an address that is not verified on both sides.

Source: https://developers.buungroup.com/sign-in/flow
