subsystem framework and authentication
DESCRIPTION
In this session, Senior Alfresco Engineer Dave Ward explains how introducing new architectural building blocks called subsystems has simplified configuring Alfresco. He will also demonstrate how one of the most complex configuration tasks of setting up an authentication chain can now be achieved with relative ease.TRANSCRIPT
1
Alfresco Subsystems
David WardSenior Developer, Alfresco Repository Team
twitter: @davelward
Agenda
• BS: Before Subsystems• Introducing Subsystems• A look at some simple Subsystems
• Third Party• File Servers
• Subsystem Basics• Defining• Mounting• Importing• Configuring
2
Agenda
• Authentication Chaining in Alfresco v3.3• Demo: Configuring an LDAP Authentication Chain
• The Synchronization Subsystem• Q & A
3
BS: Before Subsystems
• Alfresco versions 1 to 3.1• Spring configuration subdivided between broadly-themed
context files• authentication-services-context.xml• authority-services-context.xml• rendition-services-context.xml• ...
• All loaded into single global Spring Application Context• Customized by overriding definition of selected beans
4
BS: Before Subsystems
5
BS: Before Subsystems
• Problems• No scoping – everything global
• Coupling: every bean can use every other bean• Hard to separate out dependencies in unit tests• Namespacing: strict bean naming conventions had to be
followed to avoid name collisions• Supportability / Upgradeability
• No clear separation between configuration vs. customization• Even basic admin tasks required understanding of Spring• Virtually every bean definition ‘fair game’ for overriding
• Hard to make sure all possible configurations are tested• Hard for support team to recognize what is actually configured!• Hard to maintain backward compatibility with old configuration
6
BS: Before Subsystems
• Problems• No plug and play
• Switching between supported authentication stacks (Alfresco, Kerberos, LDAP, NTLM) involved simultaneous editing of
• custom-repository-context.xml• web.xml• file-servers-context.xml
• Template configuration could not be used without editing due to the namespacing problem
• E.g. Two ldap directories in authentication chain
• Reconfiguration / Startup Time• Configurable objects all live in the same application context• Reconfiguring involves shutting down and restarting entire server
7
Introducing Subsystems
• A subsystem• is a module responsible for a sub-part of Alfresco functionality• is like a mini Alfresco Server embedded within the main one• Can be started, stopped and configured independently• Has its own isolated Spring bean container and configuration
• No problem of bean name uniqueness• Can have multiple ‘instances’ of the same type
• Can be brought in and out of existence dynamically• Has amazing potential for simplifying authentication chaining
8
Introducing Subsystems
9
Introducing Subsystems
• A subsystem• Clearly defines its interfaces with the rest of the system
• All hook points into the main server must be imported as dynamic proxies
• Hides implementation specifics• Can be ‘hot-swapped’ with an alternative implementation without
the main server even knowing• Automatically exposes its configuration properties for editing via
JMX (enterprise only)• Stop subsystem, edit properties, and test without server restart• All edits are remembered in the database and synchronized
across a cluster
10
Managing and Monitoring a Subsystem
• In Alfresco Enterprise versions Subsystems and their properties are exported via JMX
• In Jconsole, objects can be found in the Alfresco:Type=Configuration tree
• Editing a property automatically ‘stops’ the subsystem across the entire cluster
• Application context is destroyed and beans disposed of
• Further edits can be made whilst in stopped state• All edited property values are persisted in the database• To apply the new settings use the start() operation
• New application context is refreshed with the new properties across the cluster
• Use the revert() operation to discard all persisted edits and return to subsystem defaults
11
Demonstration: The Third Party Subsystem
• Currently owns the ImageMagick and Swftools tools• These third party tools must be installed and configured in
order to enable certain functionality• E.g. Thumbnail and Preview generation
• On subsystem startup• Checks existence of tools at their configured locations• Outputs warnings on problems• Initializes transformer workers• Exports details to JMX
• Tool availability and version information
12
Demonstration: The Third Party Subsystem
13
The File Server Subsystem
• Owns the CIFS, FTP and NFS Servers• Allows JMX control over everything that previously had to
be edited in file-servers-custom.xml• Filesystem name• Global Access Controls
• Domain• Protocol• User
• IP v6, WINS, NetBIOS, TCP/IP• Broadcast IP addresses• Domain Mappings
14
The File Server Subsystem
• Can be restarted independently of the rest of Alfresco• Does not embed any authentication specifics
• CIFS and FTP authentication is performed by the authentication subsystem
• No danger of using incompatible authenticators• CIFS automatically disabled if your authentication subsystem is not
CIFS capable (e.g. LDAP only)
15
The File Server Subsystem
16
Demonstration: The File Server Subsystem
• Has ‘composite properties’• Properties whose values can be collections of composite types
• Examples• NFS user mappings• Global Access Controls
• Demonstration
17
Subsystem Basics
• Every subsystem has its own Spring Application Context• This is simply a child of the ‘main’ application context
• Subsystem contexts can see all beans and properties in the parent context
• All beans in core-services-context.xml automatically available
• Subsystems hide their implementation details• The parent context cannot see beans and properties of subsystems• Subsystems cannot see beans and properties of other subsystems
• To use a subsystem from outside (parent context or another subsystem) in the parent context you must:
• Mount the subsystem, defining one or more interfaces used for communication and startup options
• Import the subsystem interfaces using a dynamic proxy
18
Subsystem Basics
• Every subsystem has a Category and a Type. • Category: a broad description of the subsystem's function, e.g. Authentication
• Type: a name for the particular flavour of implementation where multiple alternative implementations exist, e.g. ldap
• Where only one implementation exists, use the default type name default
19
Defining a Subsystem
• A subsystem's definition files should be accessible from a classpath folder with the following path
• alfresco/subsystems/<category>/<type>
• In reality this means that they should be embedded in a .war file or AMP under the following path
• WEB-INF/classes/alfresco/subsystems
• In SVN, Repository subsystems are under• projects/repository/config/alfresco/subsystems
• These files should not be edited (except when developing your own subsystem or contributing enhancements).
20
Defining a Subsystem
• Two types of definition file• Property Defaults
• In Java .properties format (key=value)• Must be named *.properties• Each key declares a configurable parameter of the subsystem• Each value declares the default value of that parameter
• Spring Configuration• A standard XML Spring Bean Definition file• Must be named *-context.xml• Uses standard placeholders beginning ${ and ending } to bind
the configured parameters into the bean definition• E.g. ${placeholder}
• No need to declare a PropertyPlaceholderConfigurer!
21
Example Subsystem Definition
• WEB-INF/classes/alfresco/subsystems/Replication/default/• replication.properties
replication.transfer.readonly=true
• replication-context.xml<?xml version='1.0' encoding='UTF-8'?><!DOCTYPE beans PUBLIC '-//SPRING//DTD BEAN//EN' 'http://www.springframework.org/dtd/spring-beans.dtd'>
<beans> <bean id="replicationParams" class="org.alfresco.repo.replication.ReplicationParamsImpl">
<property name="transferReadOnly"> <value>${replication.transfer.readonly}</value>
</property> </bean></beans>
22
Mounting a Subsystem
• Declare the subsystem to the main server through a ChildApplicationContextFactory bean.
• Should extend abstractPropertyBackedBean• Bean ID defines the category and hence the search path for configuration files.
• Set the autoStart property to true if the subsystem should be activated at the same time as the main application context.
• Important for background processes or daemons (e.g. the file server subsystem), because nothing else will cause the subsystem to initialize.
• For example, in bootstrap-context.xml: <bean id="thirdparty" class="org.alfresco.repo.management.subsystems.ChildApplicationContextFactory" parent="abstractPropertyBackedBean">
<property name="autoStart"> <value>true</value> </property> </bean>
23
24
Importing a Subsystem
• Import one or more interfaces into the main application context using SubsystemProxyFactory
• If there is more than one bean with the same interface you can name the source bean
• Otherwise the beans are selected automatically according to interface
• This level of indirection makes the subsystem consumer oblivious to its implementation
• allows for dynamic reconfiguration and ‘hot-swapping’ of the subsystem without server restart
• If a subsystem is not yet started, the first call to one of its interface methods will start it automatically
Importing a Subsystem
• For example, in swf-transform-context.xml: <bean id="transformer.worker.Pdf2swf" class="org.alfresco.repo.management.subsystems.SubsystemProxyFactory">
<property name="sourceApplicationContextFactory"> <ref bean="thirdparty" /> </property> <property name="sourceBeanName"> <value>transformer.worker.Pdf2swf</value> </property> <property name="interfaces"> <list> <value>org.alfresco.repo.content.transform.ContentTransformerWorker</value>
</list> </property> </bean>
25
Configuring a Subsystem
• We’ve already seen JMX. What else is there?• alfresco-global.properties
• For community edition or headless systems with no JMX access• User-friendly replacement to custom-repository.properties• Drops in to $TOMCAT_HOME/shared/classes directory with no
extra spring configuration required• Defines global overrides to subsystem property values, repository
and hibernate properties• Not suitable for controlling properties of subsystems with multiple
instances• E.g. Authentication chain with multiple LDAP servers• See Authentication chain examples
26
Configuring a Subsystem
• Extension classpath• Allows exact scoping of properties to individual subsystem instances• Allows dropping in of extensions to prepackaged Spring Configuration
• A subsystem's extension classpath overrides are picked up from a folder in the class path with the following sub-path
• alfresco/extension/subsystems/<category>/<type>/<id>
• Here, <id> is the subsystem instance identifier, which is default unless the subsystem is chained (more later).
• Examples:• alfresco/extension/subsystems/fileServers/default/default/mychanges.properties
• alfresco/extension/subsystems/Authentication/alfrescoNtlm/alfrescoNtlm1/custom-context.xml
27
The Authentication Subsystems
• There are now 5 types of Authentication Subsystem• alfrescoNtlm
• Native Alfresco authentication• optional NTLM v2-based single sign-on (SSO)• Supports CIFS authentication
• ldap• Authentication via an LDAP server
• Optional user registry export• Form-based login only• No CIFS authentication• ldap-ad variant exists with preconfigured defaults for Active Directory
• external• Authentication by the application server
• E.g. CAS, Websphere LTPA• User identity asserted to Alfresco via
HttpServletRequest.getRemoteUser() or configured HTTP header
28
The Authentication Subsystems
• kerberos• Authentication with a Kerberos Realm
• Optional SPNEGO-based single sign-on (SSO)• Supports CIFS authentication• New in v3.4: Sharepoint Protocol, Webscript and Share support
• passthru• Authentication via a Windows domain server
• Optional NTLM v1-based single sign-on (SSO)• Supports CIFS authentication
29
What’s in an Authentication Subsystem?
• An authentication component• Handles specifics of talking to the external subsystem
• An authentication DAO• Decides what user management functions are allowed (if any) e.g.
Create user
• An authentication service• Wraps the component with higher-level functions
• A user registry export service (optional)• LDAP only – allows Alfresco to obtain user attributes such as email
address, organization, and groups automatically
30
What’s in an Authentication Subsystem?
• Authentication Filters• Provides form or SSO-based login functions for
• Web Client• Web DAV• Web Scripts• Sharepoint Protocol
• File server authenticators for• CIFS protocol• FTP protocol
31
Advantages of the Authentication Subsystems
• Each subsystem is a coordinated stack of compatible components
• No danger of e.g. Using the wrong CIFS authenticator with the wrong authentication component
• Common parameters are shared• No need to paste the same Kerberos parameters multiple times into
different configuration files
• No need to edit web.xml – ever!• Web.xml uses generic filters that call into the authentication
subsystem• You can hot swap from one filter to another
32
Advantages of the Authentication Subsystems
• All the ‘wiring’ is done for you• Less chance of error
• A ‘known quantity’ support-wise• No off-piste configuration
• Easily chained• As we are about to see!
33
What is an Authentication Chain?
• Some enterprise customers may store user authentication data in multiple systems
• Local Alfresco• Active Directory• LDAP• Kerberos
• There may be more than one instance of each type• E.g. multiple LDAP directories
• One system may support different protocols for different purposes
• E.g. Active Directory with LDAP for User Registry Export and Kerberos for Authentication
• Rather than tie Alfresco exclusively to one of those systems and protocols, our customers want it all!
34
How does an Authentication Chain work?
• An authentication component is configured for each system and added to an ordered list or ‘chain’
• On a user login, Alfresco tries the credentials against each of the components in the chain
• If a chain member accepts the credentials the login succeeds
• If no chain member accepts, the login fails
35
An Authentication Chain In Action
36
authenticate (dw, pizza)?
No No Yes!authenticate (dw, pizza)?
authenticate (dw, pizza)?
authenticate (dw, pizza)?
Yes!
Authentication Chaining in Alfresco 3.3
• The default product configuration actually already has an authentication chain
• It’s just a chain of size 1!• It contains an alfrescoNtlm1 subsystem instance with SSO
switched off by default• This means
• Native Alfresco authentication out of the box• Enablement of NTLM SSO by editing a single boolean property
• Assuming your Alfresco passwords match your domain passwords!
37
Authentication Chaining in Alfresco 3.3
• We can easily add to or completely replace this chain• The chain is controlled by a special composite property• A comma separated list of the form:
• instance_name1:type1,...,instance_namen:typen
• E.g.• alfrescoNtlm1:alfrescoNtlm,ldap1:ldap
38
Authentication Chaining in Alfresco 3.3
• By editing this property• New instances are brought into existence• Removed instances are destroyed• The new ordering of instances is honoured
• Each instance you create has its own property set in the JMX object tree
• Properties are also overridable in the extension classpath at:
• alfresco/extension/subsystems/Authentication/<type>/<instance_name>/*.properties
39
Demonstration:Adding LDAP to the chain
40
Composing Authentication Chain Functions
• Decide which chain members will handle SSO, CIFS and User Registry Export
• E.g. In this chain
alfrescoNtlm1:alfrescoNtlm,passthru1:passthru,ldap1:ldap
• Built-in users and Active Directory users should be able to log in (no SSO)
• Active Directory should handle CIFS authentication directly• LDAP should be used to synchronize user and group
details
41
Composing Authentication Chain Functions
• So we set• alfrescoNtlm1
• ntlm.authentication.sso.enabled=false• alfresco.authentication.authenticateCIFS=false
• passthru1• ntlm.authentication.sso.enabled=false`• passthru.authentication.authenticateCIFS=true
• ldap1• ldap.authentication.active=false• ldap.synchronization.active=true
42
The Synchronization Subsystem
• Owns synchronization of Alfresco with all the user registries (LDAP servers) in the authentication chain
• Avoids a system administrator having to manage Alfresco accounts for every single user in your organization!
• Tracks origin of all created users and groups to enable ‘fair’ handling of deletions and ‘collisions’ between user IDs.
• Each LDAP directory has its own ‘zone’ ID• Users and groups in Alfresco are tagged with their originating zone• On synchronization with a zone, only those users and groups
tagged with that zone are candidates for deletion• No accidental removal of built in ALFRESCO_ADMINISTRATORS
group!
The Synchronization Subsystem
• Priority order of authentication chain honoured if there are ‘overlaps’
• If user A is queried from zone Z1 but already exists in Alfresco in zone Z2
• if Z1 is before Z2 in the authentication chain• A is deleted from Z2 and recreated in Z1
• if Z1 is after Z2 in the authentication chain• A is ignored and retains its properties from Z2
• if Z2 is no longer in the authentication chain• A is ‘reclaimed’ and moved to Z1
44
The Synchronization Subsystem
• Three ‘modes’ of synchronization are supported• Differential
• Attributes of users and groups modified since the last sync queried• Local users and groups updated / added accordingly
• Differential With Deletions• Attributes of users and groups modified since the last sync queried• Local users and groups updated / added accordingly• Ids of every user and group in the LDAP directory queried• Local users and groups deleted accordingly
• Full• Attributes of all users and groups are queried• Local users and groups updated / added / deleted accordingly• Only required when the server has somehow got out of sync
45
Synchronization Triggers
• On Startup (in differential mode)• Can be disabled with
synchronization.syncOnStartup=false
• On Authentication (in differential mode)• On successful authentication of a user who does not yet exist locally• Can be disabled with
synchronization.syncWhenMissingPeopleLogIn=false
• On Schedule (in differential with deletions mode)• A scheduled job triggers synchronization every 24 hours.• Can be scheduled in full mode with
synchronization.synchronizeChangesOnly=false• The synchronization.import.cron property allows changing
of the schedule
46
Q&A
• Any questions?
47
48
Mauris id fellis quis lacus
Volutpat orci nec nisi porttitor
Mauris id fellis quis lacus
Volutpat orci nec nisi porttitor
• Mauris id fellis quis lacus• Volutpat orci nec nisi porttitor
• Mauris id fellis quis lacus• Volutpat orci nec nisi
porttitor• Mauris id fellis quis lacus
• Volutpat orci nec nisi porttitor
49
• Lorem ipsum dolor sit
• Second level bullet point avoid if possible
• Consectetur adipiscing elit
• Mauris id fellis quis lacus
• Volutpat orci nec nisi porttitor
50
• Mauris id fellis quis lacus• Volutpat orci nec nisi porttitor
51
• Lorem ipsum dolor sit• Second level bullet point
avoid if possible
• Consectetur adipiscing elit
• Lorem ipsum dolor sit• Second level bullet point
avoid if possible
• Consectetur adipiscing elit
52
Code Sample
// ensure mandatory file attributes have been locatedif (filename == undefined || content == undefined){ status.code = 400; status.message = "Uploaded file cannot be located in request"; status.redirect = true;}else{ // create document in company home for uploaded file upload = userhome.createFile("upload_" + userhome.children.length + "_" + filename) ;
upload.properties.content.write(content); //upload.properties.content.mimetype = "application/ppt"; upload.properties.title = title; upload.properties.description = description; upload.save();
53
Another Code Sample (Screenshot)
54
Learn Morewiki.alfresco.comforums.alfresco.comtwitter: @AlfrescoECM
55
Shape & Color Pallette
Normal Text
Normal TextNormal Text
56