This is an automated email from the ASF dual-hosted git repository.
enorman pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/sling-site.git
The following commit(s) were added to refs/heads/master by this push:
new be13bfa SLING-10932 Describe principalName generation in the
documentation
be13bfa is described below
commit be13bfa879b151e4bed3692b844e68877b160951
Author: Eric Norman <[email protected]>
AuthorDate: Fri Nov 19 15:04:55 2021 -0800
SLING-10932 Describe principalName generation in the documentation
---
...ging-users-and-groups-jackrabbit-usermanager.md | 81 ++++++++++++++++++++--
1 file changed, 77 insertions(+), 4 deletions(-)
diff --git
a/src/main/jbake/content/documentation/bundles/managing-users-and-groups-jackrabbit-usermanager.md
b/src/main/jbake/content/documentation/bundles/managing-users-and-groups-jackrabbit-usermanager.md
index 781bcc9..880966d 100644
---
a/src/main/jbake/content/documentation/bundles/managing-users-and-groups-jackrabbit-usermanager.md
+++
b/src/main/jbake/content/documentation/bundles/managing-users-and-groups-jackrabbit-usermanager.md
@@ -50,13 +50,25 @@ If a non-existing user is requested a `404/NOT FOUND`
status is sent back.
To create a new user POST a request to `/system/userManager/user.create.<html
or json>`. The following parameters are available:
+One of these to resolve the user name:
+
+Parameter Name | Required | Since Version | Description
+--- | --- | --- | ---
+`:name` | no | | The value is the exact name to use
+`:name@ValueFrom` | no | 2.2.16 | The value is the name of another submitted
parameter whose value is the exact name to use
+`:nameHint` | no | 2.2.16 | The value is filtered, trimmed and made unique
+`:nameHint@ValueFrom` | no | 2.2.16 | The value is the name of another
submitted parameter whose value is filtered, trimmed and made unique
+`otherwise` | | 2.2.16 | Try the value of any server-side configured
"principalNameHints" parameter to treat as a hint that is filtered, trimmed and
made unique
+
+... and these ...
+
Parameter Name | Required | Description
--- | --- | ---
-`:name` | yes | The name of the new user
`pwd` | yes | The password of the new user
`pwdConfirm` | yes | The password of the new user (must be equal to the value
of `pwd`)
`<anyproperty>` | no | Additional parameters will be stored as node properties
in the JCR. Nested properties are supported since 2.2.6
([SLING-6747](https://issues.apache.org/jira/browse/SLING-6747)).
+
Responses:
Status Code | Description
@@ -192,10 +204,20 @@ If a non-existing group is requested a 404/NOT FOUND
status is sent back.
To create a new group POST a request to
`/system/userManager/group.create.<html or json>`. The following parameters are
available:
-
+One of these to resolve the group name:
+
+Parameter Name | Required | Since Version | Description
+--- | --- | --- | ---
+`:name` | no | | The value is the exact name to use
+`:name@ValueFrom` | no | 2.2.16 | The value is the name of another submitted
parameter whose value is the exact name to use
+`:nameHint` | no | 2.2.16 | The value is filtered, trimmed and made unique
+`:nameHint@ValueFrom` | no | 2.2.16 | The value is the name of another
submitted parameter whose value is filtered, trimmed and made unique
+`otherwise` | | 2.2.16 | Try the value of any server-side configured
"principalNameHints" parameter to treat as a hint that is filtered, trimmed and
made unique
+
+... and these ...
+
Parameter Name | Required | Description
--- | --- | ---
-`:name` | yes | The name of the new group
`<anyproperty>` | no | Additional parameters will be stored as node properties
in the JCR. Nested properties are supported since 2.2.6
([SLING-6747](https://issues.apache.org/jira/browse/SLING-6747)).
Responses:
@@ -307,4 +329,55 @@ Example:
if (privilegesInfo.canUpdateGroupMembers(currentSession, "GroupName"))
{
//TODO: draw your UI that allows the user to update the group
memebership here
}
- %>
\ No newline at end of file
+ %>
+
+
+## Generating principal names from a hint
+
+*Since Version 2.2.16*
+
+For use cases where the exact principalName value isn't critical, a unique
value can be auto-generated from some other hint. With a generated unique
princpalName, the end user doesn't have to keep retrying to find a value that
hasn't been used already.
+
+With the default behavior, the principalName value would be determined by
locating the first request parameter that is a match of one of the choices in
the following order:
+
+1\. **:name** - value is the exact name to use
+
+ curl -F:name=myuser -Fpwd=password -FpwdConfirm=password
http://localhost:8080/system/userManager/user.create.html
+
+2\. **:name@ValueFrom** - value is the name of another submitted parameter
whose value is the exact name to use
+
+ curl -F:name@ValueFrom=displayName -FdisplayName=myuser -Fpwd=password
-FpwdConfirm=password http://localhost:8080/system/userManager/user.create.html
+
+3\. **:nameHint** - value is filtered, trimmed and made unique
+
+ curl -F:nameHint=myuser -Fpwd=password -FpwdConfirm=password
http://localhost:8080/system/userManager/user.create.html
+
+4\. **:nameHint@ValueFrom** - value is the name of another submitted parameter
whose value is filtered, trimmed and made unique
+
+ curl -F:nameHint@ValueFrom=displayName -FdisplayName=myuser -Fpwd=password
-FpwdConfirm=password http://localhost:8080/system/userManager/user.create.html
+
+5\. **otherwise**, try the value of any server-side configured
"principalNameHints" parameters to treat as a hint that is filtered, trimmed
and made unique
+
+ curl -FdisplayName=myuser -Fpwd=password -FpwdConfirm=password
http://localhost:8080/system/userManager/user.create.html
+
+#### Customizing how principal names are generated from a hint
+
+*Since Version 2.2.16*
+
+The default implementation of *PrincipalNameGenerator* may be adjusted via
configuration to define a length limit and define which request parameters
should be considered as hint candidates.
+
+For example:
+
+ "org.apache.sling.jackrabbit.usermanager.PrincipalNameGenerator":{
+ "principalNameMaxLength": 50,
+ "principalNameHints": [
+ "displayName"
+ ]
+ }
+
+Additionally, the following service interfaces may be implemented by a custom
OSGi component in order to influence how a principalName is generated from a
hint. Whichever registered OSGi service that has the highest *service.ranking*
value will be used.
+
+1. **org.apache.sling.jackrabbit.usermanager.PrincipalNameFilter** - An
implementation of this service interface allows for filtering what characters
are allowed in a generated principal name
+2. **org.apache.sling.jackrabbit.usermanager.PrincipalNameGenerator** - An
implementation of this service interface allows to fully customize principal
name generation
+
+
