starred/headscale
1
0
Fork 0
mirror of https://github.com/juanfont/headscale.git synced 2026-01-11 20:00:28 +01:00
Code Issues 98 Packages Projects Releases 10 Wiki Activity

Use Authorization in Swagger UI with SecurityDefinition in .swagger.json #611

New Issue
Closed
opened 2025-12-29 02:21:10 +01:00 by adam · 2 comments
adam commented 2025-12-29 02:21:10 +01:00
Owner
Copy Link

Originally created by @SwissGipfel on GitHub (Jan 9, 2024).

Why

Since headscale currently has no WebUI, it would be a quality of life feature to enable using the Swagger UI directly in the web browser without installing an add-on. (For what I've seen so far, a relatively small change)

Description

Swagger 2.0 lets you define an authentication type for each API endpoint. This definition will also be displayed in swagger UI and is usable as such. With it an admin can leverage the APIs listed on the /swagger endpoint directly without using cli tools or browser add-on.

Even though the documentation for version 2.0 does not mention bearer tokens for authentication, it is still usable if type: apikey together with name: Authorization is used in the securityDefinitions. With this configuration, an admin can brows /swagger, press Authorize and provide the value "Bearer " followed by the effective token.

What I've tried by myself

I think I know what changes have to be made to the .swagger.json files to enable this feature. I've a locally development build version running (in a container) and as far as I can see it works, with:

{
  "swagger": "2.0",
  "info": {
    "title": "headscale/v1/headscale.proto",
    "version": "version not set"
  },
  "securityDefinitions": {
    "Bearer": {
      "type": "apiKey",
      "name": "Authorization",
      "in": "header",
      "description": "Bearer token for authentication. Please type in 'Bearer' followed by a space and then the token."
    }
  },
  "security": [
    {
      "Bearer": ["read", "write"]
    }
  ],
  // followed by the rest of the generated .swagger.json file

in /gen/openapiv2/headscale/v1/headscale.swagger.json.

But I do currently not know, what kind of changes I've to make, so that the next make generate command won't overwrite the files.

Originally created by @SwissGipfel on GitHub (Jan 9, 2024). ## Why Since headscale [currently has no WebUI](https://github.com/juanfont/headscale/issues/234), it would be a quality of life feature to enable using the Swagger UI directly in the web browser without installing an add-on. (For what I've seen so far, a relatively small change) ## Description [Swagger 2.0 lets you define an authentication type for each API endpoint](https://swagger.io/docs/specification/2-0/authentication/). This definition will also be displayed in swagger UI and is usable as such. With it an admin can leverage the APIs listed on the `/swagger` endpoint directly without using cli tools or browser add-on. Even though the documentation for version 2.0 does not mention bearer tokens for authentication, it is still usable if `type: apikey` together with `name: Authorization` is used in the securityDefinitions. With this configuration, an admin can brows `/swagger`, press Authorize and provide the value "Bearer " followed by the effective token. ### What I've tried by myself I think I know what changes have to be made to the `.swagger.json` files to enable this feature. I've a locally development build version running (in a container) and as far as I can see it works, with: ```json { "swagger": "2.0", "info": { "title": "headscale/v1/headscale.proto", "version": "version not set" }, "securityDefinitions": { "Bearer": { "type": "apiKey", "name": "Authorization", "in": "header", "description": "Bearer token for authentication. Please type in 'Bearer' followed by a space and then the token." } }, "security": [ { "Bearer": ["read", "write"] } ], // followed by the rest of the generated .swagger.json file ``` in `/gen/openapiv2/headscale/v1/headscale.swagger.json`. But I do currently not know, what kind of changes I've to make, so that the next `make generate` command won't overwrite the files.
adam added the enhancementstale labels 2025-12-29 02:21:10 +01:00
adam closed this issue 2025-12-29 02:21:10 +01:00
adam commented 2025-12-29 02:21:11 +01:00
Author
Owner
Copy Link

@github-actions[bot] commented on GitHub (Apr 9, 2024):

This issue is stale because it has been open for 90 days with no activity.

@github-actions[bot] commented on GitHub (Apr 9, 2024): This issue is stale because it has been open for 90 days with no activity.
adam commented 2025-12-29 02:21:11 +01:00
Author
Owner
Copy Link

@github-actions[bot] commented on GitHub (Apr 16, 2024):

This issue was closed because it has been inactive for 14 days since being marked as stale.

@github-actions[bot] commented on GitHub (Apr 16, 2024): This issue was closed because it has been inactive for 14 days since being marked as stale.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
CLI
DERP
DNS
Nix
OIDC
SSH
bug
database
documentation
duplicate
enhancement
faq
good first issue
grants
help wanted
might-come
needs design doc
needs investigation
no-stale-bot
out of scope
performance
policy 📝
pull-request
Mirrored from GitHub Pull Request
 question
regression
routes
stale
tags
tailscale-feature-gap
well described ❤️
wontfix
No Label enhancement stale
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
adam
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: starred/headscale#611
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?