From 2115d8d55e412f7f64aa8855ade7932d1d600cb2 Mon Sep 17 00:00:00 2001 From: Marvin Dostal Date: Sat, 17 Feb 2024 13:36:37 +0100 Subject: [PATCH] Rephrase the authentication section of the REST documentation (#2234) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Rephrase the authentication section of the REST documentation Resolves #2202 * Apply suggestions from code review Signed-off-by: stefan-hoehn * fix markdown issues Signed-off-by: Stefan Höhn * fix markdown issues Emphasis style Signed-off-by: Stefan Höhn --------- Signed-off-by: stefan-hoehn Signed-off-by: Stefan Höhn Co-authored-by: stefan-hoehn --- configuration/restdocs.md | 19 +++++++++++++++++-- 1 file changed, 17 insertions(+), 2 deletions(-) diff --git a/configuration/restdocs.md b/configuration/restdocs.md index a03f9cd33..8541a499f 100644 --- a/configuration/restdocs.md +++ b/configuration/restdocs.md @@ -67,8 +67,23 @@ Just log in with an admin user, navigate to `Developer Tools -> API Explorer` an ## Authentication -Starting with version 3, openHAB supports password protection for sensible contents such as parts of the semantic model. -To access this kind of information, the REST API provides the common mechanism [Basic authentication](https://en.wikipedia.org/wiki/Basic_access_authentication) and [OAuth authorization](https://en.wikipedia.org/wiki/OAuth). +Starting with version 3, openHAB supports password protection + +- Only _admins_ are able to access and change sensitive parts of the API. + e.g., creating/editing Things, Channels, Items or Scripts. +- _Users_ are able to interact with the end-user parts of the API. + e.g., looking at the state of and interacting with the existing Items. + +The setup process of openHAB includes creating an _admin_ account. +This (or any other account that is part of the _admin_ group) can be used for the authentication of the admin APIs. +All the _admin_ accounts are equal in terms of access. +The same is true for _user_ accounts; every _user_ account has equal access to the user APIs. + +By default anyone in the LAN will have _user_ access rights. +This behavior can be changed in the `Settings -> API Security -> Implicit User Role`. +If the `Implicit User Role` is disabled, all the APIs need authentication of an _admin_ or _user_ account. + +The REST API provides the common mechanism [Basic authentication](https://en.wikipedia.org/wiki/Basic_access_authentication) and [OAuth authorization](https://en.wikipedia.org/wiki/OAuth). Both mechanisms can be used out of the box by the most programming languages and frameworks, but with regard to the `curl` examples from above, there are two alternative ways of authenticating yourself: ### With username/password