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

Open Beginner friendly
#2,874 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

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

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.

Description

type/docs
Summary

The "Work with cookies" section in Add authentication for app plugins
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:

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.
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
    is enabled.

To call the Grafana API from your app backend, use externalServiceAccounts
see the
app-with-service-account
and
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

Dominant language
TypeScript
Stars
89
Forks
58
Avg merge
4d 21h
Merged PRs (30d)
28

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from grafana/plugin-tools

All issues in grafana/plugin-tools

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.