Skip to content

Commit

Permalink
Merge branch 'fix/reauthenticate' into maintenance
Browse files Browse the repository at this point in the history
  • Loading branch information
foosel committed Jan 31, 2024
2 parents 152a608 + 4581bb3 commit 1729d16
Show file tree
Hide file tree
Showing 33 changed files with 1,140 additions and 363 deletions.
28 changes: 14 additions & 14 deletions docs/api/access.rst
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,7 @@ Add a new group

Will return a :ref:`group list response <sec-api-access-datamodel-groups-list>` on success.

Requires the ``SETTINGS`` permission.
Requires the ``SETTINGS`` permission and a recent credentials check.

:json key: The group's identifier
:json name: The user's name
Expand Down Expand Up @@ -101,7 +101,7 @@ Update a group

Will return a :ref:`group list response <sec-api-access-datamodel-groups-list>` on success.

Requires the ``SETTINGS`` permission.
Requires the ``SETTINGS`` permission and a recent credentials check.

:json description: A human readable description of the group
:json permissions: The permissions to assign to the group
Expand All @@ -122,7 +122,7 @@ Delete a group

Will return a :ref:`group list response <sec-api-access-datamodel-groups-list>` on success.

Requires the ``SETTINGS`` permission.
Requires the ``SETTINGS`` permission and a recent credentials check.

:status 200: No error

Expand Down Expand Up @@ -179,7 +179,7 @@ Add a new user

Returns a list of registered users on success, see :ref:`Retrieve a list of users <sec-api-access-users-list>`.

Requires the ``SETTINGS`` permission.
Requires the ``SETTINGS`` permission and a recent credentials check.

:json name: The user's name
:json password: The user's password
Expand All @@ -204,7 +204,7 @@ Update a user

Returns a list of registered users on success, see :ref:`Retrieve a list of users <sec-api-access-users-list>`.

Requires the ``SETTINGS`` permission.
Requires the ``SETTINGS`` permission and a recent credentials check.

:param username: Name of the user to update
:json admin: Whether to mark the user as admin (true) or not (false), can be left out (no change)
Expand All @@ -223,7 +223,7 @@ Delete a user

Returns a list of registered users on success, see :ref:`Retrieve a list of users <sec-api-access-users-list>`.

Requires the ``SETTINGS`` permission.
Requires the ``SETTINGS`` permission and a recent credentials check.

:param username: Name of the user to delete
:status 200: No error
Expand All @@ -242,7 +242,7 @@ Change a user's password
request body. Without the ``SETTINGS`` permission, an additional property ``current``
is also required to be set on the request body, containing the user's current password.

Requires the ``SETTINGS`` permission or to be logged in as the user. Note that ``current``
Requires the ``SETTINGS`` permission or to be logged in as the user, and a recent credentials check. Note that ``current``
will be evaluated even in presence of the ``SETTINGS`` permission, if set.

:param username: Name of the user to change the password for
Expand All @@ -252,7 +252,7 @@ Change a user's password
:status 400: If the request doesn't contain a ``password`` property, doesn't
contain a ``current`` property even though required, or the request
is otherwise invalid
:status 403: No admin rights, not logged in as the user or a current password
:status 403: No admin rights, not logged in as the user, no recent credentials check or a current password
mismatch
:status 404: The user is unknown

Expand Down Expand Up @@ -287,11 +287,11 @@ Update a user's settings
Expects a new settings JSON object to merge with the current settings as
request body.

Requires the ``SETTINGS`` permission or to be logged in as the user.
Requires the ``SETTINGS`` permission or to be logged in as the user, and a recent credentials check.

:param username: Name of the user to retrieve the settings for
:status 204: No error
:status 403: No admin rights and not logged in as the user
:status 403: No admin rights and not logged in as the user, or no recent credentials check
:status 404: The user is unknown

.. _sec-api-access-users-apikey-generate:
Expand All @@ -306,11 +306,11 @@ Regenerate a user's api key
Does not expect a body. Will return the generated API key as ``apikey``
property in the JSON object contained in the response body.

Requires the ``SETTINGS`` permission or to be logged in as the user.
Requires the ``SETTINGS`` permission or to be logged in as the user, and a recent credentials check.

:param username: Name of the user to retrieve the settings for
:status 200: No error
:status 403: No admin rights and not logged in as the user
:status 403: No admin rights and not logged in as the user, or no recent credentials check
:status 404: The user is unknown

.. _sec-api-access-users-apikey-delete:
Expand All @@ -322,11 +322,11 @@ Delete a user's api key
Deletes a user's personal API key.

Requires the ``SETTINGS`` permission or to be logged in as the user.
Requires the ``SETTINGS`` permission or to be logged in as the user, and a recent credentials check.

:param username: Name of the user to retrieve the settings for
:status 204: No error
:status 403: No admin rights and not logged in as the user
:status 403: No admin rights and not logged in as the user, or no recent credentials check
:status 404: The user is unknown

.. _sec-api-access-datamodel:
Expand Down
105 changes: 90 additions & 15 deletions docs/bundledplugins/appkeys.rst
Original file line number Diff line number Diff line change
Expand Up @@ -291,6 +291,8 @@ Decide on existing request

Returns an HTTP :http:statuscode:`204` on success.

Requires the ``PLUGIN_APPKEYS_GRANT`` permissions and a recent credentials check.

:json decision: boolean value to indicate whether to confirm (``True``) or deny (``False``) access
:status 204: success

Expand All @@ -303,13 +305,17 @@ Fetch list of existing application keys
Fetches a list of existing application keys and pending requests registered in the system for the current user.

If the additional optional parameter ``all`` is provided and the user has administrator rights, fetches a list
If the additional optional parameter ``all`` is provided and the user has the ``PLUGIN_APPKEYS_ADMIN`` permission, fetches a list
of *all** application keys and pending requests registered in the system for any user.

If the additional optional parameter ``app`` is provided, only the key for the specified application identifier and the
current user will be returned. A user with the ``PLUGIN_APPKEYS_ADMIN``permission may also specify the ``user`` parameter
to fetch the key for the specified application identifier and a different user.

Returns a :http:statuscode:`200` with a :ref:`List response <sec-bundledplugins-appkey-datamodel-listreponse>` in the
body upon success.

:query all: Fetch all application keys and pending requests from all users. Requires administrator rights.
:query all: Fetch all application keys and pending requests from all users. Requires the ``PLUGIN_APPKEYS_ADMIN`` permission.

.. _sec-bundledplugins-appkeys-api-issuecommand:

Expand All @@ -323,18 +329,27 @@ Issue an application key command

revoke
Revokes an existing application key. Must belong to the user issuing the command, unless the user has admin rights
in which case they make revoke any application key in the system. Expects the key in question as parameter ``key``.
in which case they make revoke any application key in the system. Expects the key in question identified by the
associated application identifier provided in the ``app`` parameter. Keys for other users but the current one can
be revoked by admins with the additional ``user`` parameter to specify the user id.

generate
Generates a new application key for the user, using the application identifier provided as parameter ``app``.
Generates a new application key for the user, using the application identifier provided as parameter ``app``. Keys
for other users but the current one can be generated by admins with the additional ``user`` parameter to specify
the user id.

Upon success, a status code of :http:statuscode:`204` and an empty body is returned.

Requires user rights.
Requires user rights and a fresh credentials check.

.. deprecated:: 1.10.0

Revoking a key by supplying the key itself has been deprecated as of OctoPrint 1.10.0. Use ``app`` and optionally
``user`` instead.

**Example revoke request**

Revokes the (fictional) key ``aabbccddeeff112233445566``.
Revokes the key associated with app id ``test`` for the current user.

.. sourcecode:: http

Expand All @@ -345,7 +360,28 @@ Issue an application key command

{
"command": "revoke",
"key": "aabbccddeeff112233445566"
"app": "test"
}

.. sourcecode:: http

HTTP/1.1 204 No Content

**Example revoke request by an admin for a different user**

Revokes the key associated with the app id ``test`` for user ``user``.

.. sourcecode:: http

POST /api/plugin/appkeys HTTP/1.1
Host: example.com
Content-Type: application/json
X-Api-Key: abcdef...

{
"command": "revoke",
"app": "test",
"user": "user"
}

.. sourcecode:: http
Expand All @@ -365,17 +401,28 @@ Issue an application key command

{
"command": "generate",
"key": "My awesome application 1.0"
"app": "My awesome application 1.0"
}

.. sourcecode:: http

HTTP/1.1 204 No Content
HTTP/1.1 200 OK
Content-Type: application/json

{
"app_id": "My awesome application 1.0",
"user_id": "me",
"api_key": "abcdef1234567890"
}

:json string command: The command to issue, either ``revoke`` or ``generate``
:json string key: ``revoke`` command: The key to revoke
:json string app: ``generate`` command: Application identifier for which to generate a key
:statuscode 204: No error
:json string app: ``revoke`` & ``generate`` commands: The application identifier of the key to revoke or generate.
:json string user: ``revoke`` & ``generate`` commands: The user name for which to revoke or generated a key associated with the provided
app id. If not provided, the current user's name will be used.
:json string key: ``revoke`` command: The key to revoke. Revoking by providing the key itself has been deprecated
as of OctoPrint 1.10.0. Use ``app`` and optionally ``user`` instead.
:statuscode 200: Key generation successful
:statuscode 204: No error during key revocation
:statuscode 400: Invalid or missing parameter

.. _sec-bundledplugins-appkey-datamodel:
Expand Down Expand Up @@ -543,6 +590,18 @@ Pending list entry
JavaScript Client Library
-------------------------

.. js:function:: OctoPrintClient.plugins.appkeys.getKey(app, user, opts)

Retrieves the key information the given ``app`` and optional other ``user``. The key must belong to the current user, or the current user must
have the ``PLUGIN_APPKEYS_ADMIN`` permission.

See :ref:`Fetch list of existing application keys <sec-bundledplugins-appkeys-api-fetchlist>` for more details.

:param string app: Application identifier
:param string user: Optional user identifier
:param object opts: Additional options for the request
:returns Promise: A `jQuery Promise <http://api.jquery.com/Types/#Promise>`_ for the request's response

.. js:function:: OctoPrintClient.plugins.appkeys.getKeys(opts)

Retrieves registered keys and pending requests for the current user.
Expand All @@ -556,7 +615,7 @@ JavaScript Client Library

Retrieves registered keys and pending requests for all users.

Needs administrator rights.
Needs the ``PLUGIN_APPKEYS_ADMIN`` permission.

See :ref:`Fetch list of existing application keys <sec-bundledplugins-appkeys-api-fetchlist>` for more details.

Expand All @@ -575,15 +634,31 @@ JavaScript Client Library

.. js:function:: OctoPrintClient.plugins.appkeys.revokeKey(key, opts)

Revokes the given ``key``. The key must belong to the current user, or the current user must have administrator
rights.
Revokes the given ``key``. The key must belong to the current user, or the current user must
have the ``PLUGIN_APPKEYS_ADMIN`` permission.

See :ref:`Issue an application key command <sec-bundledplugins-appkeys-api-issuecommand>` for details.

.. deprecated:: 1.10.0

``revokeKey`` has been deprecated. Use ``revokeKeyForApp`` instead.

:param string key: Key to revoke
:param object opts: Additional options for the request
:returns Promise: A `jQuery Promise <http://api.jquery.com/Types/#Promise>`_ for the request's response

.. js:function:: OctoPrintClient.plugins.appkeys.revokeKeyForApp(app, user, opts)

Revokes the key for the given ``app`` and optional other ``user``. The key must belong to the current user, or the current user must
have the ``PLUGIN_APPKEYS_ADMIN`` permission.

See :ref:`Issue an application key command <sec-bundledplugins-appkeys-api-issuecommand>` for details.

:param string app: Application identifier
:param string user: Optional user identifier
:param object opts: Additional options for the request
:returns Promise: A `jQuery Promise <http://api.jquery.com/Types/#Promise>`_ for the request's response

.. js:function:: OctoPrintClient.plugins.appkeys.decide(token, decision, opts)

Decides on an existing authorization request.
Expand Down
4 changes: 4 additions & 0 deletions docs/configuration/config_yaml.rst
Original file line number Diff line number Diff line change
Expand Up @@ -72,6 +72,10 @@ Use the following settings to enable access control:
# If a remote user is not found, add them. Use this only if all users from the remote system can use OctoPrint.
addRemoteUsers: false
# Default timeout after which to require reauthentication by a user for dangerous changes, in minutes.
# Defaults to 5 minutes. Set to 0 to disable reauthentication requirements (SECURITY IMPACT!).
defaultReauthenticationTimeout: 5
.. _sec-configuration-config_yaml-api:

API
Expand Down
2 changes: 1 addition & 1 deletion src/octoprint/access/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ def auth_log(message):


login_mechanisms = login_mechanism_lut = {
"http": "credentials",
"password": "credentials",
"autologin": "autologin",
"remember_me": "Remember Me cookie",
"basic_auth": "Basic Authorization header",
Expand Down
Loading

0 comments on commit 1729d16

Please sign in to comment.