You are viewing a plain text version of this content. The canonical link for it is here.
Posted to oak-commits@jackrabbit.apache.org by an...@apache.org on 2014/11/27 10:38:03 UTC
svn commit: r1642055 - in
/jackrabbit/oak/trunk/oak-doc/src/site/markdown/security: authentication.md
user.md user/authorizablenodename.md
Author: angela
Date: Thu Nov 27 09:38:03 2014
New Revision: 1642055
URL: http://svn.apache.org/r1642055
Log:
OAK-2138 : documentation
Added:
jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/user/authorizablenodename.md
Modified:
jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/authentication.md
jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/user.md
Modified: jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/authentication.md
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/authentication.md?rev=1642055&r1=1642054&r2=1642055&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/authentication.md (original)
+++ jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/authentication.md Thu Nov 27 09:38:03 2014
@@ -447,7 +447,7 @@ There also exists a utility class that a
The default security setup as present with Oak 1.0 is able to provide custom
implementation on various levels:
-1. The complete authentiction setup can be changed by plugging a different
+1. The complete authentication setup can be changed by plugging a different
`AuthenticationConfiguration` implementations. In OSGi-base setup this is
achieved by making the configuration a service. In a non-OSGi-base setup the
custom configuration must be exposed by the `SecurityProvider` implementation.
Modified: jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/user.md
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/user.md?rev=1642055&r1=1642054&r2=1642055&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/user.md (original)
+++ jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/user.md Thu Nov 27 09:38:03 2014
@@ -21,7 +21,7 @@ User Management
### JCR User Management
JCR itself doesn't come with a dedicated user management API. The only method
-related and ultemately used for user management tasks is `Session.getUserID()`.
+related and ultimately used for user management tasks is `Session.getUserID()`.
Therefore an API for user and group management has been defined as part of the
extensions present with Jackrabbit API.
@@ -199,20 +199,10 @@ details and examples.
#### Node Name Generation
The default user management implementation with Oak 1.0 allows to specify how
-the name of a new authorizable node is being generated. As in Jackrabbit 2.x
-the ID is used as name-hint by default. In order to prevent exposing identifier
-related information in the path of the authorizable node, it it's desirable to
-change this default behavior by pluggin a custom implementation of the
-`AuthorizableNodeName` interface.
-
-- `AuthorizableNodeName` : Defines the generation of the authorizable node names
- in case the user management implementation stores user information in the repository.
-
-In the default implementation the corresponding configuration parameter is
-`PARAM_AUTHORIZABLE_NODE_NAME`. The default name generator can be replace
-by installing an OSGi service that implementats the `AuthorizableNodeName` interface.
-In a non-OSGi setup the user configuration must be initialized with configuration
-parameters that provide the custom generator implementation.
+the name of a new authorizable node is being generated.
+
+See section [Authorizable Node Name](user/authorizablenodename.html) for further
+details and examples.
#### Password Expiry and Force Initial Password Change
@@ -294,44 +284,14 @@ implementation on various levels:
- `AuthorizableActionProvider`: Defines the authorizable actions, see [Authorizable Actions](user/authorizableaction.html).
- `AuthorizableNodeName`: Defines the generation of the authorizable node names
in case the user management implementation stores user information in the repository.
-
-##### Examples
-
-###### Example AuthorizableNodeName
-
-In an OSGi-based setup it's sufficient to make the service available to the repository
-in order to enable this custom node name generator.
-
- @Component
- @Service(value = {AuthorizableNodeName.class})
- /**
- * Custom implementation of the {@code AuthorizableNodeName} interface
- * that uses a uuid as authorizable node name.
- */
- final class UUIDNodeName implements AuthorizableNodeName {
-
- @Override
- @Nonnull
- public String generateNodeName(@Nonnull String authorizableId) {
- return UUID.randomUUID().toString();
- }
- }
-
-In a non-OSGi setup this custom name generator can be plugged by making it available
-to the user configuration as follows:
-
- Map<String, Object> userParams = new HashMap<String, Object>();
- userParams.put(UserConstants.PARAM_AUTHORIZABLE_NODE_NAME, new UUIDNodeName());
- ConfigurationParameters config = ConfigurationParameters.of(ImmutableMap.of(UserConfiguration.NAME, ConfigurationParameters.of(userParams)));
- SecurityProvider securityProvider = new SecurityProviderImpl(config));
- Repository repo = new Jcr(new Oak()).with(securityProvider).createRepository();
-
+ See [Authorizable Node Name Generation](user/authorizablenodename.html).
### Further Reading
- [Differences wrt Jackrabbit 2.x](user/differences.html)
- [Group Membership](user/membership.html)
- [Authorizable Actions](user/authorizableaction.html)
+- [Authorizable Node Name](user/authorizablenodename.html)
- [Searching Users and Groups](user/query.html)
- [Password Expiry and Force Initial Password Change](user/expiry.html)
Added: jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/user/authorizablenodename.md
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/user/authorizablenodename.md?rev=1642055&view=auto
==============================================================================
--- jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/user/authorizablenodename.md (added)
+++ jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/user/authorizablenodename.md Thu Nov 27 09:38:03 2014
@@ -0,0 +1,109 @@
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+ -->
+
+Authorizable Node Name Generation
+--------------------------------------------------------------------------------
+
+### Overview
+
+Oak 1.0 comes with a extension to the Jackrabbit user management API that allows
+to change the way how the name of an authorizable node is being generated.
+
+As in Jackrabbit 2.x the target ID is used as name-hint by default. In order to
+prevent exposing identifier related information in the path of the authorizable
+node, it it's desirable to change this default behavior by plugging a different
+implementation of the `AuthorizableNodeName` interface.
+
+- `AuthorizableNodeName` : Defines the generation of the authorizable node names
+ in case the user management implementation stores user information in the repository.
+
+In the default implementation the corresponding configuration parameter is
+`PARAM_AUTHORIZABLE_NODE_NAME`. The default name generator can be replace
+by installing an OSGi service that implementations the `AuthorizableNodeName` interface.
+In a non-OSGi setup the user configuration must be initialized with configuration
+parameters that provide the custom generator implementation.
+
+### AuthorizableNodeName API
+
+The following public interfaces are provided by Oak in the package `org.apache.jackrabbit.oak.spi.security.user`:
+
+- [AuthorizableNodeName]
+
+The `AuthorizableNodeName` interface itself defines single method that allows
+to generate a valid JCR name for a given authorizable ID.
+
+#### Changes wrt Jackrabbit 2.x
+
+- The generation of the node name is a configuration option of the default
+ user management implementation.
+- In an OSGi-based setup the default can be changed at runtime by plugging a
+ different implementation. E.g. the `RandomAuthorizableNodeName` component
+ can easily be enabled by providing the required configuration.
+
+#### Built-in AuthorizableAction Implementations
+
+Oak 1.0 provides the following base implementations:
+
+- `AuthorizableNodeName.Default`: Backwards compatible implementation that
+ uses the authorizable ID as name hint.
+- `RandomAuthorizableNodeName`: Generating a random JCR name (see [RandomAuthorizableNodeName].java).
+
+### Pluggability
+
+The default security setup as present with Oak 1.0 can be run with a custom
+`RandomAuthorizableNodeName` implementations.
+
+In an OSGi setup the following steps are required in order to add a different
+implementation:
+
+- implement `AuthorizableNodeName` interface.
+- make the implementation an OSGi service and make it available to the Oak repository.
+
+##### Examples
+
+###### Example AuthorizableNodeName
+
+In an OSGi-based setup it's sufficient to make the service available to the repository
+in order to enable this custom node name generator.
+
+ @Component
+ @Service(value = {AuthorizableNodeName.class})
+ /**
+ * Custom implementation of the {@code AuthorizableNodeName} interface
+ * that uses a uuid as authorizable node name.
+ */
+ final class UUIDNodeName implements AuthorizableNodeName {
+
+ @Override
+ @Nonnull
+ public String generateNodeName(@Nonnull String authorizableId) {
+ return UUID.randomUUID().toString();
+ }
+ }
+
+In a non-OSGi setup this custom name generator can be plugged by making it available
+to the user configuration as follows:
+
+ Map<String, Object> userParams = new HashMap<String, Object>();
+ userParams.put(UserConstants.PARAM_AUTHORIZABLE_NODE_NAME, new UUIDNodeName());
+ ConfigurationParameters config = ConfigurationParameters.of(ImmutableMap.of(UserConfiguration.NAME, ConfigurationParameters.of(userParams)));
+ SecurityProvider securityProvider = new SecurityProviderImpl(config));
+ Repository repo = new Jcr(new Oak()).with(securityProvider).createRepository();
+
+<!-- hidden references -->
+[AuthorizableNodeName]: /oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/user/AuthorizableNodeName.html
+[RandomAuthorizableNodeName]: /oak/docs/apidocs/org/apache/jackrabbit/oak/security/user/RandomAuthorizableNodeName.html