9 |
10 |
11 | | |
12 | Name |
13 | |
14 | Interfaces/Functions |
15 | Implementation |
16 | Database |
17 | Implications |
18 |
19 |
20 |
21 |
22 | | x |
23 | Major Version |
24 | if major version number increased |
25 | interfaces will be different (i.e. not upward compatible) |
26 | will be different |
27 | new tables and possibly
change of existing tables
28 | |
29 | Implementation:
- bugs fixed
- new functions
- user code requires refactoring
Database:
- modification of existing tables
and adding of new tables
- no data migration |
30 |
31 |
32 | | y |
33 | Minor Version |
34 | if minor version number increased (but same major version number) |
35 | interfaces have been extended and/or new functions have been added (but upward compatibility is guaranteed) |
36 | will be different |
37 | possibly new tables |
38 | Implementation:
- bugs fixed
- new functions
- user code upwards compatible
Database:
- script adding new columns to table
and adding new tables
- no data migration |
39 |
40 |
41 | | z |
42 | Patch Version |
43 | if patch version number increased (but same specification number) |
44 | unchanged |
45 | will be different |
46 | possibly new columns
of existing tables
47 | |
48 | Implementation:
- bugs fixed
- user code upwards compatible
Database:
- script adding new columns to table
- no data migration |
49 |
50 |
51 |
52 |
53 | ## Upgrading to current version ##
54 |
55 | * Stop the running openCRX server
56 | * Backup your database
57 | * Install the current version of with the _openCRX Server Installer_ in a new directory
58 | * In case you made changes to the standard configuration of your previous openCRX installation, amend the changes in the new openCRX installation:
59 | * Verify `{OPENCRX_INSTALL_DIR}/apache-tomee-plus-[version]/bin/setenv.sh` (or setenv.bat on Windows)
60 | * Verify `{OPENCRX_INSTALL_DIR}/apache-tomee-plus-[version]/conf/tomee.xml` (called openejb.xml in older versions)
61 | * Verify `{OPENCRX_INSTALL_DIR}/apache-tomee-plus-[version]/conf/server.xml`
62 | * Verify `{OPENCRX_INSTALL_DIR}/apache-tomee-plus-[version]/conf/tomcat-users.xml`
63 | * Copy and upgrade extra JARs (e.g. JDBC-drivers, etc.) you added to `{OPENCRX_INSTALL_DIR}/apache-tomee-plus-[version]/lib`
64 | * In case you use HSQLDB as a database:
65 | * Copy `{OPENCRX_INSTALL_DIR_OLD}/data/crx/crx.script` to `{OPENCR_INSTALL_DIR}/data/crx/crx.script`
66 | * Start openCRX Server (the newly installed instance); you can either use the shortcut created by the installer or open a shell/cmd window and
67 | * cd to `{OPENCRX_INSTALL_DIR}/apache-tomee-plus-[version]/bin` and
68 | * execute `./opencrx.sh` run (or `opencrx.bat` run on Windows)
69 | * Once you have openCRX running again, proceed as follows:
70 | * Login as _admin-Root_
71 | * Launch the _Database schema wizard_ from _Wizards > Database schema wizard_
72 | * Click on the button _Validate and Fix_ (the wizard will upgrade your DB schema to the appropriate version of openCRX; the wizard will not delete/drop any tables or columns, i.e. if there are validation messages that you have extra tables/columns in your database, you should drop those manually with your preferred DB admin tool, e.g. pgAdmin for PostgreSQL). __Hint:__ some databases do not support create/update view and you will have to manually delete all views in your openCRX database so that the database schema wizard can create the new views; you have to do this with your preferred database administration tool (e.g. pgAdmin for PostgreSQL).
73 | * If there are validation messages that you have extra tables/columns in your database, you might want to drop those manually (the wizard does not drop tables/columns ever); please note, however, that __the wizard does not know about tables/columns related to model extensions in custom-projects__, i.e. double-check any table/column before you actually drop it
74 | * Click on the button _Validate_ to verify the database schema; it is important that the schema validation reports NO errors before you continue - if there are errors reported, try another cycle of _Validate and Fix_ followed by _Validate_; if that doesn't help, try deleting the views manually as explained above and then try another cycle of _Validate and Fix_ followed by _Validate_
75 | * Delete all codes as follows:
76 | * Navigate to _Codes_
77 | * In the grid _Codes_ select View > Show 500 rows
78 | * In the grid _Codes_ click the checkbox to the left of the header Identity to select all code rows
79 | * In the gird _Codes_ select Edit > Delete to delete all code entries
80 | * Import codes and data as follows:
81 | * Navigate to _Administration_
82 | * In the grid _Administration_ select View > Reload to import the new codes and data
83 | * Set the access levels of codes to 4, 3, 2, 1 as follows:
84 | * Navigate to _Codes_
85 | * In the grid _Codes_ select Security > Set Access Level
86 | * Set the drop downs in the dialog Set Access Level to the following values:
87 | * 4 for Browse access level
88 | * 3 for Update access level
89 | * 2 for Delete access level
90 | * 1 for Mode Recursive
91 | * Stop openCRX Server; it is important to shut down openCRX properly - you can either use the shortcut created by the installer or open a shell/cmd window and
92 | * cd to `{OPENCRX_INSTALL_DIR}/apache-tomee-plus-[version]/bin` and
93 | * execute `./opencrx.sh stop` (or `opencrx.bat stop` on Windows)
94 | * Start openCRX Server
95 | * For each of your segments (e.g. Standard) login as segment administrator (e.g. _admin-Standard_) and run the wizard Segment Setup (_Home > Wizards > Segment Setup_) to bring your configuration up to date
96 | * Optionally: you can now uninstall the new installation of openCRX as it is no longer needed
97 |
--------------------------------------------------------------------------------
/Admin/InstallOnDocker.md:
--------------------------------------------------------------------------------
1 | # How to install openCRX on Docker #
2 |
3 | openCRX comes with a Docker image. See [here](https://github.com/opencrx/opencrx-docker) for information.
4 |
--------------------------------------------------------------------------------
/Admin/InstallerServer.md:
--------------------------------------------------------------------------------
1 | # openCRX Server Installation #
2 | This book describes how to install an openCRX Server with the IzPack cross-platform installer
3 | (works on Windows, Linux, Mac OS, etc.). Please note that this is a guide to set up a runtime
4 | environment suitable for evaluation and testing purposes. If you intend to use openCRX in a
5 | production environment it is recommended that you migrate to one of the recommended database
6 | management systems (see guide “How to migrate openCRX database”).
7 |
8 | openCRX is the leading enterprise-class open source CRM suite. openCRX is based on openMDX,
9 | an open source MDA framework based on the OMG's model driven architecture (MDA) standards.
10 | This guarantees total openness, compliance with all relevant standards, a state-of-the-art
11 | component-based architecture, and virtually unlimited scalability.
12 |
13 | ### Who this book is for ###
14 | The intended audience are openCRX administrators and advanced users interested in evaluating openCRX.
15 |
16 | ### What you need to know with this book ###
17 | This book describes how to install openCRX with the IzPack installer, which takes care of
18 | all the tricky configuration issues for you. The prerequisites are minimal (JDK and Apache Ant)
19 | and once they are met you should have openCRX up and running in less than 5 minutes.
20 |
21 | ## Prerequisites ##
22 |
23 | ### JDK 21 ###
24 | Install [OpenJDK 21](https://openjdk.java.net/projects/jdk/21/).
25 |
26 | __IMPORTANT:__
27 |
28 | * With openCRX 6.x you really do need Java 21. Earlier versions do not work.
29 | * It is not sufficient to have a Java Runtime Environment (JRE) only. The full-blown JDK
30 | is required to run openCRX.
31 | * On Windows, it is a good idea to avoid paths containing blanks like the default installation
32 | directory ...\\Program Files\\....
33 |
34 | ### Apache Ant ###
35 | Download and install the latest version of [Apache Ant](https://ant.apache.org/index.html) for your platform and install it by expanding the downloaded file to a directory of your choice.
36 |
37 | ### openCRX Server Installer ###
38 | Download the openCRX Server Installer from [GitHub](https://github.com/opencrx/opencrx/releases/). The openCRX Server installer
39 | installs Apache TomEE, the openCRX EAR, an openCRX database (HSQLDB) and various configuration files on your system.
40 |
41 | __NOTE:__
42 | Please note that HSQLDB is not exactly a high performance DBMS nor is it meant to be
43 | used as a productive DBMS for openCRX. However, it gets lots of points for "ease of installation"
44 | and that is what counts for getting off the ground fast. Once you're comfortable with openCRX you
45 | can easily migrate to another DBMS without losing any data. More information about choosing a
46 | suitable DBMS and migrating from HSQLDB to another DBMS is available [here](http://www.opencrx.org/faq.htm#changedb)
47 |
48 | ## Installing openCRX Server ##
49 |
50 | * Open a console (Terminal window, DOS window, etc.) and navigate to the directory
51 | that contains the openCRX IzPack installer.
52 | * Launch the installer with the following command ((use the option -console to launch
53 | the installer in text mode):
54 |
55 |
56 | ```
57 | java -jar opencrxServer-6.0.0-installer.jre-21.jar
58 | ```
59 |
60 |
61 | * Click _Next_ on the following screen:
62 |
63 | 
64 |
65 | * Accept the BSD License Agreement and click _Next_ again:
66 |
67 | 
68 |
69 | * Select the home directory of your JDK 21 installation (automatically selected if the environment
70 | variable _JAVA\_HOME_ is set) - for example /usr/lib/jvm/java-21-openjdk-amd64 - and then click
71 | _Next_ to continue:
72 |
73 | 
74 |
75 | * Select the home directory of your Ant installation (automatically selected if the environment
76 | variable _ANT\_HOME_ is set correctly) - for example /opt/apache-ant-1.9.4 - and then click _Next_
77 | to continue:
78 |
79 | 
80 |
81 | * Select the installation directory - for example /opt/opencrxServer - and then click
82 | _Next_ to continue. Note that if you choose to create a new directory you will have to confirm
83 | your choice by clicking _OK_ in the respective pop-up.
84 |
85 | 
86 |
87 | * Verify the configuration data and then click _Next_ to continue:
88 |
89 | 
90 |
91 | * openCRX Server is now being installed. Once the installation process has completed,
92 | click _Next_ to continue:
93 |
94 | 
95 |
96 | * If you want the installer to create shortcuts, select options as shown below and then
97 | click _Next_ to continue:
98 |
99 | 
100 |
101 | * Carefully read the README, in particular information about valid URLs,
102 | preconfigured users and passwords. Click _Next_ to continue:
103 |
104 | 
105 |
106 | * Finally, click _Done_ to finish:
107 |
108 | 
109 |
110 | That's it for the installation.
111 |
112 | ## Running openCRX Server ##
113 | The installation process created various shortcuts in your Windows Start Menu
114 | (shortcuts/launchers in your application directory on Linux).
115 |
116 | __NOTE:__ Your version numbers might be different depending on the Tomcat version included in the installer.
117 |
118 | ### Starting openCRX Server ###
119 | Launch the shortcut _Start openCRX Server 6.0.0 (8080)_.
120 |
121 | If you did not create the shortcuts (or if the installer could not create them) you can start
122 | openCRX Server with the command:
123 |
124 | Linux:
125 |
126 | ```
127 | cd ./opencrxServer/apache-tomee-plus-10.0.0/bin
128 | ./opencrx.sh run
129 | ```
130 |
131 | Windows:
132 |
133 | ```
134 | cd .\opencrxServer\apache-tomee-plus-10.0.0\bin
135 | opencrx.bat run
136 | ```
137 |
138 | directly from a console (Terminal window, DOS window). Please note that on
139 | Linux/Mac platforms you might have to start the server with elevated rights,
140 | e.g. sudo ./opencrx.sh run.
141 |
142 | ### Connecting and Login ###
143 | Launch your browser and load the URL
144 |
145 | ```
146 | http://localhost:8080/opencrx-core-CRX/
147 | ```
148 |
149 | If you want to load the login page in a specific language,
150 | read [here](http://www.opencrx.org/faq.htm#login) on how to do it.
151 |
152 | ### Stopping openCRX Server ###
153 | Launch the shortcut _Stop openCRX Server 6.0.0 (8080)_.
154 |
155 | ## Next Steps ##
156 | Now that you have successfully installed openCRX you might want to have a look at some of
157 | the additional documentation published [here](http://www.opencrx.org/documents.htm).
158 |
--------------------------------------------------------------------------------
/Admin/ManagingSecurity.md:
--------------------------------------------------------------------------------
1 | # Managing Security #
2 | In this chapter we will present a high-level overview of openCRX security and discuss a few important issues.
3 |
4 | __WARNING:__ We do not recommend learning about security with mission critical data. Backup your data before you make changes if you are not certain what the consequences are! The risk of you being locked out is real and the resources required to fix broken security settings can not be overestimated!
5 |
6 | The default settings should work for virtually all users; the probability of getting yourself into trouble by changing default settings should not be underestimated. Read and understand at least the basics of openCRX security BEFORE you make any changes.
7 |
8 | ## Introduction ##
9 |
10 | ### Basic Concepts and Conventions ###
11 |
12 | * Each “real user” is represented by a Subject (e.g. “guest”). Subjects are managed by the openCRX Root administrator (admin-Root).
13 | * Each subject has an Application Login Principal (also called login id). Application login principals are managed by the openCRX Root administrator (admin-Root).
14 | * Each application login principal is assigned to a subject (e.g. principal “guest” is assigned to subject “guest”) and allows a “real user” to login.
15 | * A “real user” can have one or more additional segment login principals. The Segment Login Principal has typically the same name as the application login principal (e.g. “guest”) and grants a “real user” login access to a segment. Segment login principals are managed by openCRX segment administrators (admin-Standard for the Segment Standard).
16 | * Each “real user” who has access to a segment (i.e. has a segment login principal) has (in addition to the segment login principal) a segment user principal, e.g. “guest.User”. The Segment User Principal is required to assign objects to an Owning User. Each “real user” also has a Principal Group, e.g. “guest.Group”.
17 | * Each segment has a corresponding realm to manage Principals:
18 | * The application login principals are stored in the realm Default.
19 | * The segment login principals for segment _segment name_ are stored in the realm _segment name_ (e.g. principals for the segment Standard are stored in the realm Standard).
20 | * Each segment has a segment administrator principal (admin-_segment name_) (e.g. _admin-Standard_ for the segment Standard).
21 |
22 | The following figure shows the situation after the initial setup of openCRX:
23 |
24 | 
25 |
26 | Summarizing the above:
27 |
28 | * there is a realm for each segment (e.g. a realm Standard corresponding to the segment Standard)
29 | * the realm Default acts as login realm; it contains all principals who are allowed to login to the openCRX application; PrincipalGroups in this realm are only used to configure Granted Roles by inheritance (in addition to configuring them directly in the appropriate grid).
30 | * there is a subject for each “real user” and all principals of a user are assigned to the same subject; this allows openCRX to find all principals of a user (→ role selection drop down)
31 |
32 | The segment administrator (e.g. admin-Standard) creates principals and User home pages with the operation createUser:
33 |
34 | 
35 |
36 | Each segment login principal has a home page in the respective segment (qualifier of principal and home page must match!).
37 |
38 | Each segment login principal is correlated with a contact. This correlation is for example required to find all activities and contracts assigned to the logged in principal.
39 |
40 | 
41 |
42 | While each “real user” (typically) has 1 application login principal only, “real users” may have multiple segment login principals (e.g. because a “real user” is allowed to access multiple segments or because a “real user” is allowed to access a particular segment in different roles like Head of Sales or CFO).
43 |
44 | Available segment login principals are listed in the so-called Role Drop Down:
45 |
46 | 
47 |
48 | ### Permissions / Access Control ###
49 | The openCRX security framework makes a clear distinction between Ownership Permissions (permissions granted on a particular object) and Model Permissions (permissions granted on a particular model element). As the latter are not implemented (yet) we only talk about Ownership Permissions in this guide. In addition to wwnership permissions there are also GUI Permissions (see the guide openCRX GUI – Getting Started).
50 |
51 | Ownership permissions are used to control browse/update/delete access to openCRX objects by Users and UserGroups (i.e. Ownership access control). Every openCRX object is a SecureObject. The following figure shows an extract from the UML model (if you are interested in all the details and the formally correct and complete specifications you should refer to the latest openCRX UML models):
52 |
53 | 
54 |
55 | __NOTE:__ If you see N/P in a reference field instead of a more meaningful value you probably do not have browse access to the respective object (N/P stands for No Permission)
56 |
57 | __NOTE:__ If you see N/A in a reference field instead of a more meaningful value the object cannot be retrieved (N/A stands for Not Available); maybe the object was deleted or the respective provider is not accessible/available.
58 |
59 | The most important security attributes of an object X are discussed below:
60 |
61 | * __Owning User:__ this user "owns" object X; the Owning User can always browse/update/delete object X (unless the access level is set to 0 - in which case nobody has access and is probably not a desirable situation).
62 | * __Owning Groups:__ these groups might enjoy privileged treatment for browsing/updating/deleting object X depending on the relevant access level settings.
63 | * __Access Granted by Parent:__ this attribute is set by configuration and refers to the parent object that grants access to object X.
64 | * __Browse Access Level:__ this setting determines which users/user groups are granted browse access to direct composite objects of object X (i.e. who can view/inspect direct composite objects of object X (including all their attributes)). It is a common misconception that browse access level of an object X controls browse access to this object X – please read the above definition carefully!
65 | * __Update Access Level:__ this setting determines which users/user groups are granted update access to object X (i.e. who can change object X; this includes adding composite objects to object X).
66 | * __Delete Access Level:__ this setting determines which users/user groups are granted delete access to object X and all its composite objects (recursively!) (i.e. who can delete object X and all its composite objects (recursively!)).
67 |
68 | 
69 |
70 | The following access levels are available to control which users/user groups are granted permission to browse/delete/update a particular object X:
71 |
72 | Access Level | Meaning
73 | -------------|---------
74 | 0 - N/A | no access
75 | 1 - private | access is granted if the user is owning user of object X
76 | 2 - basic | access is granted if at least one of the following conditions is true:
77 | | (a) the user is owning user of object X
78 | | (b) the user is member of any of the owning groups of object X
79 | | (c) any of the owning groups of object X is a subgroup** of any group the user is member of
80 | 3 - deep | access is granted if at least one of the following conditions is true:
81 | | (a) the user is owning user of object X
82 | | (b) the user is member of any of the owning groups of object X
83 | | (c) any of the owning groups of object X is a subgroup** of any group the user is member of
84 | | (d) any of the owning groups of object X is a subgroup** of any supergroup* of any group the user is member of
85 | 4 – global | all users are granted access
86 |
87 | (\*) Owning group Gsuper is a supergroup of an owning group G if every user who is member of G is also member of Gsuper
88 | (\**) Owning group Gsub is a subgroup of an owning group G if every user who is member of Gsub is also member of G
89 |
90 | ### Default Principal Groups ###
91 | The figure on the right shows the openCRX default principal groups and their memberships:
92 |
93 | * Unassigned
94 | * Public
95 | * Administrators
96 | * Users
97 | * Unspecified
98 |
99 | 
100 |
101 | ### The SQL approach to understanding security ###
102 | If you are familiar with SQL, the following approach to understanding security might be helpful. Let's put ourselves into the role of the AccessControl Plugin; accessing an object (read mode) results in a SELECT statement as follows:
103 |
104 | ```
105 | SELECT * FROM T WHERE owner IN (p1, p2, ....)
106 | ```
107 |
108 | * owner is a column that is present in all (multi-valued) tables xACCOUNT_, xADDRESS_, etc.) and it contains a list of principals who are permitted to access the respective object in read-mode
109 | * the set P = {p1, p2, ...} is calculated by the AccessControl Plugin before accessing the object and it corresponds to the principals who are assigned to the current user based on the object's AccessLevel as shown in the following table:
110 |
111 | Access Level | Set P = {p1, p2, ...}
112 | -------------|----------------------
113 | 0 - N/A | P = {}
114 | 1 - private | P = Pp where Pp = {all groups directly assigned to the principal p}
115 | 2 - basic | P = Pp + Pupper where Pp = {all groups directly assigned to the principal p}, Pupper = {all groups that contain at least one group contained in Pp}
116 | 3 - deep | P = Pp + Pupper + Plower where Pp = {all groups directly assigned to the principal p}, Pupper = {all groups that contain at least one group contained in Pp}, Plower = {all groups contained in Pupper}
117 | 4 – global | the where-clause “WHERE owner IN (p1, p2, ....)” is not required, i.e. the SELECT statement reduces to SELECT * FROM T
118 |
119 | You can mark PrincipalGroups as _Base group_ to better control the inclusion of PrincipalGroups with Access Level 3.
120 |
121 | ## Activating Security ##
122 | Security (including Access Control) is not just a fancy add-on, rather it is an integral part of openCRX; openCRX Access Control is always activated.
123 |
124 | The openCRX security provider manages all security data and provides access control services for all requests through the openCRX API. Hence, you can rely on openCRX access control even if you write you own clients or adapters for openCRX.
125 |
126 | __NOTE:__ The only “hardening” you might want to do is the one described in the following chapter: set browse access level to 3 for non-Root segments.
127 |
128 | ### Default Settings ###
129 | Default access level settings for non-Root segments (e.g. segment Standard) after a clean install are as follows:
130 |
131 | * Browse Access Level: 4 - global
132 | * Update Access Level: 3 - deep
133 | * Delete Access Level: 1 - private
134 |
135 | 
136 |
137 | Due to the setting access_level_browse = 4 (global) any user with access to a particular segment is allowed to browse top level objects (i.e. any user can browse all accounts, all activities, all documents, etc.).
138 |
139 | These default settings are suitable for test environments and deployments in smaller companies/teams with a generous access policy; for most real-world applications, however, it is more appropriate to set access_level_browse = 3 (deep) for non-Root segments. You can do this by changing the values in the column access_level_browse from 4 to 3 (table OOCKE1_SEGMENT).
140 |
141 | After this change, the table OOCKE1_SEGMENT will look as follows:
142 |
143 | 
144 |
145 | __IMPORTANT:__ Segment security settings are loaded during the initialization of the openCRX servlet. Hence, if you change settings you must redeploy openCRX for the new settings to become active.
146 |
147 | ## Security Settings of New Objects ##
148 | New objects are by default created with the following security settings:
149 |
150 | * Browse Access Level: 3 - deep
151 | * Update Access Level: 2 - basic
152 | * Delete Access Level: 2 - basic
153 | * Access Granted by Parent:
154 | * in general: Parent object as modeled
155 | * exceptions: there are some select exceptions, but they are all pre-configured
156 | * Owning User: User who is creating the object
157 | * Owning Groups: Primary User Group of the user who is creating the object and (meaning as well as) Owning Group(s) of the parent object of the new object (except Users, see below).
158 |
159 | __WARNING:__ Please note that the User Group Users (e.g. Standard\\Users) is not added to the list of Owning Groups of newly created objects unless the creating user's Primary User Group is equal to Users.
160 |
161 | __WARNING:__ By default, a user's primary user group is