PWD reset docu changes, added example use case for REST PWD reset wit…

…h link to future example config
Evolveum · Feb 8, 2024 · 5100021 · 5100021
1 parent 80ad1ea
commit 5100021
Show file tree

Hide file tree

Showing 5 changed files with 159 additions and 14 deletions.
diff --git a/docs/interfaces/rest/operations/examples/get-user-unique-id.adoc b/docs/interfaces/rest/operations/examples/get-user-unique-id.adoc
@@ -29,10 +29,8 @@ curl --user administrator:5ecr3t -H "Accept: application/json" -X GET http://loc
 ----
 
 .Get Object in JSON format with the Raw option set to true
-[source,bash]
-----
+
 include::../examples/raw/get-user-administrator.adoc[]
-----
 
 == See Also
 

diff --git a/docs/interfaces/rest/operations/examples/raw/create-user-jack.adoc b/docs/interfaces/rest/operations/examples/raw/create-user-jack.adoc
@@ -1,14 +1,32 @@
 .Create a new User object in MidPoint with file data source
 [source,bash]
 ----
-curl --user administrator:5ecr3t -H "Content-Type: application/xml" -X POST http://localhost:8080/midpoint/ws/rest/users --data-binary @pathToMidpointGit\samples\rest\user-jack.xml -v
+# Authenticating with the credentials "administrator" and password "5ecr3t" on a localhost instance running on port 8080
+curl --user administrator:5ecr3t -H "Content-Type: application/json" -X POST http://localhost:8080/midpoint/ws/rest/users --data-binary @pathToMidpointGit\samples\rest\user-jack.json -v
 ----
 
-.*Show* data source example for *"Create a new User object in MidPoint"*
+.*Show* data source example for *"Create a new User object in MidPoint"* | link:https://raw.githubusercontent.com/Evolveum/midpoint-samples/master/samples/rest/user-jack.json[GitHub]
 [%collapsible]
 ====
-[source, xml]
+[source, json]
 ----
-include::https://raw.githubusercontent.com/Evolveum/midpoint-samples/master/samples/rest/user-jack.xml[]
+{
+  "user": {
+    "name": "jack",
+    "fullName": "Jack Sparrow",
+    "givenName": "Jack",
+    "familyName": "Sparrow"
+  }
+}
 ----
 ====
+
+The response is an HTTP 201 code in case of success *without* a response body.
+Also, the response contains a *Location Header* pointing to the location of the created
+user.
+
+.Example location header
+[source, bash]
+----
+ # Location: http://localhost:8080/midpoint/ws/rest/users/e4b0c81e-7fc7-462d-a92c-b3e0b10b8b49
+----
diff --git a/docs/interfaces/rest/operations/examples/raw/get-user-administrator.adoc b/docs/interfaces/rest/operations/examples/raw/get-user-administrator.adoc
@@ -1 +1,5 @@
+[source,bash]
+----
+# Authenticating with the credentials "administrator" and password "5ecr3t" on a localhost instance running on port 8080
 curl --user administrator:5ecr3t -H "Accept: application/json" -X GET http://localhost:8080/midpoint/ws/rest/users/00000000-0000-0000-0000-000000000002?options=raw
+----
diff --git a/docs/interfaces/rest/resource-types/users.adoc b/docs/interfaces/rest/resource-types/users.adoc
@@ -1,5 +1,5 @@
-= User Type Web Resource
-:page-nav-title: User Type Resource
+= User Type REST Objects
+:page-nav-title: User Type REST Objects
 :page-display-order: 200
 :page-toc: top
 
@@ -23,36 +23,71 @@ present in midPoint. This is apparent in the operations which are available for
 |===
 |.Create
 
+Object creation.
+
 include::../operations/examples/raw/create-user-jack.adoc[]
 
 - xref:/midpoint/reference/interfaces/rest/operations/create-op-rest/[Create Operation]
 
 |.Get
+
+Get operation for fetching a single specific object.
+
 .Get Default Administrator User with REST
-[source, http]
-----
+
 include::../operations/examples/raw/get-user-administrator.adoc[]
-----
+
 - xref:/midpoint/reference/interfaces/rest/operations/get-op-rest/[Get Operation]
+
 |.Search
+
+Search operation usable for fetching the full list of objects or a list based on filter.
+
+include::../operations/examples/raw/search-all-users.adoc[]
+
+include::../operations/examples/raw/search-all.adoc[]
+
 - xref:/midpoint/reference/interfaces/rest/operations/search-op-rest/[Search Operation]
+
 |.Modify
+
+Object Modification.
+
+include::../operations/examples/raw/modify-attr-user.adoc[]
+
+include::../operations/examples/raw/modify-attr.adoc[]
+
 - xref:/midpoint/reference/interfaces/rest/operations/modify-op-rest/[Modify Operation]
 |.Delete
+
+Object deletion.
+
+include::../operations/examples/raw/delete-user.adoc[]
+
 - xref:/midpoint/reference/interfaces/rest/operations/delete-op-rest/[Delete Operation]
 |.User specific
+
+A set of operations specific for the User REST objects. i.e. password reset and others.
+
+include::../operations/examples/raw/user-pwd-reset.adoc[]
+
 - xref:/midpoint/reference/interfaces/rest/operations/user-specific-op-rest/[User specific Operations]
 |.Generate and Validate
+
+Operations to generate or validate values, here we have an example of a simple password generate use-case.
+
+include::../operations/examples/raw/user-pwd-generate.adoc[]
+
 - xref:/midpoint/reference/interfaces/rest/operations/generate-and-validate-concrete-op-rest/[Generate and Validate Operations]
 |===
 == Common Use-case Examples
 
-1. xref:/midpoint/reference/interfaces/rest/operations/examples/create-object/[Create object]
+1. xref:/midpoint/reference/interfaces/rest/operations/examples/create-user/[Create User]
 2. xref:/midpoint/reference/interfaces/rest/operations/examples/get-user-unique-id/[Get user based on his unique identificator]
 3. xref:/midpoint/reference/interfaces/rest/operations/examples/get-user-self/[Get own profile information]
 
 
-== JSON Example
+== UserType JSON Example
 
 Example output of information regarding a specific user object. Metadata is usually a part of
 the output, yet it was removed for the purpose of the example.

diff --git a/docs/security/credentials/password-reset/index.adoc b/docs/security/credentials/password-reset/index.adoc
@@ -519,6 +519,96 @@ image::attribute-verification-module.png[Attribute verification module,width=400
 
 Full list of xref:/midpoint/reference/security/authentication/flexible-authentication/configuration/#module-configuration[supported authentication modules] are listed in documentation for xref:/midpoint/reference/security/authentication/flexible-authentication/configuration/[Flexible authentication].
 
+[#_pwd_reset_rest_api]
+== Password Reset with the REST API
+
+The password reset feature can be leveraged also in the case of the REST api. In this case
+the requesting user, i.e. service account accessing the REST api, know the password value
+which should be applied to the user object. In this case the security configuration does not
+need some of the previously mentioned configuration sections.
+
+.Default Security policy configuration with example "credentialsReset"
+[%collapsible]
+====
+[source,xml]
+----
+<securityPolicy xmlns="http://midpoint.evolveum.com/xml/ns/public/common/common-3"
+                oid="00000000-0000-0000-0000-000000000120">
+    <name>Default Security Policy</name>
+    <authentication>
+        <modules>
+            <loginForm>
+                <identifier>loginForm</identifier>
+            </loginForm>
+            <httpBasic>
+                <identifier>httpBasic</identifier>
+            </httpBasic>
+        </modules>
+        <sequence>
+            <identifier>admin-gui-default</identifier>
+            <displayName>Default gui sequence</displayName>
+            <channel>
+                <channelId>http://midpoint.evolveum.com/xml/ns/public/common/channels-3#user</channelId>
+                <default>true</default>
+                <urlSuffix>gui-default</urlSuffix>
+            </channel>
+            <module>
+                <identifier>loginForm</identifier>
+                <order>1</order>
+                <necessity>sufficient</necessity>
+            </module>
+        </sequence>
+        <sequence>
+            <identifier>rest-default</identifier>
+            <channel>
+                <channelId>http://midpoint.evolveum.com/xml/ns/public/common/channels-3#rest</channelId>
+                <default>true</default>
+                <urlSuffix>rest-default</urlSuffix>
+            </channel>
+            <module>
+                <identifier>httpBasic</identifier>
+                <order>1</order>
+                <necessity>sufficient</necessity>
+            </module>
+        </sequence>
+        <sequence>
+            <identifier>actuator-default</identifier>
+            <channel>
+                <channelId>http://midpoint.evolveum.com/xml/ns/public/common/channels-3#actuator</channelId>
+                <default>true</default>
+                <urlSuffix>actuator-default</urlSuffix>
+            </channel>
+            <module>
+                <identifier>httpBasic</identifier>
+                <order>1</order>
+                <necessity>sufficient</necessity>
+            </module>
+        </sequence>
+        <ignoredLocalPath>/actuator/health</ignoredLocalPath>
+    </authentication>
+    <credentials>
+        <password>
+            <minOccurs>0</minOccurs>
+            <lockoutMaxFailedAttempts>3</lockoutMaxFailedAttempts>
+            <lockoutFailedAttemptsDuration>PT3M</lockoutFailedAttemptsDuration>
+            <lockoutDuration>PT15M</lockoutDuration>
+            <valuePolicyRef oid="00000000-0000-0000-0000-000000000003" relation="org:default" type="c:ValuePolicyType"/>
+        </password>
+    </credentials>
+    <credentialsReset>
+        <identifier>passwordReset</identifier>
+        <newCredentialSource>
+            <userEntry/>
+        </newCredentialSource>
+        <forceChange>true</forceChange>
+    </credentialsReset>
+</securityPolicy>
+----
+====
+
+In this case the password value originates from the payload of the REST request which will be issued.
+for an example of the REST request please have a look at xref:/midpoint/reference/interfaces/rest/operations/examples/user-pwd-reset.adoc[this] page
+
 == Additional Configuration
 
 For some authentication modules, additional configuration might be necessary, such as: