grafana / grafana/plugin-tools

Docs: app plugin "Work with cookies" section documents behavior removed

Open Beginner friendly
#2,874 0 comments 0 reactions 0 assignees View on GitHub
type/docs
Dominant language
TypeScript
Stars
89
Forks
57
Avg merge
3d 17h
Merged PRs (30d)
37

Description

### Summary

The "Work with cookies" section in [Add authentication for app plugins](https://grafana.com/developers/plugin-tools/how-to-guides/app-plugins/add-authentication-for-app-plugins#work-with-cookies)
states:

> Your app plugin can read the cookies forwarded by Grafana to the app.

Cookies aren't forwarded to app plugin backends, and there is no configuration to
opt in.

### Why it's wrong

Cookie forwarding to app plugins was removed in
grafana/grafana#88663 ("Plugins: Don't forward cookies for app plugins"), which
was backported to every then-supported branch (9.5.x through 11.0.x). Before that
change, app plugins skipped the cookie middleware entirely via an early return on
`pCtx.DataSourceInstanceSettings == nil`; the fix removed the early return so the
filtering applies to apps too.

Because the allow-list is only populated from data source settings:

```go
allowedCookies := []string{}
if pCtx.DataSourceInstanceSettings != nil {
allowedCookies = ds.AllowedCookies() // jsonData.keepCookies
}
proxyutil.ClearCookieHeader(reqCtx.Req, allowedCookies, m.skipCookiesNames)
```

an app plugin always gets an empty allow-list, and `ClearCookieHeader` deletes the
`Cookie` header and re-adds nothing. This is still the case on `main` today.

### Impact

A plugin developer following this guide will write a resource handler that reads
`req.Cookies()`, get an empty list with no error or warning, and have no way to
tell from the docs that it's expected. The only signal is reading Grafana's
middleware source.

Note also that the data source guide's equivalent section is correct and complete
- it documents both configuring **Allowed cookies** (`jsonData.keepCookies`) *and*
extracting them. The app version contains only the extraction half, without the
configuration step that makes it work (and which has no app equivalent).

### Suggested fix

Replace the section with an explicit statement of the current behavior plus
pointers to the supported alternatives. Something like:

> ### Work with cookies
>
> Grafana does not forward cookies to app plugin backends. Cookie forwarding is
> available only for data source plugins, configured with the **Allowed cookies**
> option - see
> [Add authentication for data source plugins](../data-source-plugins/add-authentication-for-data-source-plugins.md#work-with-cookies).
> There is no equivalent setting for app plugins.
>
> To identify the user who made a request to your app backend, use one of:
>
> - `backend.PluginConfigFromContext(req.Context()).User` — login, name, email,
> and role of the calling user, when a user originated the request.
> - The `X-Grafana-Id` header (`idForwarding`) — a signed token your backend can
> verify.
> - The `X-Grafana-User` header, when
> [`send_user_header`](https://grafana.com/docs/grafana/latest/setup-grafana/configure-grafana/#send_user_header)
> is enabled.
>
> To call the Grafana API from your app backend, use `externalServiceAccounts` —
> see the
> [app-with-service-account](https://github.com/grafana/grafana-plugin-examples/tree/main/examples/app-with-service-account)
> and
> [app-with-rbac](https://github.com/grafana/grafana-plugin-examples/tree/main/examples/app-with-rbac)
> examples.

Minor, but worth catching if any of the current snippet is retained: it writes
`{"message": "ok}` (unterminated JSON string), calls `w.WriteHeader(http.StatusOK)`
after `w.Write` where it has no effect, and uses stdlib `log.Printf` rather than
the plugin SDK logger used elsewhere on the same page.

cc @grafana/docs-plugins @grafana/grafana-frontend-platform

Contributor guide

Open the contributing guide

Research direction

Open the “Work with cookies” section in the Add authentication for app plugins guide and compare it with the linked data source plugin guide. Update the app guidance to describe the current behavior and supported alternatives, then check the rendered links, code snippets, and examples for correctness.

Written by the indexing model from the issue text.

Assessment

Tech stack
go
Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
Half a day
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
82/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.