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 2024/04/19 11:29:52 UTC
(jackrabbit-oak) branch trunk updated: OAK-10772 : Broken links in authentication documentation
This is an automated email from the ASF dual-hosted git repository.
angela pushed a commit to branch trunk
in repository https://gitbox.apache.org/repos/asf/jackrabbit-oak.git
The following commit(s) were added to refs/heads/trunk by this push:
new f3296ec88d OAK-10772 : Broken links in authentication documentation
f3296ec88d is described below
commit f3296ec88d45467006e34a5ea37e3ccde0db7faf
Author: angela <an...@adobe.com>
AuthorDate: Fri Apr 19 13:29:39 2024 +0200
OAK-10772 : Broken links in authentication documentation
---
.../markdown/security/authentication/default.md | 68 ++++++++--------------
.../security/authentication/tokenmanagement.md | 8 ++-
2 files changed, 30 insertions(+), 46 deletions(-)
diff --git a/oak-doc/src/site/markdown/security/authentication/default.md b/oak-doc/src/site/markdown/security/authentication/default.md
index 44535fd05f..ef49e5432c 100644
--- a/oak-doc/src/site/markdown/security/authentication/default.md
+++ b/oak-doc/src/site/markdown/security/authentication/default.md
@@ -42,22 +42,14 @@ dedicated `LoginModule` implementation(s) for each scenario:
<a name="guest"></a>
#### Guest Login
-The proper way to obtain an guest session as of Oak is as specified by JSR 283:
+The proper way to obtain a guest session is specified by JSR 283:
- String wspName = null;
+ String wspName = null; // or any other workspace name if not login to the default workspace
Session anonymous = repository.login(new GuestCredentials(), wspName);
-As of Oak 1.0 `Repository#login()` and `Repository#login(null, wspName)` is no
-longer treated as guest login. This behavior of Jackrabbit-core is violating the
-specification, which defines that null-login should be used for those cases where
-the authentication process is handled outside of the repository (see [Pre-Authentication](preauthentication.html)).
+As of Oak 1.0 `Repository#login()` and `Repository#login(null, wspName)` is no longer treated as guest login. This behavior of Jackrabbit-core is violating the specification, which defines that null-login should be used for those cases where the authentication process is handled outside the repository (see [Pre-Authentication](preauthentication.html)).
-Similarly, any special treatment that Jackrabbit core applied for the guest (anonymous)
-user has been omitted altogether from the default [LoginModuleImpl]. In the default
-setup the built-in anonymous user will be created without any password. Therefore
-explicitly uid/pw login using the anonymous userId will no longer work. This behavior
-is now consistent with the default login of any other user which doesn't have a
-password set.
+Similarly, any special treatment that Jackrabbit core applied for the guest (anonymous) user has been omitted altogether from the default [LoginModuleImpl]. By default, the built-in anonymous user will be created without any password. Therefore, explicitly uid/pw login using the anonymous userId will no longer work. This behavior is now consistent with the default login of any other user which doesn't have a password set.
##### GuestLoginModule
@@ -132,7 +124,7 @@ This login module implementations behaves as follows:
The `LoginModuleImpl` uses a configured `Authentication`-implementation for
performing the login step. Which implementation to use is determined by the
[UserAuthenticationFactory] obtained by the given `UserConfiguration`. It is
-expected to provides an `Authentication` implementation if the given
+expected to provide an `Authentication` implementation if the given
`UserConfiguration` is accepted.
In case multiple implementations of the `UserAuthenticationFactory` are available,
@@ -145,11 +137,7 @@ See also section [user management](../user/default.html#pluggability).
<a name="impersonation"></a>
#### Impersonation Login
-Another flavor of the Oak authentication implementation is covered by
-`javax.jcr.Session#impersonate(Credentials)`, which allows to obtain an new
-`Session` for a user identified by the specified credentials. As of JSR 333
-this method can also be used in order to clone the existing session (i.e.
-self-impersonation of the user that holds the session.
+Another flavor of the Oak authentication implementation is covered by `javax.jcr.Session#impersonate(Credentials)`, which allows to obtain a new `Session` for a user identified by the specified credentials. As of JSR 333 this method can also be used in order to clone the existing session (i.e. self-impersonation of the user that holds the session).
With Oak 1.0 impersonation is implemented as follows:
@@ -195,30 +183,22 @@ Applications that wish to use a custom authentication setup need to ensure the
following steps in order to get JCR impersonation working:
- Respect `ImpersonationCredentials` in the authentication setup.
-- Identify the impersonated from `ImpersonationCredentials.getBaseCredentials`
- and verify if it can be authenticated.
-- Validate that the editing session is allowed to impersonate: The user associated
- with the editing session can be identified by the [AuthInfo] obtained from
- from `ImpersonationCredentials.getImpersonatorInfo()`.
+- Identify the impersonated from `ImpersonationCredentials.getBaseCredentials`and verify if it can be authenticated.
+- Validate that the editing session is allowed to impersonate: The user associated with the editing session can be identified by the [AuthInfo] obtained from `ImpersonationCredentials.getImpersonatorInfo()`.
<a name="token"></a>
#### Token Login
-See section [Token Authentication](tokenmanagement.html) for details
-regarding token based authentication.
+See section [Token Authentication](tokenmanagement.html) for details regarding token based authentication.
##### TokenLoginModule
-The `TokenLoginModule` is in charge of creating new login tokens and validate
-repository logins with `TokenCredentials`. The exact behavior of this login module is
-described in section [Token Authentication](tokenmanagement.html).
+The `TokenLoginModule` is in charge of creating new login tokens and validate repository logins with `TokenCredentials`. The exact behavior of this login module is described in section [Token Authentication](tokenmanagement.html).
<a name="pre_authenticated"></a>
#### Pre-Authenticated Login
-Oak provides two different mechanisms to create pre-authentication that doesn't
-involve the repositories internal authentication mechanism for credentials
-validation.
+Oak provides two different mechanisms to create pre-authentication that doesn't involve the repositories internal authentication mechanism for credentials validation.
- Pre-Authentication combined with Login Module Chain
- Pre-Authentication without Repository Involvement (aka `null` login)
@@ -235,16 +215,10 @@ systems (e.g. LDAP). For those setups that wish to combine initial authenticatio
against a third party system with repository functionality, Oak provides a default
implementation with extension points:
-- [External Authentication](externalloginmodule.html): Summary of
- the external authentication and details about the `ExternalLoginModule`.
-- [User and Group Synchronization](usersync.html): Details regarding
- user and group synchronization as well as a list of configuration options provided
- by the the default implementations present with Oak.
-- [Identity Management](identitymanagement.html): Further information regarding extenal identity management.
-- [LDAP Integration](ldap.html): How to make use of the `ExternalLoginModule`
- with the LDAP identity provider implementation. This combination is aimed to replace
- `com.day.crx.security.ldap.LDAPLoginModule`, which relies on Jackrabbit internals
- and will no longer work with Oak.
+- [External Authentication](externalloginmodule.html): Summary of the external authentication and details about the `ExternalLoginModule`.
+- [User and Group Synchronization](usersync.html): Details regarding user and group synchronization as well as a list of configuration options available with the default implementations present with Oak.
+- [Identity Management](identitymanagement.html): Further information regarding external identity management.
+- [LDAP Integration](ldap.html): How to make use of the `ExternalLoginModule` with the LDAP identity provider implementation. This combination is aimed to replace `com.day.crx.security.ldap.LDAPLoginModule`, which relies on Jackrabbit internals and will no longer work with Oak.
##### ExternalLoginModule
@@ -254,9 +228,7 @@ general mode of the external login module is to use the external system as authe
source and as a provider for users and groups that may also be synchronized into
the repository.
-This login module implementation requires an valid `SyncHandler` and `IdentityProvider`
-to be present. The detailed behavior of the `ExternalLoginModule` is described in
-section [External Authentication](externalloginmodule.html).
+This login module implementation requires a valid [SyncHandler] and [IdentityProvider] to be present. The detailed behavior of the `ExternalLoginModule` is described in section [External Authentication](externalloginmodule.html).
<!-- hidden references -->
[GuestCredentials]: https://s.apache.org/jcr-2.0-javadoc/javax/jcr/GuestCredentials.html
@@ -266,4 +238,10 @@ section [External Authentication](externalloginmodule.html).
[GuestLoginModule]: /oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authentication/GuestLoginModule.html
[LoginModuleImpl]: /oak/docs/apidocs/org/apache/jackrabbit/oak/security/authentication/user/LoginModuleImpl.html
[AbstractLoginModule]: /oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authentication/AbstractLoginModule.html
-[UserAuthenticationFactory]: /oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/user/UserAuthenticationFactory.html
\ No newline at end of file
+[UserAuthenticationFactory]: /oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/user/UserAuthenticationFactory.html
+[CallbackHandler]: /oak/docs/apidocs/javax/security/auth/callback/CallbackHandler.html
+[CredentialsCallback]: /oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authentication/callback/CredentialsCallback.html
+[ExternalLoginModule]: /oak/docs/apidocs/org/apache/jackrabbit/oak/security/authentication/external/ExternalLoginModule.html
+[UserConfiguration]: /oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/user/UserConfiguration.html
+[SyncHandler]: /oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authentication/external/SyncHandler.html
+[IdentityProvider]: /oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authentication/external/IdentityProvider.html
\ No newline at end of file
diff --git a/oak-doc/src/site/markdown/security/authentication/tokenmanagement.md b/oak-doc/src/site/markdown/security/authentication/tokenmanagement.md
index 1662542c17..5c911e4c30 100644
--- a/oak-doc/src/site/markdown/security/authentication/tokenmanagement.md
+++ b/oak-doc/src/site/markdown/security/authentication/tokenmanagement.md
@@ -62,10 +62,12 @@ authentication phases behave as follows:
##### Example JAAS Configuration
+ ```
jackrabbit.oak {
org.apache.jackrabbit.oak.security.authentication.token.TokenLoginModule sufficient;
org.apache.jackrabbit.oak.security.authentication.user.LoginModuleImpl required;
};
+ ```
<a name="api_extensions"></a>
@@ -113,6 +115,7 @@ token provider implementation:
- implement `TokenProvider` interface
- expose the custom provider by your custom `TokenConfiguration` service
- make the configuration available to the Oak repository.
+ - make sure the `TokenConfiguration` is listed as required service with the SecurityProvider (see also [Introduction](../introduction.html#configuration]))
##### Examples
@@ -159,4 +162,7 @@ token provider implementation:
[TokenProvider]: /oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authentication/token/TokenProvider.html
[TokenInfo]: /oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authentication/token/TokenInfo.html
[CompositeTokenConfiguration]: /oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authentication/token/CompositeTokenConfiguration.html
-[CompositeTokenProvider]: /oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authentication/token/CompositeTokenProvider.html
\ No newline at end of file
+[CompositeTokenProvider]: /oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authentication/token/CompositeTokenProvider.html
+[CredentialsCallback]: /oak/docs/apidocs/org/apache/jackrabbit/oak/security/authentication/callback/CredentialsCallback.html
+[CallbackHandler]: /oak/docs/apidocs/org/apache/jackrabbit/oak/security/authentication/callback/CallbackHandler.html
+[TokenConfiguration]: /oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authentication/token/TokenConfiguration.html
\ No newline at end of file