-
Notifications
You must be signed in to change notification settings - Fork 7
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
API Key Authentication #99
Open
kgarner7
wants to merge
8
commits into
main
Choose a base branch
from
api-key-auth
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
+222
−52
Open
Changes from all commits
Commits
Show all changes
8 commits
Select commit
Hold shift + click to select a range
bbe1a3e
initial proposal for api key authentication
kgarner7 81965c7
v1 rework
kgarner7 e95541a
Merge branch 'main' into api-key-auth
kgarner7 dcf5645
remove v2 uncommitted stuff
kgarner7 d690523
Merge branch 'api-key-auth' of github.com:opensubsonic/open-subsonic-…
kgarner7 c206a8f
errors, remove auth header
kgarner7 7bfe865
add tokenInfo endpoint, require u to be unset, minor cleanup for getL…
kgarner7 4b94bc6
fix copypasta
kgarner7 File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,62 @@ | ||
--- | ||
title: "tokenInfo" | ||
linkTitle: "tokenInfo [OS]" | ||
opensubsonic: | ||
- Addition | ||
- Extension | ||
categories: | ||
- System | ||
description: > | ||
Returns information about an API key | ||
--- | ||
|
||
**OpenSubsonic version**: [1](../../opensubsonic-versions) | ||
|
||
**OpenSubsonic extension name** `apiKeyAuthentication` (As returned by [`getOpenSubsonicExtensions`](../../endpoints/getopensubsonicextensions)) | ||
|
||
Returns data about an API key. | ||
|
||
`http://your-server/rest/tokenInfo` | ||
|
||
### Parameters | ||
|
||
None | ||
|
||
### Example | ||
|
||
{{< alert color="primary" >}} `http://your-server/rest/tokenInfo.view?apiKey=1234&v=1.13.0&c=AwesomeClientName&f=json` {{< /alert >}} | ||
|
||
|
||
### Result | ||
|
||
A [`subsonic-response`](../../responses/subsonic-response) element with a nested [`tokenInfo`](../../responses/tokenInfo/) on success, or error 44 on invalid token. | ||
|
||
{{< tabpane persistLang=false >}} | ||
{{< tab header="**Example**:" disabled=true />}} | ||
{{< tab header="OpenSubsonic JSON" lang="json">}} | ||
{ | ||
"subsonic-response": { | ||
"status": "ok", | ||
"version": "1.16.1", | ||
"type": "AwesomeServerName", | ||
"serverVersion": "0.1.3 (tag)", | ||
"openSubsonic": true, | ||
"tokenInfo": { | ||
"username": "token username" | ||
} | ||
} | ||
} | ||
{{< /tab >}} | ||
{{< tab header="OpenSubsonic XML" lang="xml">}} | ||
<subsonic-response status="ok" version="1.16.1" type="AwesomeServerName" serverVersion="0.1.3 (tag)" openSubsonic="true"> | ||
<tokenInfo username="token username"></tokenInfo> | ||
</subsonic-response> | ||
{{< /tab >}} | ||
{{< tab header="Subsonic" >}} | ||
Does not exist. | ||
{{< /tab >}} | ||
{{< /tabpane >}} | ||
|
||
| Field | Type | Req. | OpenS. | Details | | ||
| ----------- | ---------------------------------------- | ------- | ------- | ------------------------- | | ||
| `tokenInfo` | [`tokenInfo`](../../responses/tokeninfo) | **Yes** | **Yes** | Information about the token | |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,47 @@ | ||
--- | ||
title: "API Key Authentication" | ||
linkTitle: "API Key Authentication" | ||
OpenSubsonic: | ||
- Extension | ||
description: > | ||
Add a new authentication mechanism involving only an API key, and no | ||
--- | ||
|
||
**OpenSubsonic version**: [1](../../opensubsonic-versions) | ||
|
||
**OpenSubsonic extension name** `apiKeyAuthentication` (As returned by [`getOpenSubsonicExtensions`](../../endpoints/getopensubsonicextensions)) | ||
|
||
## Version 1 | ||
|
||
This extension requires changes to the semantics of authentication. | ||
Broadly, there are two general changes: | ||
|
||
1. **Required**: A new authentication mechanism: `apiKey` for query. | ||
2. Recommended: Deprecation of token/salt-based authentication. | ||
|
||
### API keys | ||
|
||
An API key is any authentication token generated by an OpenSubsonic server that can be used to authenticate. | ||
How this API key is generated by the server is implementation-specific: the server may provide a page where the user can configure one or more API keys, the server may automatically generate a API key, or any other variety of means. | ||
The format of the API key is not specified, but it **must** be of reasonable length to fit into a query parameter (less than 2048 characters URL-encoded). | ||
|
||
Servers which implement this extension **must** provide some mechanism for viewing active API key(s) and allow for revoking API keys. | ||
Note that these API keys **do not** expire; as long as they are not revoked by the user, they are assumed to be valid. | ||
|
||
#### Using a API key | ||
|
||
An API key is used as a query parameter `apiKey=<api key>`. | ||
When an API key is provided, the client **must not** provide a `u` parameter; passing in `u` **must** be treated as an error `43`. | ||
|
||
It is **recommended** that servers which provide API-key authentication deprecate salt/token-based authentication. | ||
|
||
If multiple conflicting authentication parameters are passed in, the server **must** return an error `43`, `Multiple conflicting authentication mechanisms provided` | ||
|
||
If a server deprecates salt-based authentication, it **must** return an error `41` (`Token authentication not supported for LDAP users.`). | ||
Similarly, if a server deprecates password-based authentication, it **must** return an error `42` (`Password authentication not supported. Use API keys`). | ||
|
||
In both cases, it is recommended that the server provide a meaningful url (configuration url, documentation, etc) in the `helpUrl` to help clients instruct their users how to obtain an API key. | ||
|
||
## New error codes | ||
|
||
This extension introduces three new errors `42`, `43` and `44`, and adds a new field `helpUrl`. See [error](../../responses/error) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,29 @@ | ||
--- | ||
title: "tokenInfo" | ||
linkTitle: "tokenInfo [OS]" | ||
opensubsonic: | ||
- Addition | ||
description: > | ||
Information about an API key | ||
--- | ||
|
||
{{< tabpane persistLang=false >}} | ||
{{< tab header="**Example**:" disabled=true />}} | ||
{{< tab header="OpenSubsonic JSON" lang="json">}} | ||
{ | ||
"tokenInfo": { | ||
"username": "token username" | ||
} | ||
} | ||
{{< /tab >}} | ||
{{< tab header="OpenSubsonic XML" lang="xml">}} | ||
<tokenInfo username="token username"></tokenInfo> | ||
{{< /tab >}} | ||
{{< tab header="Subsonic" >}} | ||
Does not exist. | ||
{{< /tab >}} | ||
{{< /tabpane >}} | ||
|
||
| Field | Type | Req. | OpenS. | Details | | ||
| ---------- | ------ | ------- | ------- | ------------------------------ | | ||
| `username` | string | **Yes** | **Yes** | Username associated with token | |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think the new apiKey version no more pass an username so it can't be a wrong user name.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The reason why I left username is if it's not required (and clients just specify api key), then there's no easy way to get the username. I would potentially be amenable to adding a new endpoint to turn a token into a username
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Ho you left username mandatory I missed that. Well then it makes sense but won't it be a problem if we extend to v2 with apiKey that can be limited to a media and don't want to leak the username in the urls ?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Sounds like a new endpoint to exchange token for username (and other things (?) for v2) then
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Sounds good, could return the scope too ;)
I think better to reuse the apiKey for media than adding again something else that would not bring anything more.