docs/explanation/security: add authentication and authorization section#193
docs/explanation/security: add authentication and authorization section#193ernestl wants to merge 18 commits intocanonical:mainfrom
Conversation
…e persisted data to correct data location sectionw
|
|
||
| A Linux system user is a standard user account on the host operating system. | ||
|
|
||
| System users are uniquely identified by their system username. Snapd may associate a Linux system user with a snapd user so that API requests originating from that account can be authenticated and authorized. |
There was a problem hiding this comment.
they can also be identified by their user id, both are unique
There was a problem hiding this comment.
Changed to ...system username or user ID (UID)
|
|
||
| System users are uniquely identified by their system username. Snapd may associate a Linux system user with a snapd user so that API requests originating from that account can be authenticated and authorized. | ||
|
|
||
| In managed environments such as Ubuntu Core systems, Linux system users may be created based on system user assertions signed by the device brand or retrieved from the Snap Store. |
There was a problem hiding this comment.
the last bit is strange, I would drop the "retrieved from" bit, I don't think it's true
There was a problem hiding this comment.
I was referring to this https://github.com/canonical/snapd/blob/master/overlord/devicestate/users.go#L75.
I have now clarified: In managed environments such as Ubuntu Core systems, Linux system users may be created from system-user assertions signed by the device brand, or from user information retrieved from the Snap Store for a given store user email address.
|
|
||
| This file contains the snapd user identity and authentication tokens. Clients such as the snap command-line tool read this file and include the relevant credentials when making requests to the snapd API. | ||
|
|
||
| These credentials allow snapd to authenticate subsequent API requests and perform operations on behalf of the user. |
There was a problem hiding this comment.
I think we need to be a bit more clear where API means snapd API vs store API. I would also "on behalf"/"for", unless you are thinking of store operations?
There was a problem hiding this comment.
Changed to "...snapd API requests and perform operations for the user."
|
|
||
| ## Interface-based authorization | ||
|
|
||
| Some API operations require that specific snap interfaces are connected. |
There was a problem hiding this comment.
..., this is relevant for operation requested by snaps over the snap API access socket.
There was a problem hiding this comment.
Does this work? Some API operations requested by snaps via the snap API access socket require that specific snap interfaces are connected.
docs/explanation/security/api-authentication-and-authorization.md
Outdated
Show resolved
Hide resolved
There was a problem hiding this comment.
Pull request overview
This PR extends the Sphinx/MyST security documentation by adding new pages/sections covering snapd API authentication/authorization and snapd decommissioning, and by expanding existing security policy documentation (including cryptography provenance and security maintenance lifecycle details). The PR description references a follow-up to PR #179, but this review is limited to the diffs included here.
Changes:
- Add new “API authentication and authorization” and “Decommissioning” explanation pages and link them from the security index.
- Expand
security-policies.mdwith cryptography provenance notes and a new “Security maintenance” section; fix a few formatting issues in refresh awareness text. - Add a dedicated anchor in
data-locations.mdfor “Persisted data on Ubuntu Core” and update cross-references to point to it.
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 11 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/reference/administration/data-locations.md | Adds an anchor label for the Ubuntu Core persisted data section to support more specific cross-references. |
| docs/explanation/security/snap-confinement.md | Adjusts the Classic confinement link (currently in a way that likely breaks the reference). |
| docs/explanation/security/security-policies.md | Adds cryptography provenance + security maintenance content; updates cross-references and refresh awareness formatting. |
| docs/explanation/security/index.md | Adds nav links/toctree entries for the new security pages (currently with a toctree filename mismatch). |
| docs/explanation/security/decomissioning.md | Introduces decommissioning guidance (currently has label whitespace + typos + structure issues, and filename spelling mismatch). |
| docs/explanation/security/api-authentication-and-authorization.md | Introduces API auth/authz overview content, including auth data location and authorization mechanisms. |
|
|
||
| If required, root and other user data should be manually removed by wiping `/root/snap/` and `/root/.snap/` as well as `/home/$USER/snap/` and `/home/$USER/.snap/`. | ||
|
|
||
| ## Removing journal logs |
There was a problem hiding this comment.
"Removing journal logs" is at ## level while the preceding removal steps are ### subsections under "Classic systems". This breaks the page structure; it should likely be a ### subsection as well (or the earlier subsections should be promoted consistently).
| ## Removing journal logs | |
| ### Removing journal logs |
bboozzoo
left a comment
bboozzoo
left a comment
There was a problem hiding this comment.
LGTM, assuming comments from copilot are addressed
| The authenticated identity is persisted in: | ||
|
|
||
| ```console | ||
| <home>/.snap/auth.json |
There was a problem hiding this comment.
$HOME is probably more in line with using $USER elsewhere
|
|
||
| If required, root and other user data should be manually removed by wiping `/root/snap/` and `/root/.snap/` as well as `/home/$USER/snap/` and `/home/$USER/.snap/`. | ||
|
|
||
| ## Removing journal logs |
Follow up of WIP #179 that was accidentally merged early.
Please also look at provide feedback on #179.