Reply-To: dev@sling.apache.org Delivered-To: mailing list commits@sling.apache.org Received: (qmail 63791 invoked by uid 99); 19 Jun 2017 12:41:10 -0000 Received: from git1-us-west.apache.org (HELO git1-us-west.apache.org) (140.211.11.23) by apache.org (qpsmtpd/0.29) with ESMTP; Mon, 19 Jun 2017 12:41:10 +0000 Received: by git1-us-west.apache.org (ASF Mail Server at git1-us-west.apache.org, from userid 33) id 77250F4A60; Mon, 19 Jun 2017 12:41:08 +0000 (UTC) Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit From: bdelacretaz@apache.org To: commits@sling.apache.org Date: Mon, 19 Jun 2017 12:41:44 -0000 Message-Id: <6d98bc900c484d949e5ffc0ea9ea59c9@git.apache.org> In-Reply-To: <97c7fddf11964b93a267d6db6ca03cdb@git.apache.org> References: <97c7fddf11964b93a267d6db6ca03cdb@git.apache.org> X-Mailer: ASF-Git Admin Mailer Subject: [38/53] sling-site git commit: asf-site branch created for published content archived-at: Mon, 19 Jun 2017 12:41:26 -0000 http://git-wip-us.apache.org/repos/asf/sling-site/blob/a6129baf/documentation/the-sling-engine/authentication/authentication-actors.html ---------------------------------------------------------------------- diff --git a/documentation/the-sling-engine/authentication/authentication-actors.html b/documentation/the-sling-engine/authentication/authentication-actors.html new file mode 100644 index 0000000..cec16a4 --- /dev/null +++ b/documentation/the-sling-engine/authentication/authentication-actors.html @@ -0,0 +1,73 @@ + + + + Apache Sling on JBake + + +

+ +

Authentication - Actors

Excerpt: The authentication process involves a number of actors contributing to the concepts, the API and the particular implementations.

The authentication process involves a number of actors contributing to the concepts, the API and the particular implementations.

OSGi Http Service Specification

The main support for authentication is defined by the OSGi Http Service specification. This specification defines how an OSGi application can register servlets and resources to build web applications. As part of the servlet and/or resource registration a HttpContext may be provided, which allows for additional support.

The main method of interest to the authentication process is the handleSecurity method. This is called by the OSGi Http Service implementation before the registered servlet is called. Its intent is to authenticate the request and to provide authentication information for the request object: the authentication type and the remote user name.

The Sling Auth Core bundle provides the AuthenticationSupport service which may be used to the implement the HttpContext.handleSecurity method.

Sling Engine

The Sling Engine implements the main entry point into the Sling system by means of the SlingMainServlet. This servlet is registered with the OSGi Http Service and provides a custom HttpContext whose handleSecurity method is implemented by the AuthenticationSupport service.

When the request hits the service method of the Sling Main Servlet, the resource resolver provided by the AuthenticationSupport service is retrieved from the request attributes and used as the resource resolver for the request.

That's all there is for the Sling Engine to do with respect to authentication.

Sling Auth Core

The support for authenticating client requests is implemented in the Sling Auth Core bundle. As such this bundle provides three areas of support

AuthenticationHandler service interface. This is implemented by services providing functionality to extract credentials from HTTP requests.
Authenticator service interface. This is implemented by the SlingAuthenticator class in the Sling Auth Core bundle and provides applications with entry points to login and logout.
AuthenticationSupport service interface. This is implemented by the SlingAuthenticator class in the Sling Auth Core bundle and allows applications registering with the OSGi HTTP Service to make use of the Sling authentication infrastructure.

JCR Repository

The actual process of logging into the repository and provided a Session is implementation dependent. In the case of Jackrabbit extensibility is provided by configuration of the Jackrabbit repository by means of an interface and two helper classes:

LoginModule -- The interface to be implemented to provide login processing plugins
AbstractLoginModule -- A an abstract base class implementation of the LoginModule interface.
DefaultLoginModule -- The default implementation of the AbstractLoginModule provided by Jackabbit. This login module takes SimpleCredentials and uses the repository to lookup the users, validate the credentials and providing the Principal representing the user towards the repository.

The Sling Jackrabbit Embedded Repository bundle provides additional plugin interfaces to extend the login process dynamically using OSGi services. To this avail the bundle configures a LoginModule with the provided default Jackrabbit configuration supporting these plugins:

LoginModulePlugin -- The main service interface. Plugins must implement this interface to be able to extend the login process. See for example the Sling OpenID authentication handler, which implements this interface to support OpenID authentication.
AuthenticationPlugin -- Helper interface for the LoginModulePlugin.

Sling Applications

Sling Applications requiring authenticated requests should not care about how authentication is implemented. To support such functionality the Authenticator service is provided with two methods:

+
login -- allows the application to ensure requests are authenticated. This involves selecting an AuthenticationHandler to request credentials for authentication.
+
logout -- allows the application to forget about any authentication. This involves selecting an AuthenticationHandler to forget about credentials in the request.

Sling Applications should never directly use any knowledge of any authentication handler or directly call into an authentication handler. This will certainly break the application and cause unexpected behaviour.

+If you want to know whether a request is authenticated or not, you can inspect the result of the HttpServletRequest.getAuthType method: If this method returns null the request is not authenticated. +

+ + +

+ + http://git-wip-us.apache.org/repos/asf/sling-site/blob/a6129baf/documentation/the-sling-engine/authentication/authentication-authenticationhandler.html ---------------------------------------------------------------------- diff --git a/documentation/the-sling-engine/authentication/authentication-authenticationhandler.html b/documentation/the-sling-engine/authentication/authentication-authenticationhandler.html new file mode 100644 index 0000000..8ab1b7d --- /dev/null +++ b/documentation/the-sling-engine/authentication/authentication-authenticationhandler.html @@ -0,0 +1,107 @@ + + + + Apache Sling on JBake + + +

+ +

Authentication - AuthenticationHandler

Excerpt: The AuthenticationHandler interface defines the service API which may be implemented by authentication handlers registered as OSGi services.

The AuthenticationHandler interface defines the service API which may be implemented by authentication handlers registered as OSGi services.

AuthenticationHandler services have a single required service registration property which is used to identify requests to which the AuthenticationHandler service is applicable:

+ + + + + + + + + + + + + + + + + +

Property Description

path One or more (array or vector) string values indicating the request URLs to which the AuthenticationHandler is applicable.

authtype The authentication type implemented by this handler. This is a string value property and should be the same as will be used as the authentication type of the AuthenticationInfo object provided by the extractCredentials method. If this property is set, the requestCredentials method of the authentication handler is only called if the sling:authRequestLogin request parameter is either not set or is set to the same value as the authtype of the handler. This property is optional. If not set, the requestCredentials method is always called regardless of the value of the sling:authRequestLogin request parameter.

Property	Description
`path`	One or more (array or vector) string values indicating the request URLs to which the `AuthenticationHandler` is applicable.
`authtype`	The authentication type implemented by this handler. This is a string value property and should be the same as will be used as the authentication type of the `AuthenticationInfo` object provided by the `extractCredentials` method. If this property is set, the `requestCredentials` method of the authentication handler is only called if the `sling:authRequestLogin` request parameter is either not set or is set to the same value as the `authtype` of the handler. This property is optional. If not set, the `requestCredentials` method is always called regardless of the value of the `sling:authRequestLogin` request parameter.

Each path may be an absolute URL, an URL with just the host/port and path or just a plain absolute path:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

URL part	Scheme	Host/Port	Path
Absolute URL	must match	must match	request URL path is prefixed with the path
Host/Port with Path	ignored	must match	request URL path is prefixed with the path
Path	ignored	ignored	request URL path is prefixed with the path

When looking for an AuthenticationHandler the authentication handler is selected whose path is the longest match on the request URL. If the service is registered with Scheme and Host/Port, these must exactly match for the service to be eligible. If multiple AuthenticationHandler services are registered with the same length matching path, the handler with the higher service ranking is selected[^ranking].

[^ranking]: Service ranking is defined by the OSGi Core Specification as follows: If multiple qualifying service interfaces exist, a service with the highest service.ranking number, or when equal to the lowest service.id, determines which service object is returned by the Framework.

The value of path service registration property value triggering the call to any of the AuthenticationHandler methods is available as the path request attribute (for the time of the method call only). If the service is registered with multiple path values, the value of the path request attribute may be used to implement specific handling.

Implementations provided by Sling

Sample implementations

HTTP Basic Authentication Handler

extractCredentials -- Get user name and password from the Authorization HTTP header
requestCredentials -- Send a 401/UNAUTHORIZED status with WWW-Authenticate response header setting the Realm
dropCredentials -- Send a 401/UNAUTHORIZED status with WWW-Authenticate response header setting the Realm

Interestingly the dropCredentials method is implemented in the same way as the requestCredentials method. The reason for this is, that HTTP Basic authentication does not have a notion of login and logout. Rather the request is accompanied with an Authorization header or not. The contents of this header is usually cached by the client browser. So logout is actually simulated by sending a 401/UNAUTHORIZED status thus causing the client browser to clear the cache and ask for user name and password.

Form Based Authentication Handler

extractCredentials -- Get user name and password with the help of a special cookie (note, that of course the cookie should not contain this data, but refer to it in an internal store of the authentication handler). If the cookie is not set, check for specific login parameters to setup the cookie.
requestCredentials -- Send the login form for the user to provide the login parameters.
dropCredentials -- Clear the authentication cookie and internal store.

///Footnotes Go Here///

+ + +

+ + http://git-wip-us.apache.org/repos/asf/sling-site/blob/a6129baf/documentation/the-sling-engine/authentication/authentication-authenticationhandler/form-based-authenticationhandler.html ---------------------------------------------------------------------- diff --git a/documentation/the-sling-engine/authentication/authentication-authenticationhandler/form-based-authenticationhandler.html b/documentation/the-sling-engine/authentication/authentication-authenticationhandler/form-based-authenticationhandler.html new file mode 100644 index 0000000..64092aa --- /dev/null +++ b/documentation/the-sling-engine/authentication/authentication-authenticationhandler/form-based-authenticationhandler.html @@ -0,0 +1,180 @@ + + + + Apache Sling on JBake + + +

+ +

Form Based AuthenticationHandler

[TOC]

The Form Based AuthenticationHandler has two authentication phases: The first phase is presenting a login form to the user and passing the entered user name and password to the server. The second phase is storing successful authentication in a Cookie or an HTTP Session.

The implementation of the Form Based Authentication Handler follows the guidelines of the Servlet API 2.4 specification for Form Based Authentication in section SRV.12.5.3. Specifically the following requirements are implemented:

For the initial form submission, the request URL must end with /j_security_check and the user name and password names must be j_username and j_password, resp.
The authentication type as returned by HttpServletRequest.getAuthType() is set to HttpServletRequest.FORM_AUTH.

The Form Based Authentication Handler is maintained in the Sling SVN

AuthenticationHandler implementation

extractCredentials -- Prepares credentials for the form entered data or from the Cookie or HTTP Session attribute. Returns null if neither data is provided in the request
requestCredentials -- Redirects the client (browser) to the login form
dropCredentials -- Remove the Cookie or remove the HTTP Session attribute

AuthenticationFeedbackHandler implementation

authenticationFailed -- Remove the Cookie or remove the HTTP Session attribute
authenticationSucceeded -- Set (or update) the Cookie or HTTP Session attribute

Phase 1: Form Submission

The login form submitted in phase 1 to validate the user name and password must be provided in an HTTP POST request to an URL whose last segment is j_security_check. The request is ignored as a form submission if either the method is not POST or the last segment is no j_security_check.

The form is rendered by redirecting the client to the URL indicated by the form.login.form configuration parameter. This redirection request may accompanyied by the following parameters:

resource -- The resource to which the user should be redirected after successful login. This request parameter should be submitted back to the server as the resource parameter.
j_reason -- This parameter indicates the reason for rendering the login form. If this parameter is set, it is set to INVALID_CREDENTIALS indicating a previous form submission presented invalid username and password or TIMEOUT indicating a login session has timed out. The login form servlet/script can present the user with an appropriate message.

The Form Based Authentication Handlers supports the following request parameters submitted by the HTML form:

j_username -- Name of the user to authenticate
j_password -- Password to authenticate the user
j_validate -- Flag indicating whether to just validate the credentials
resource -- The location to go to on successful login
sling.auth.redirect -- The location to redirect to on successful login

The j_username and j_password parameters are used to create a JCR SimpleCredentials object to log into the JCR Repository.

The j_validate parameter may be used to implement login form submission using AJAX. If this parameter is set to true (case-insensitive) the credentials are used to login and after success or failure to return a status code:

+ + + + + + + + + + + + + + + + + +

Status	Description
`200 OK`	Authentication succeeded; credentials are valid for login; the Cookie or HTTP Session attribute is now set
`403 FORBIDDEN`	Authentication failed; credentials are invalid for login; the Cookie or HTTP Session attribute is not set (if it was set, it is now cleared)

If the j_validate parameter is not set or is set to any value other than true, the request processing depends on authentication success or failure:

+ + + + + + + + + + + + + + + + + +

Authentication	Description
Success	Client is redirected to the authenticated resource; the Cookie or HTTP Session attribute is now set.
Failure	The request is redirected to the login form again; the Cookie or HTTP Session attribute is not set (if it was set, it is now cleared)

The resource and sling.auth.redirect parameters provide similar functionality but with differing historical backgrounds. The resource parameter is based on the resource request attribute which is set by the login servlet to indicate the original target resource the client desired when it was forced to authenticate. The sling.auth.redirect parameter can be used by clients (applications like cURL or plain HTML forms) to request being redirected after successful login. If both parameters are set, the sling.auth.redirect parameter takes precedence.

The Form Based Authentication Handler contains a default form servlet and HTML form template.

Phase 2: Authenticated Requests

After the successful authentication of the user in phase 1, the authentication state is stored in a Cookie or an HTTP Session. The stored value is a security token with the following contents:

HmacSHA1(securetoken, @)@@

The securetoken and securetokennumber are related in that an table of secure tokens is maintained where the securetoken is an entry in the table and the securetokennumber is the index in of the token in the table.

The secure tokens are refreshed periodically causing the authentication state stored in the Cookie or the HTTP Session to be updated peridocally. This periodic update has two advantages:

Login sessions time out after some period of inactivity: If a request is handled for an authentication state whose expiry time has passed, the request is considered unauthenticated.
If a Cookie would be stolen or an HTTP Session be hijacked, the authentication state expires within a reasonable amount of time to try to prevent stealing the authentication.

The authentication state may be transmitted with a Cookie which is configured as follows:

Cookie Path -- Set to the servlet context path
Domain -- See below
Age -- Set to -1 to indicate a session Cookie
Secure -- Set to the value returned by the ServletRequest.isSecure() method

If the authentication state is kept in an HTTP Session the setup of the session ID cookie is maintained by the servlet container and is outside of the control of the Form Based AuthenticationHandler.

Configuration

The Form Based Authentication Handler is configured with configuration provided by the OSGi Configuration Admin Service using the org.apache.sling.formauth.FormAuthenticationHandler service PID.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Parameter	Default	Description
`form.login.form`	`/system/sling/form/login`	The URL (without any context path prefix) to redirect the client to to present the login form.
`form.auth.storage`	`cookie`	The type of storage used to provide the authentication state. Valid values are `cookie` and `session`. The default value also applies if any setting other than the supported values is configured.
`form.auth.name`	`sling.formauth`	The name of the Cookie or HTTP Session attribute providing the authentication state.
`form.auth.timeout`	`30`	The number of minutes after which a login session times out. This value is used as the expiry time set in the authentication data.
`form.credentials.name`	`sling.formauth`	The name of the `SimpleCredentials` attribute used to provide the authentication data to the `LoginModulePlugin`.
`form.token.file`	`cookie-tokens.bin`	The name of the file used to persist the security tokens.
`form.default.cookie.domain`		The domain on which cookies will be set, unless overridden in the `AuthenticationInfo` object.

Note: The form.token.file parameter currently refers to a file stored in the file system. If the path is a relative path, the file is either stored in the Authentication Handler bundle private data area or -- if not possible -- below the location indicated by the sling.home framework property or -- if sling.home is not set -- the current working directory. In the future this file may be store in the JCR Repository to support clustering scenarios.

Security Considerations

Form Based Authentication has some limitations in terms of security:

User name and password are transmitted in plain text in the initial form submission.
The Cookie used to provide the authentication state or the HTTP Session ID may be stolen.

To prevent eavesdroppers from sniffing the credentials or stealing the Cookie a secure transport layer should be used such as TLS/SSL, VPN or IPSec.

+ + +

+ + http://git-wip-us.apache.org/repos/asf/sling-site/blob/a6129baf/documentation/the-sling-engine/authentication/authentication-authenticationhandler/openid-authenticationhandler.html ---------------------------------------------------------------------- diff --git a/documentation/the-sling-engine/authentication/authentication-authenticationhandler/openid-authenticationhandler.html b/documentation/the-sling-engine/authentication/authentication-authenticationhandler/openid-authenticationhandler.html new file mode 100644 index 0000000..936b49d --- /dev/null +++ b/documentation/the-sling-engine/authentication/authentication-authenticationhandler/openid-authenticationhandler.html @@ -0,0 +1,141 @@ + + + + Apache Sling on JBake + + +

+ +

OpenID AuthenticationHandler

[TOC]

The OpenID Authentication Handler supports authentication of request users using the OpenID authentication protocol. If the user has successfully authenticated with his OpenID provider a signed OpenID identity is further used to identify the user.

Since generally an OpenID identity is an URL and URLs may not be used as JCR user names, an association mechanism is used by the OpenID authentication handler to associate an OpenID identity with an existing JCR user: The OpenID identity URL is set as the value of a JCR user property. When a user authenticates with his OpenID identity the matching user searched for by looking for a match in this property.

NOTE: This association currently only works with Jackrabbit (or Jackrabbit based repositories) because user management is not part of the JCR 2 specification and the OpenID authentication handler uses the Jackrabbit UserManager to find users by a user property value.

The OpenID Authentication Handler is maintained in the Sling SVN

Credentials Extraction

Theoretically each request with the openid_identifier request parameter set may initiate an OpenID authentication process which involves resolving the OpenID provider for the identifier and subsequently authentication with the provider authorizing the Sling instance to use the OpenID identity.

This initiation, though, is not possible if the request already contains a valid and validated OpenID identifier either set as a request attribute or set in the HTTP Session or the OpenID cookie. In these situations, the current association of a client with an OpenID identity must first be removed by logging out, e.g. by requesting /system/sling/logout.html which causes the current OpenID user data to be removed by either removing it from the HTTP Session or by clearing the OpenID cookie.

Phase 1: Form Submission

Requesting an OpenID identifier is initiated by the Sling Authenticator deciding, that authentication is actually required to process a request and the OpenID Authentication Handler being selected to request credentials with.

In this case the OpenID authenticator causes a form to be rendered by redirecting the client to the URL indicated by the form.login.form configuration parameter. This redirection request may accompanied by the following parameters:

+ + + + + + + + + + + + + + + + + + + + + +

Request Parameter	Description
`resource`	The location to which the user initially requested access and that caused the `requestCredentials` method to be called. This may not be set (or be set to an empty string).
`j_reason`	The reason why an earlier attempt at authentication with the OpenID authentication handler failed. This request parameter is only set if the same named request attribute has been set by the `extractCredentials` or the `authenticationFailed` method. The value of the parameter is the name of one of the `OpenIDFailure` constants.
`j_openid_identity`	The OpenID identity which could not successfully be associated with an existing JCR user. This request parameter is only set if the `authenticationFailed` method has been called due to inability to associate an existing and validated OpenID identity with an existing JCR user.

The OpenID Authentication handlers supports the following request parameters submitted by the HTML form:

openid_identifier -- OpenID Claimed Identifier. This may be any actual OpenID identity URL or the URL of OpenID Provider such as https://www.google.com/accounts/o8/id, https://me.yahoo.com, or https://www.myopenid.com.
sling:authRequestLogin -- This request parameter is recommended to be set with a hidden field to the value OpenID to ensure the request is handled by the OpenID Authentication Handler.
resource -- The resource request parameter should be sent back to ensure the user is finally redirected to requested target resource after successful authentication. If this request parameter is not set, or is set to an empty string, it is assumed to be the request context root path.

The OpenID Authentication Handler provides a default login form registered at /system/sling/openid/login.

Configuration

The OpenID AuthenticationHandler is configured with configuration provided by the OSGi Configuration Admin Service using the org.apache.sling.openidauth.OpenIdAuthenticationHandler service PID.

+ + + + + + + + +

Parameter	Default	Description

| path | -- | Repository path for which this authentication handler should be used by Sling. If this is empty, the authentication handler will be disabled. | | openid.login.form | /system/sling/openid/login | This should provide a way to capture the user's OpenID identifier. This is not the OpenID Provider's login page, however, it does not have to be a local URL. If it is a local Sling URL, it must be accessible by the anonymous user. The user is HTTP Redirect'ed to this URL. This page should POST back the user's OpenID identifier (as named by the "OpenID identifier form field" property) to the originally requested URL set in the "resource" request parameter. | | openid.login.identifier | openid_identifier | The name of the form parameter that provides the user's OpenID identifier. By convention this is openid_identifier. Only change this if you have a very good reason to do so. | | openid.extern al.url.prefix | -- | The prefix of URLs generated for the ReturnTo and TrustRoot properties of the OpenID request to the OpenID provider. Thus this URL prefix should bring back the authenticated user to this Sling instance. Configuring this property is usually necessary when running Sling behind a proxy (like Apache) since proxy mapping is not performed on the OpenID ReturnTo and TrustRoot URLs as they are sent to the OpenID Provider as form parameters. If this property is empty, the URLs are generated using the hostname found in the original request.| | openid.use.cookie | true | Whether to use a regular Cookie or an HTTP Session to cache the OpenID authentication details. By default a regular cookie is used to prevent use of HTTP Sessions. | | openid.cookie.domain | -- | Domain of cookie used to persist authentication. This defaults to the host name of the Sling server but may be set to a different value to sh are the cookie amongst a server farm or if the server is running behind a proxy. Only used if 'Use Cookie' is checked. | | openid.cookie.name | sling.openid | Name of cookie used to persist authentication. Only used if 'Use Cookie' is checked. | | openid.cookie.secret.key | secret | Secret key used to create a signature of the cookie value to prevent tampering. Only used if 'Use Cookie' is true. | | openid.user.attr | openid.user | Name of the JCR SimpleCredentials attribute to to set with the OpenID User data. This attribute is used by the OpenID LoginModule to validate the OpenID user authentication data. | | openid.property.identity | openid.identity | The name of the JCR User attribute listing one or more OpenID Identity URLs with which a user is associated. The property may be a multi- or single-valued. To resolve a JCR user ID from an OpenID identity a user is searched who l ists the identity in this property. |

AuthenticationHandler implementation

extractCredentials

To extract authentication information from the request, the Sling OpenID Authentication handler considers the following information in order:

The OpenID credentials cookie or OpenID User data in the HTTP Session (depending on the openid.use.cookie configuration)
Otherwise the openid_identifier request parameter (or a different request parameter depending on the openid.login.identifier configuration)

If the OpenID credentials already exist in the request, they are validated and returned if valid

If the existing credentials fail to validate, authentication failure is assumed and the credentials are removed from the request, either by clearing the OpenID cookie or by removing the OpenID User data from the HTTP Session.

If no OpenID credentials are found in the request, the request parameter is considered and if set is used to resolve the actual OpenID identity of the user. This involves redirecting the client to the OpenID provider resolved from the OpenID identifier supplied.

If the supplied OpenID identifier fails to resolve to an OpenID provider or if the identifier fails to be resolved to a validated OpenID identity, authentication fails.

requestCredentials

If the sling:authRequestLogin parameter is set to a value other than OpenID this method immediately returns false.

If the parameter is not set or is set to OpenID this method continues with first invalidating any cached OpenID credentials (same as dropCredentials does) and then redirecting the client to the login form configured with the openid.login.form configuration property. The redirect is provided with up to three request parameters:

+ + + + + + + + + + + + + + + + + + + + + +

Request Parameter	Description
`resource`	The location to which the user initially requested access and that caused the `requestCredentials` method to be called.
`j_reason`	The reason why an earlier attempt at authentication with the OpenID authentication handler failed. This request parameter is only set if the same named request attribute has been set by the `extractCredentials` or the `authenticationFailed` method. The value of the parameter is the name of one of the `OpenIDFailure` constants.
`j_openid_identity`	The OpenID identity which could not successfully be associated with an existing JCR user. This request parameter is only set if the `authenticationFailed` method has been called due to inability to associate an existing and validated OpenID identity with an existing JCR user.

dropCredentials

Invalidates the OpenID identity currently stored with the request. This means to either remove the OpenID cookie or to remove the OpenID information from the HTTP Session. This method does not write to the response (except setting the Set-Cookie header to remove the OpenID cookie if required) and does not commit the response.

AuthenticationFeedbackHandler implementation

authenticationFailed

This method is called, if the Credentials provided by the Authentication Handler could not be validated by the Jackrabbit authentication infrastructure. One cause may be that the integration with Jackrabbit has not been completed (see Integration with Jackrabbit below). Another, more probably cause, is that the validated OpenID identifier cannot be associated with an existing JCR user.

The OpenID Authentication Handler implementation of the authenticationFailed method sets the j_reason request attribute to OpenIDFailure.REPOSITORY and sets the j_openid_identity request attribute to the OpenID identity of the authenticated user.

A login form provider may wish to act upon this situation and provide a login form to the user to allow to his OpenID identity with an existing JCR user.

In addition, the current OpenID identity is invalidated thus the cached OpenID information is removed from the HTTP Session or the OpenID cookie is cleaned. This will allow the user to present a different OpenID identifier to retry or it will require the OpenID identity to be revalidated with the OpenID provider if the identity is associated with a JCR user.

authenticationSucceeded

The OpenID Authentication Handler implementation of the authenticationSucceeded method just calls the DefaultAuthenticationFeedbackHandler.handleRedirect method to redirect the user to the initially requested location.

Integration with Jackrabbit

The OpenID authentication handler can be integrated in two ways into the Jackrabbit authentication mechanism which is based on JAAS LoginModule. One integration is by means of a LoginModulePlugin which plugs into the extensible LoginModule architecture supported by the Sling Jackrabbit Embedded Repository bundle.

The other integration option is the trusted_credentials_attribute mechanism supported by the Jackrabbit DefaultLoginModule. By setting the trusted_credentials_attribute parameter of the Jackrabbit DefaultLoginModule and the openid.user.attr configuration property of the OpenID Authentication Handler to the same value, the existence of an attribute of that name in the SimpleCredentials instance provided to the Repository.login method signals pre-authenticated credentials, which need not be further checked by the DefaultLoginModule.

Security Considerations

OpenIDAuthentication has some limitations in terms of security:

User name and password are transmitted in plain text in the initial form submission.
The Cookie used to provide the authentication state or the HTTP Session ID may be stolen.
When using the trusted_credentials_attribute mechanism, any intruder knowing the attribute name may log into the repository as any existing JCR user. The better option is to be based on the LoginModulePlugin mechanism.

To prevent eavesdroppers from sniffing the credentials or stealing the Cookie a secure transport layer should be used such as TLS/SSL, VPN or IPSec.

+ + +

+ + http://git-wip-us.apache.org/repos/asf/sling-site/blob/a6129baf/documentation/the-sling-engine/authentication/authentication-framework.html ---------------------------------------------------------------------- diff --git a/documentation/the-sling-engine/authentication/authentication-framework.html b/documentation/the-sling-engine/authentication/authentication-framework.html new file mode 100644 index 0000000..e5d3ea1 --- /dev/null +++ b/documentation/the-sling-engine/authentication/authentication-framework.html @@ -0,0 +1,184 @@ + + + + Apache Sling on JBake + + +

+ +

Authentication - Framework

Excerpt: The core piece of functionality with respect to authentication in Sling is contained in the Sling Auth Core bundle. This bundle provides the API for Sling and Sling applications to make use of authentication.

The core piece of functionality with respect to authentication in Sling is contained in the Sling Auth Core bundle. This bundle provides the API for Sling and Sling applications to make use of authentication.

This support encompasses three parts:

The AuthenticationSupport service provided by the SlingAuthenticator class. This service can be used by implementations of the OSGi HttpContext interface to delegate authentication.
The Authenticator service also provided by the SlingAuthenticator class. This service may be used by Sling applications to help clients login and logout.
The AuthenticationHandler service interface. These services may be implemented by extensions to support various ways for transporting credentials from clients to the Sling server.

This page describes how the SlingAuthenticator class provides the AuthenticationSupport and Authenticator services. For a description of the AuthenticationHandler service interface and the interaction between the SlingAuthenticator and the AuthenticationHandler services refer to the AuthenticationHandler page.

The SlingAuthenticator class is an internal class of the org.apache.sling.auth.core bundle and implements the Authenticator and AuthenticationSupport services.

AuthenticationSupport

The AuthenticationSupport service interface defines a single method: handleSecurity. This method is intended to be called by the handleSecurity method of any HttpContext implementation wishing to make use of the Sling Authentication Framework.

The Sling Authenticator implementation selects an AuthenticationHandler service appropriate for the request and calls the AuthenticationHandler.extractCredentials method to extract the credentials from the request. If no credentials could be extracted, the Sling Authenticator either admits the request as an anonymous request or requests authentication from the client by calling its own login method.

The implementation follows this algorithm:

Select one or more AuthenticationHandler for the request according to the request URL's scheme and authorization part.
Call the extractCredentials method of each authentication handler, where the order of handler call is defined by the length of the registered path: handlers registered with longer paths are called before handlers with shorter paths. The goal is to call the handlers in order from longest request path match to shortest match. Handlers not matching the request path at all are not called.
The first handler returning a non-null AuthenticationInfo result "wins" and the result is used for authentication.
If any AuthenticationInfoPostProcessor services are registered, the AuthenticationInfo object is passed to their postProcess() method.
If no handler returns a non-null result, the request may be handled anonymously. In these cases, an empty AuthenticationInfo object is passed to any AuthenticationInfoPostProcessor services.
(Try to) log into the repository either with the provided credentials or anonymously.
If there were credentials provided and the login was successful, a login event is posted if the AuthenticationInfo object contains a non-null object with the key $$auth.info.login$$ (AuthConstants.AUTH_INFO_LOGIN). This event is posted with the topic org/apache/sling/auth/core/Authenticator/LOGIN. (added in Sling Auth Core 1.1.0)
Set request attributes listed below.

Extracting the credentials and trying to login to the repository may yield the following results:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Credentials	Login	Consequence
present	successful	Continue with an authenticated request
present	failed	Select `AuthenticationHandler` and call `requestCredentials` method
missing	anonymous allowed	Continue with a non authenticated request using anonymous access to the repository
missing	anonymous forbidden	Select `AuthenticationHandler` and call `requestCredentials` method

+Only one AuthenticationHandler is able to provide credentials for a given request. If the credentials provided by the handler cannot be used to login to the repository, authentication fails and no further AuthenticationHandler is consulted. +

Request Attributes on Successful Login

The handleSecurity method gets credentials from the AuthenticationHandler and logs into the JCR repository using those credentials. If the login is successful, the SlingAuthenticator sets the following request attributes:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Attribute	Description
`org.osgi.service.http.authentication.remote.user`	The user ID of the JCR Session. This attribute is used by the HTTP Service implementation to implement the `HttpServletRequest.getRemoteUser` method.
`org.osgi.service.http.authentication.type`	The authentication type defined by the `AuthenticationHandler`. This attribute is used by the HTTP Service implementation to implement the `HttpServletRequest.getAuthType` method.
`org.apache.sling.auth.core.ResourceResolver`	The `ResourceResolver` created from the credentials and the logged in JCR Session. This attribute may be used by servlets to access the repository. Namely the `SlingMainServlet` uses this request attribute to provide the `ResourceResolver` to handle the request.
`javax.jcr.Session`	The JCR Session. This attribute is for backwards compatibility only. Its use is deprecated and the attribute will be removed in future versions.
`org.apache.sling.auth.core.spi.AuthenticationInfo`	The `AuthenticationInfo` object produced from the `AuthenticationHandler`.

NOTE: Do NOT use the javax.jcr.Session request attribute in your Sling applications. This attribute must be considered implementation specific to convey the JCR Session to the SlingMainServlet. In future versions of the Sling Auth Core bundle, this request attribute will not be present anymore. To get the JCR Session for the current request adapt the request's resource resolver to a JCR Session:

Session session = request.getResourceResolver().adaptTo(Session.class);

Anonymous Login

The SlingAuthenticator provides high level of control with respect to allowing anonymous requests or requiring authentication up front:

Global setting of whether anonymous requests are allowed or not. This is the boolean value of the Allow Anonymous Access (auth.annonymous) property of the SlingAuthenticator configuration. This property is supported for backwards compatibility and defaults to true (allowing anonymous access). Setting it to true is a shortcut for setting sling.auth.requirements to -/.
Specific configuration per URL. The Authentication Requirements (sling.auth.requirements) property of the SlingAuthenticator configuration may provide a list of URLs for which authentication may be required or not: Any entry prefixed with a dash - defines a request path prefix for which authentication is not required. Any entry not prefixed with a dash or prefixed with a plus + defines a subtree for which authentication is required up front and thus anonymous access is not allowed. This list is empty by default.
Any OSGi service may provide a sling.auth.requirements registration property which is used to dynamically extend the authentication requirements from the Authentication Requirements configuration. This may for example be set by AuthenticationHandler implementations providing a login form to ensure access to the login form does not require authentication. The value of this property is a single string, an array of strings or a Collection of strings and is formatted in the same way as the Authentication Requirements configuration property.

The values set on the Authentication Requirements configuration property or the sling.auth.requirements service registration property can be absolute paths or URLs like the path service registration property of AuthenticationHandler services. This allows the limitation of this setup to certain requests by scheme and/or virtual host address. The requests path (HttpServletRequest.getServletPath() + HttpServletRequest.getPathInfo()) is afterwards matched against the given paths. It matches if it starts with one of the given paths.

Examples

The LoginServlet contained in the Sling Auth Core bundle registers itself with the service registration property sling.auth.requirements = "-/system/sling/login" to ensure the servlet can be accessed without requiring authentication (checks for slash or dot or end of string). The following request urls would work then without authentication:
/system/sling/login
/system/sling/login.html
/system/sling/login/somesuffix

While the following request will still require authentication

+
/system/sling/login-test
+
An authentication handler may register itself with the service registration property sling.auth.requirements = "-/apps/sample/loginform" to ensure the login form can be rendered without requiring authentication.

Authenticator implementation

The implementation of the Authenticator interface is similar for both methods:

login

Select one or more AuthenticationHandler for the request according to the request URL's scheme and authorization part.
Call the requestCredentials method of each authentication handler, where the order of handler call is defined by the length of the registered path: handlers registered with longer paths are called before handlers with shorter paths. The goal is to call the handlers in order from longest request path match to shortest match. Handlers not matching the request path at all are not called.
As soon as the first handlers returns true, the process ends and it is assumed credentials have been requested from the client.

The login method has three possible exit states:

+ + + + + + + + + + + + + + + + + + + + + +

Exit State	Description
Normal	An `AuthenticationHandler` could be selected to which the login request could be forwarded.
`NoAuthenticationHandlerException`	No `AuthenticationHandler` could be selected to forward the login request to. In this case, the caller can proceed as appropriate. For example a servlet, which should just login a user may send back a 403/FORBIDDEN status because login is not possible. Or a 404/NOT FOUND handler, which tried to login as a fallback, may continue and send back the regular 404/NOT FOUND response.
`IllegalStateException`	The response has already been committed and the login request cannot be processed. Normally to request login, the current response must be reset and a new response has to be prepared. This is only possible if the request has not yet been committed.

logout

Select one or more AuthenticationHandler for the request according to the request URL's scheme and authorization part.
Call the dropCredentials method of each authentication handler, where the order of handler call is defined by the length of the registered path: handlers registered with longer paths are called before handlers with shorter paths. The goal is to call the handlers in order from longest request path match to shortest match. Handlers not matching the request path at all are not called.

Unlike for the login method in the logout method case all AuthenticationHandler services selected in the first step are called. If none can be selected or none can actually handle the dropCredentials request, the logout silently returns.

+ + +

+ + http://git-wip-us.apache.org/repos/asf/sling-site/blob/a6129baf/documentation/the-sling-engine/authentication/authentication-tasks.html ---------------------------------------------------------------------- diff --git a/documentation/the-sling-engine/authentication/authentication-tasks.html b/documentation/the-sling-engine/authentication/authentication-tasks.html new file mode 100644 index 0000000..4475315 --- /dev/null +++ b/documentation/the-sling-engine/authentication/authentication-tasks.html @@ -0,0 +1,49 @@ + + + + Apache Sling on JBake + + +

+ +

Authentication - Tasks

Excerpt: Authentication of HTTP Requests is generally a two-step process: First the credentials must be extracted from the request and second the credentials must be validated. In the case of Sling this means acquiring a JCR Session.

Authentication of HTTP Requests is generally a two-step process: First the credentials must be extracted from the request and second the credentials must be validated. In the case of Sling this means acquiring a JCR Session.

Extract Credentials from the Request

Implemented and controlled by the Sling Auth Core bundle
Takes HttpServletRequest
Provides credentials for futher processing (basically JCR Credentials and Workspace name)
Extensible with the help of AuthenticationHandler services

Login to the JCR Repository

Implemented and controlled by the JCR Repository
Takes JCR Credentials and Workspace name
Provides a JCR Session
Implementation dependent process. Jackrabbit provides extensibility based on LoginModules; Sling's Embedded Jackrabbit Repository bundle provides extensibility with LoginModulePlugin services.

Currently the credentials are always verified by trying to login to the JCR repository. Once an ResourceResolverFactory API has been added, the process of validating the credentials and logging in is actualy replaced by a process of requesting a ResourceResolver from the ResourceResolverFactory. Of course, the JCR Repository will still be the main underlying repository and as such be used to validate the credentials and get a JCR Session.

+ + +

+ + http://git-wip-us.apache.org/repos/asf/sling-site/blob/a6129baf/documentation/the-sling-engine/default-mapping-and-rendering.html ---------------------------------------------------------------------- diff --git a/documentation/the-sling-engine/default-mapping-and-rendering.html b/documentation/the-sling-engine/default-mapping-and-rendering.html new file mode 100644 index 0000000..529eb13 --- /dev/null +++ b/documentation/the-sling-engine/default-mapping-and-rendering.html @@ -0,0 +1,34 @@ + + + + Apache Sling on JBake + + +

+ +

Default Mapping and Rendering

translation_pending: true

This page contained obsolete content, moved it to http://cwiki.apache.org/confluence/display/SLING/Default+Mapping+and+Rendering+%28OBSOLETE%29 in case it is useful to someone.

+ + +

+ +