API Key Authentication #99
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 support for synchronized lyrics, multiple languages, and retrieval by song ID | ||
| --- | ||
|
|
||
| **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.
Bad copy/paste?