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