From c285d6137e9bc17f1c5c5caf8ac0daee5650fed0 Mon Sep 17 00:00:00 2001 From: Salvatore Coppola Date: Wed, 4 Oct 2023 16:41:37 +0200 Subject: [PATCH 1/7] Added new identity api section. --- .../references/rest-apis/rest-identity-api.md | 166 ++++++++++++++++++ mkdocs.yml | 1 + 2 files changed, 167 insertions(+) create mode 100644 docs/references/rest-apis/rest-identity-api.md diff --git a/docs/references/rest-apis/rest-identity-api.md b/docs/references/rest-apis/rest-identity-api.md new file mode 100644 index 00000000000..268d97e303f --- /dev/null +++ b/docs/references/rest-apis/rest-identity-api.md @@ -0,0 +1,166 @@ +# Rest Identity v1 API +!!! note + + This API can also be accessed via the RequestHandler with app-id: `ID-V1`. + + +The `IdentityRestService` APIs provides methods to manage the system identities. +Identities with `rest.identity` permissions can access these APIs. + +## POST methods + +#### Set users configuration + +- Description: This method allows to overwrite the users configuration in the system. +- Method: POST +- API PATH: `services/identity/v1/security-policy-fingerprint/reload` + +##### Request +```JSON +{ + "userConfig": [ + { + "userName": "admin", + "passwordChangeNeeded": false, + "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" + ] + }, + { + "userName": "kura.user.example", + "passwordChangeNeeded": true, + "permissions": [ + "rest.assets" + ] + } + ] +} +``` + +##### Responses + +- 200 OK status +- 500 Internal Server Error + +#### Create User + +- Description: This method allows to create a new user in the system +- Method: POST +- API PATH: `services/identity/v1/users/configs` + +##### Request +```JSON +{ + "userName": "example", +} +``` + +##### Responses + +- 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 +- API PATH: `services/identity/v1/defined-permissions` + +##### Responses + +- 200 OK status +```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" + ] +} +``` +- 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. +- API PATH: `services/identity/v1/users/configs` + +##### Responses + +- 200 OK status +```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" + ] + } + ] +} +``` +- 500 Internal Server Error + +## DELETE methods + +#### Delete User + +- Description: This method allows to delete an existing user in the system +- Method: DELETE +- API PATH: `services/identity/v1/users/configs` + +##### Request +```JSON +{ + "userName": "example", +} +``` + +##### Responses + +- 200 OK status +- 500 Internal Server Error diff --git a/mkdocs.yml b/mkdocs.yml index 6ef8bca3f9d..fe343327cc3 100644 --- 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 From d2d4bd8c0d1ec1d10e5f3573ff229824100165fe Mon Sep 17 00:00:00 2001 From: Salvatore Coppola Date: Wed, 4 Oct 2023 16:51:22 +0200 Subject: [PATCH 2/7] Specified the accepted parameter. --- docs/references/rest-apis/rest-identity-api.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/references/rest-apis/rest-identity-api.md b/docs/references/rest-apis/rest-identity-api.md index 268d97e303f..3aadb3a6fe0 100644 --- a/docs/references/rest-apis/rest-identity-api.md +++ b/docs/references/rest-apis/rest-identity-api.md @@ -60,7 +60,7 @@ Identities with `rest.identity` permissions can access these APIs. #### Create User -- Description: This method allows to create a new user in the system +- Description: This method allows to create a new user in the system. The only accepted parameter is the userName. - Method: POST - API PATH: `services/identity/v1/users/configs` @@ -149,7 +149,7 @@ Identities with `rest.identity` permissions can access these APIs. #### Delete User -- Description: This method allows to delete an existing user in the system +- Description: This method allows to delete an existing user in the system. The only accepted parameter is the userName. - Method: DELETE - API PATH: `services/identity/v1/users/configs` From 51e773e83a3be6cff3539d576499a0a5a1323955 Mon Sep 17 00:00:00 2001 From: Salvatore Coppola Date: Mon, 9 Oct 2023 14:42:08 +0200 Subject: [PATCH 3/7] Added Get User doc --- .../references/rest-apis/rest-identity-api.md | 28 ++++++++++++++++++- 1 file changed, 27 insertions(+), 1 deletion(-) diff --git a/docs/references/rest-apis/rest-identity-api.md b/docs/references/rest-apis/rest-identity-api.md index 3aadb3a6fe0..5fe01560ec5 100644 --- a/docs/references/rest-apis/rest-identity-api.md +++ b/docs/references/rest-apis/rest-identity-api.md @@ -67,7 +67,7 @@ Identities with `rest.identity` permissions can access these APIs. ##### Request ```JSON { - "userName": "example", + "userName": "example" } ``` @@ -78,6 +78,32 @@ Identities with `rest.identity` permissions can access these APIs. ## GET methods +#### Get User + +- Description: This method allows to get data about an user in the system. The only accepted parameter is the userName. +- Method: GET +- API PATH: `services/identity/v1/users/configs` + +##### Request +```JSON +{ + "userName": "example" +} +``` + +##### Responses +```JSON +{ + "userName": "kura.user.example", + "passwordAuthEnabled": false, + "passwordChangeNeeded": false, + "permissions": [] +} +```JSON + +- 200 OK status +- 500 Internal Server Error + #### Get defined permissions - Description: This method allows you to get the list of the permissions defined in the system From 1a9a5303c32ec9364d74db67822b5067cf86099b Mon Sep 17 00:00:00 2001 From: Salvatore Coppola Date: Mon, 9 Oct 2023 14:50:20 +0200 Subject: [PATCH 4/7] Fixed several path errors. --- docs/references/rest-apis/rest-identity-api.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/references/rest-apis/rest-identity-api.md b/docs/references/rest-apis/rest-identity-api.md index 5fe01560ec5..7ff3a89bdec 100644 --- a/docs/references/rest-apis/rest-identity-api.md +++ b/docs/references/rest-apis/rest-identity-api.md @@ -13,7 +13,7 @@ Identities with `rest.identity` permissions can access these APIs. - Description: This method allows to overwrite the users configuration in the system. - Method: POST -- API PATH: `services/identity/v1/security-policy-fingerprint/reload` +- API PATH: `services/identity/v1/users/configs` ##### Request ```JSON @@ -62,7 +62,7 @@ Identities with `rest.identity` permissions can access these APIs. - Description: This method allows to create a new user in the system. The only accepted parameter is the userName. - Method: POST -- API PATH: `services/identity/v1/users/configs` +- API PATH: `services/identity/v1/users` ##### Request ```JSON @@ -82,7 +82,7 @@ Identities with `rest.identity` permissions can access these APIs. - Description: This method allows to get data about an user in the system. The only accepted parameter is the userName. - Method: GET -- API PATH: `services/identity/v1/users/configs` +- API PATH: `services/identity/v1/users` ##### Request ```JSON @@ -99,7 +99,7 @@ Identities with `rest.identity` permissions can access these APIs. "passwordChangeNeeded": false, "permissions": [] } -```JSON +``` - 200 OK status - 500 Internal Server Error @@ -177,7 +177,7 @@ Identities with `rest.identity` permissions can access these APIs. - Description: This method allows to delete an existing user in the system. The only accepted parameter is the userName. - Method: DELETE -- API PATH: `services/identity/v1/users/configs` +- API PATH: `services/identity/v1/users` ##### Request ```JSON From 625b0391a9bb2fd2b7bbd125360e1cc6513c1545 Mon Sep 17 00:00:00 2001 From: Salvatore Coppola Date: Tue, 17 Oct 2023 12:52:13 +0200 Subject: [PATCH 5/7] doc updated. --- .../references/rest-apis/rest-identity-api.md | 118 ++++++++---------- 1 file changed, 53 insertions(+), 65 deletions(-) diff --git a/docs/references/rest-apis/rest-identity-api.md b/docs/references/rest-apis/rest-identity-api.md index 7ff3a89bdec..fd2103b5710 100644 --- a/docs/references/rest-apis/rest-identity-api.md +++ b/docs/references/rest-apis/rest-identity-api.md @@ -9,46 +9,21 @@ Identities with `rest.identity` permissions can access these APIs. ## POST methods -#### Set users configuration +#### Create User -- Description: This method allows to overwrite the users configuration in the system. +- Description: This method allows to create a new user in the system. - Method: POST -- API PATH: `services/identity/v1/users/configs` +- API PATH: `services/identity/v1/identities` ##### Request ```JSON { - "userConfig": [ - { - "userName": "admin", - "passwordChangeNeeded": false, - "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" - ] - }, - { - "userName": "kura.user.example", - "passwordChangeNeeded": true, - "permissions": [ - "rest.assets" - ] - } + "userName": "username", + "password": "password", + "passwordChangeNeeded": false, + "passwordAuthEnabled": true, + "permissions": [ + "rest.identity" ] } ``` @@ -58,43 +33,23 @@ Identities with `rest.identity` permissions can access these APIs. - 200 OK status - 500 Internal Server Error -#### Create User +#### Get User by Name -- Description: This method allows to create a new user in the system. The only accepted parameter is the userName. +- 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/users` - -##### Request -```JSON -{ - "userName": "example" -} -``` - -##### Responses - -- 200 OK status -- 500 Internal Server Error - -## GET methods - -#### Get User - -- Description: This method allows to get data about an user in the system. The only accepted parameter is the userName. -- Method: GET -- API PATH: `services/identity/v1/users` +- API PATH: `services/identity/v1/identities/byName` ##### Request ```JSON { - "userName": "example" + "userName": "username" } ``` ##### Responses ```JSON { - "userName": "kura.user.example", + "userName": "kura.user.username", "passwordAuthEnabled": false, "passwordChangeNeeded": false, "permissions": [] @@ -104,14 +59,16 @@ Identities with `rest.identity` permissions can access these APIs. - 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/defined-permissions` ##### Responses -- 200 OK status ```JSON { "permissions": [ @@ -135,16 +92,18 @@ Identities with `rest.identity` permissions can access these APIs. ] } ``` + +- 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. -- API PATH: `services/identity/v1/users/configs` +- Method: GET +- API PATH: `services/identity/v1/identities` ##### Responses -- 200 OK status ```JSON { "userConfig": [ @@ -169,20 +128,49 @@ Identities with `rest.identity` permissions can access these APIs. ] } ``` + +- 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 - 500 Internal Server Error ## DELETE methods #### Delete User -- Description: This method allows to delete an existing user in the system. The only accepted parameter is the userName. +- 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/users` +- API PATH: `services/identity/v1/identities` ##### Request ```JSON { - "userName": "example", + "userName": "username", } ``` From ef9a619d0968518f3877697fe42ededa36545413 Mon Sep 17 00:00:00 2001 From: Salvatore Coppola Date: Wed, 25 Oct 2023 11:13:03 +0200 Subject: [PATCH 6/7] Updated documentation. --- .../references/rest-apis/rest-identity-api.md | 22 +++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/docs/references/rest-apis/rest-identity-api.md b/docs/references/rest-apis/rest-identity-api.md index fd2103b5710..b38453d5ede 100644 --- a/docs/references/rest-apis/rest-identity-api.md +++ b/docs/references/rest-apis/rest-identity-api.md @@ -31,6 +31,7 @@ Identities with `rest.identity` permissions can access these APIs. ##### Responses - 200 OK status +- 400 Bad Request (Password strenght requirements not satisfied) - 500 Internal Server Error #### Get User by Name @@ -132,6 +133,26 @@ Identities with `rest.identity` permissions can access these APIs. - 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/password-requirements` + +##### Responses + +```JSON +{ + "passwordMinimumLength": 8, + "passwordRequireDigits": false, + "passwordRequireSpecialChars": false, + "passwordRequireBothCases": false +} +``` + +- 200 OK status +- 500 Internal Server Error + ## PUT methods #### Update User @@ -157,6 +178,7 @@ Identities with `rest.identity` permissions can access these APIs. ##### Responses - 200 OK status +- 400 Bad Request (Password strenght requirements not satisfied) - 500 Internal Server Error ## DELETE methods From 6710978148c3f99b11aa82de6760e592fe62cf48 Mon Sep 17 00:00:00 2001 From: nicolatimeus Date: Tue, 31 Oct 2023 09:40:09 +0100 Subject: [PATCH 7/7] Documented naming changes --- docs/references/rest-apis/rest-identity-api.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/docs/references/rest-apis/rest-identity-api.md b/docs/references/rest-apis/rest-identity-api.md index b38453d5ede..8d797d5a1d0 100644 --- a/docs/references/rest-apis/rest-identity-api.md +++ b/docs/references/rest-apis/rest-identity-api.md @@ -1,11 +1,11 @@ # Rest Identity v1 API !!! note - This API can also be accessed via the RequestHandler with app-id: `ID-V1`. + This API can also be accessed via the RequestHandler with app-id: `IDN-V1`. The `IdentityRestService` APIs provides methods to manage the system identities. -Identities with `rest.identity` permissions can access these APIs. +Unless otherwise specified, identities with `rest.identity` permissions can access these APIs. ## POST methods @@ -34,7 +34,7 @@ Identities with `rest.identity` permissions can access these APIs. - 400 Bad Request (Password strenght requirements not satisfied) - 500 Internal Server Error -#### Get User by Name +#### 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 @@ -66,7 +66,9 @@ Identities with `rest.identity` permissions can access these APIs. - Description: This method allows you to get the list of the permissions defined in the system - Method: GET -- API PATH: `services/identity/v1/defined-permissions` +- API PATH: `services/identity/v1/definedPermissions` + +No specific permission is required to access this resource. ##### Responses @@ -137,7 +139,9 @@ Identities with `rest.identity` permissions can access these APIs. - Description: This method allows you to get the password requirements. - Method: GET -- API PATH: `services/identity/v1/password-requirements` +- API PATH: `services/identity/v1/passwordRequirements` + +No specific permission is required to access this resource. ##### Responses