docs: Added REST Identity API section (#4880)

* Added new identity api section. * Specified the accepted parameter. * Added Get User doc * Fixed several path errors. * doc updated. * Updated documentation. * Documented naming changes --------- Co-authored-by: nicolatimeus <[email protected]>
eclipse-kura · Oct 31, 2023 · 9a1b03e · 9a1b03e
1 parent ad901d3
commit 9a1b03e
Show file tree

Hide file tree

Showing 2 changed files with 207 additions and 0 deletions.
diff --git a/docs/references/rest-apis/rest-identity-api.md b/docs/references/rest-apis/rest-identity-api.md
@@ -0,0 +1,206 @@
+# Rest Identity v1 API
+!!! note
+
+    This API can also be accessed via the RequestHandler with app-id: `IDN-V1`.
+
+
+The `IdentityRestService` APIs provides methods to manage the system identities.
+Unless otherwise specified, identities with `rest.identity` permissions can access these APIs.
+
+## POST methods
+
+#### Create User
+
+- Description: This method allows to create a new user in the system.
+- Method: POST
+- API PATH: `services/identity/v1/identities`
+
+##### Request
+```JSON
+{
+    "userName": "username",
+    "password": "password",
+    "passwordChangeNeeded": false,
+    "passwordAuthEnabled": true,
+    "permissions": [
+        "rest.identity"
+    ]
+}
+```
+
+##### Responses
+
+- 200 OK status
+- 400 Bad Request (Password strenght requirements not satisfied)
+- 500 Internal Server Error
+
+#### Get User by Name
+
+- Description: This method allows to get data about an user in the system. The only considered field is the userName.
+- Method: POST
+- API PATH: `services/identity/v1/identities/byName`
+
+##### Request
+```JSON
+{
+    "userName": "username"
+}
+```
+
+##### Responses
+```JSON
+{
+    "userName": "kura.user.username",
+    "passwordAuthEnabled": false,
+    "passwordChangeNeeded": false,
+    "permissions": []
+}
+```
+
+- 200 OK status
+- 500 Internal Server Error
+
+## GET methods
+
+#### Get defined permissions
+
+- Description: This method allows you to get the list of the permissions defined in the system
+- Method: GET
+- API PATH: `services/identity/v1/definedPermissions`
+
+No specific permission is required to access this resource.
+
+##### Responses
+
+```JSON
+{
+    "permissions": [
+        "rest.command",
+        "rest.inventory",
+        "rest.configuration",
+        "rest.tamper.detection",
+        "rest.security",
+        "kura.cloud.connection.admin",
+        "rest.position",
+        "kura.packages.admin",
+        "kura.device",
+        "rest.wires.admin",
+        "kura.admin",
+        "rest.keystores",
+        "rest.assets",
+        "rest.system",
+        "kura.maintenance",
+        "kura.wires.admin",
+        "rest.identity"
+    ]
+}
+```
+
+- 200 OK status
+- 500 Internal Server Error
+
+#### Get users configuration
+
+- Description: This method allows you to get the list of the users and their configuration on the system.
+- Method: GET
+- API PATH: `services/identity/v1/identities`
+
+##### Responses
+
+```JSON
+{
+    "userConfig": [
+        {
+            "userName": "admin",
+            "passwordAuthEnabled": true,
+            "passwordChangeNeeded": false,
+            "permissions": [
+                "kura.admin"
+            ]
+        },
+        {
+            "userName": "appadmin",
+            "passwordAuthEnabled": true,
+            "passwordChangeNeeded": true,
+            "permissions": [
+                "kura.cloud.connection.admin",
+                "kura.packages.admin",
+                "kura.wires.admin"
+            ]
+        }
+    ]
+}
+```
+
+- 200 OK status
+- 500 Internal Server Error
+
+#### Get password requirements
+
+- Description: This method allows you to get the password requirements.
+- Method: GET
+- API PATH: `services/identity/v1/passwordRequirements`
+
+No specific permission is required to access this resource.
+
+##### Responses
+
+```JSON
+{
+    "passwordMinimumLength": 8,
+    "passwordRequireDigits": false,
+    "passwordRequireSpecialChars": false,
+    "passwordRequireBothCases": false
+}
+```
+
+- 200 OK status
+- 500 Internal Server Error
+
+## PUT methods
+
+#### Update User
+
+- Description: This method allows to update an existing user in the system.
+- Method: PUT
+- API PATH: `services/identity/v1/identities`
+
+##### Request
+
+```JSON
+{
+    "userName": "username",
+    "password": "password",
+    "passwordChangeNeeded": false,
+    "passwordAuthEnabled": true,
+    "permissions": [
+        "rest.identity"
+    ]
+}
+```
+
+##### Responses
+
+- 200 OK status
+- 400 Bad Request (Password strenght requirements not satisfied)
+- 500 Internal Server Error
+
+## DELETE methods
+
+#### Delete User
+
+- Description: This method allows to delete an existing user in the system. The only considered field is the userName.
+- Method: DELETE
+- API PATH: `services/identity/v1/identities`
+
+##### Request
+```JSON
+{
+    "userName": "username",
+}
+```
+
+##### Responses
+
+- 200 OK status
+- 500 Internal Server Error
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -151,6 +151,7 @@ nav:
       - REST-APIs:
         - Command: references/rest-apis/rest-command-api.md
         - Deploy: references/rest-apis/rest-deploy-api.md
+        - Identity: references/rest-apis/rest-identity-api.md
         - Inventory: references/rest-apis/rest-inventory-api.md
         - Position: references/rest-apis/rest-position-api.md
         - Security: references/rest-apis/rest-security-api.md