From 6e5105f899de3ff7cfb7dd408bf02df8354ac9b7 Mon Sep 17 00:00:00 2001 From: Rob Winch Date: Tue, 6 Mar 2018 13:09:31 -0600 Subject: [PATCH] Extract appendix subsections Issue: gh-2567 --- .../_includes/appendix/database-schema.adoc | 352 ++++++++++ .../_includes/appendix/dependencies.adoc | 261 ++++++++ .../_includes/{ => appendix}/faq.adoc | 0 .../asciidoc/_includes/appendix/index.adoc | 12 + .../namespace.adoc} | 621 ------------------ .../{ => appendix}/proxy-server.adoc | 0 docs/manual/src/docs/asciidoc/index.adoc | 2 +- 7 files changed, 626 insertions(+), 622 deletions(-) create mode 100644 docs/manual/src/docs/asciidoc/_includes/appendix/database-schema.adoc create mode 100644 docs/manual/src/docs/asciidoc/_includes/appendix/dependencies.adoc rename docs/manual/src/docs/asciidoc/_includes/{ => appendix}/faq.adoc (100%) create mode 100644 docs/manual/src/docs/asciidoc/_includes/appendix/index.adoc rename docs/manual/src/docs/asciidoc/_includes/{appendix.adoc => appendix/namespace.adoc} (83%) rename docs/manual/src/docs/asciidoc/_includes/{ => appendix}/proxy-server.adoc (100%) diff --git a/docs/manual/src/docs/asciidoc/_includes/appendix/database-schema.adoc b/docs/manual/src/docs/asciidoc/_includes/appendix/database-schema.adoc new file mode 100644 index 0000000000..8c3f26d9bf --- /dev/null +++ b/docs/manual/src/docs/asciidoc/_includes/appendix/database-schema.adoc @@ -0,0 +1,352 @@ +[[appendix-schema]] +== Security Database Schema +There are various database schema used by the framework and this appendix provides a single reference point to them all. +You only need to provide the tables for the areas of functionality you require. + +DDL statements are given for the HSQLDB database. +You can use these as a guideline for defining the schema for the database you are using. + + +=== User Schema +The standard JDBC implementation of the `UserDetailsService` (`JdbcDaoImpl`) requires tables to load the password, account status (enabled or disabled) and a list of authorities (roles) for the user. +You will need to adjust this schema to match the database dialect you are using. + +[source] +---- + +create table users( + username varchar_ignorecase(50) not null primary key, + password varchar_ignorecase(50) not null, + enabled boolean not null +); + +create table authorities ( + username varchar_ignorecase(50) not null, + authority varchar_ignorecase(50) not null, + constraint fk_authorities_users foreign key(username) references users(username) +); +create unique index ix_auth_username on authorities (username,authority); +---- + +==== Group Authorities +Spring Security 2.0 introduced support for group authorities in `JdbcDaoImpl`. +The table structure if groups are enabled is as follows. +You will need to adjust this schema to match the database dialect you are using. + +[source] +---- + +create table groups ( + id bigint generated by default as identity(start with 0) primary key, + group_name varchar_ignorecase(50) not null +); + +create table group_authorities ( + group_id bigint not null, + authority varchar(50) not null, + constraint fk_group_authorities_group foreign key(group_id) references groups(id) +); + +create table group_members ( + id bigint generated by default as identity(start with 0) primary key, + username varchar(50) not null, + group_id bigint not null, + constraint fk_group_members_group foreign key(group_id) references groups(id) +); +---- + +Remember that these tables are only required if you are using the provided JDBC `UserDetailsService` implementation. +If you write your own or choose to implement `AuthenticationProvider` without a `UserDetailsService`, then you have complete freedom over how you store the data, as long as the interface contract is satisfied. + + +=== Persistent Login (Remember-Me) Schema +This table is used to store data used by the more secure <> remember-me implementation. +If you are using `JdbcTokenRepositoryImpl` either directly or through the namespace, then you will need this table. +Remember to adjust this schema to match the database dialect you are using. + +[source] +---- + +create table persistent_logins ( + username varchar(64) not null, + series varchar(64) primary key, + token varchar(64) not null, + last_used timestamp not null +); + +---- + +[[dbschema-acl]] +=== ACL Schema +There are four tables used by the Spring Security <> implementation. + +. `acl_sid` stores the security identities recognised by the ACL system. +These can be unique principals or authorities which may apply to multiple principals. +. `acl_class` defines the domain object types to which ACLs apply. +The `class` column stores the Java class name of the object. +. `acl_object_identity` stores the object identity definitions of specific domai objects. +. `acl_entry` stores the ACL permissions which apply to a specific object identity and security identity. + +It is assumed that the database will auto-generate the primary keys for each of the identities. +The `JdbcMutableAclService` has to be able to retrieve these when it has created a new row in the `acl_sid` or `acl_class` tables. +It has two properties which define the SQL needed to retrieve these values `classIdentityQuery` and `sidIdentityQuery`. +Both of these default to `call identity()` + +The ACL artifact JAR contains files for creating the ACL schema in HyperSQL (HSQLDB), PostgreSQL, MySQL/MariaDB, Microsoft SQL Server, and Oracle Database. +These schemas are also demonstrated in the following sections. + +==== HyperSQL +The default schema works with the embedded HSQLDB database that is used in unit tests within the framework. + +[source,ddl] +---- + +create table acl_sid( + id bigint generated by default as identity(start with 100) not null primary key, + principal boolean not null, + sid varchar_ignorecase(100) not null, + constraint unique_uk_1 unique(sid,principal) +); + +create table acl_class( + id bigint generated by default as identity(start with 100) not null primary key, + class varchar_ignorecase(100) not null, + constraint unique_uk_2 unique(class) +); + +create table acl_object_identity( + id bigint generated by default as identity(start with 100) not null primary key, + object_id_class bigint not null, + object_id_identity varchar_ignorecase(36) not null, + parent_object bigint, + owner_sid bigint, + entries_inheriting boolean not null, + constraint unique_uk_3 unique(object_id_class,object_id_identity), + constraint foreign_fk_1 foreign key(parent_object)references acl_object_identity(id), + constraint foreign_fk_2 foreign key(object_id_class)references acl_class(id), + constraint foreign_fk_3 foreign key(owner_sid)references acl_sid(id) +); + +create table acl_entry( + id bigint generated by default as identity(start with 100) not null primary key, + acl_object_identity bigint not null, + ace_order int not null, + sid bigint not null, + mask integer not null, + granting boolean not null, + audit_success boolean not null, + audit_failure boolean not null, + constraint unique_uk_4 unique(acl_object_identity,ace_order), + constraint foreign_fk_4 foreign key(acl_object_identity) references acl_object_identity(id), + constraint foreign_fk_5 foreign key(sid) references acl_sid(id) +); +---- + +==== PostgreSQL +[source,ddl] +---- +create table acl_sid( + id bigserial not null primary key, + principal boolean not null, + sid varchar(100) not null, + constraint unique_uk_1 unique(sid,principal) +); + +create table acl_class( + id bigserial not null primary key, + class varchar(100) not null, + constraint unique_uk_2 unique(class) +); + +create table acl_object_identity( + id bigserial primary key, + object_id_class bigint not null, + object_id_identity varchar(36) not null, + parent_object bigint, + owner_sid bigint, + entries_inheriting boolean not null, + constraint unique_uk_3 unique(object_id_class,object_id_identity), + constraint foreign_fk_1 foreign key(parent_object)references acl_object_identity(id), + constraint foreign_fk_2 foreign key(object_id_class)references acl_class(id), + constraint foreign_fk_3 foreign key(owner_sid)references acl_sid(id) +); + +create table acl_entry( + id bigserial primary key, + acl_object_identity bigint not null, + ace_order int not null, + sid bigint not null, + mask integer not null, + granting boolean not null, + audit_success boolean not null, + audit_failure boolean not null, + constraint unique_uk_4 unique(acl_object_identity,ace_order), + constraint foreign_fk_4 foreign key(acl_object_identity) references acl_object_identity(id), + constraint foreign_fk_5 foreign key(sid) references acl_sid(id) +); +---- + +You will have to set the `classIdentityQuery` and `sidIdentityQuery` properties of `JdbcMutableAclService` to the following values, respectively: + +* `select currval(pg_get_serial_sequence('acl_class', 'id'))` +* `select currval(pg_get_serial_sequence('acl_sid', 'id'))` + +==== MySQL and MariaDB +[source,ddl] +---- +CREATE TABLE acl_sid ( + id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY, + principal BOOLEAN NOT NULL, + sid VARCHAR(100) NOT NULL, + UNIQUE KEY unique_acl_sid (sid, principal) +) ENGINE=InnoDB; + +CREATE TABLE acl_class ( + id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY, + class VARCHAR(100) NOT NULL, + UNIQUE KEY uk_acl_class (class) +) ENGINE=InnoDB; + +CREATE TABLE acl_object_identity ( + id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY, + object_id_class BIGINT UNSIGNED NOT NULL, + object_id_identity VARCHAR(36) NOT NULL, + parent_object BIGINT UNSIGNED, + owner_sid BIGINT UNSIGNED, + entries_inheriting BOOLEAN NOT NULL, + UNIQUE KEY uk_acl_object_identity (object_id_class, object_id_identity), + CONSTRAINT fk_acl_object_identity_parent FOREIGN KEY (parent_object) REFERENCES acl_object_identity (id), + CONSTRAINT fk_acl_object_identity_class FOREIGN KEY (object_id_class) REFERENCES acl_class (id), + CONSTRAINT fk_acl_object_identity_owner FOREIGN KEY (owner_sid) REFERENCES acl_sid (id) +) ENGINE=InnoDB; + +CREATE TABLE acl_entry ( + id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY, + acl_object_identity BIGINT UNSIGNED NOT NULL, + ace_order INTEGER NOT NULL, + sid BIGINT UNSIGNED NOT NULL, + mask INTEGER UNSIGNED NOT NULL, + granting BOOLEAN NOT NULL, + audit_success BOOLEAN NOT NULL, + audit_failure BOOLEAN NOT NULL, + UNIQUE KEY unique_acl_entry (acl_object_identity, ace_order), + CONSTRAINT fk_acl_entry_object FOREIGN KEY (acl_object_identity) REFERENCES acl_object_identity (id), + CONSTRAINT fk_acl_entry_acl FOREIGN KEY (sid) REFERENCES acl_sid (id) +) ENGINE=InnoDB; +---- + +==== Microsoft SQL Server +[source,ddl] +---- +CREATE TABLE acl_sid ( + id BIGINT NOT NULL IDENTITY PRIMARY KEY, + principal BIT NOT NULL, + sid VARCHAR(100) NOT NULL, + CONSTRAINT unique_acl_sid UNIQUE (sid, principal) +); + +CREATE TABLE acl_class ( + id BIGINT NOT NULL IDENTITY PRIMARY KEY, + class VARCHAR(100) NOT NULL, + CONSTRAINT uk_acl_class UNIQUE (class) +); + +CREATE TABLE acl_object_identity ( + id BIGINT NOT NULL IDENTITY PRIMARY KEY, + object_id_class BIGINT NOT NULL, + object_id_identity VARCHAR(36) NOT NULL, + parent_object BIGINT, + owner_sid BIGINT, + entries_inheriting BIT NOT NULL, + CONSTRAINT uk_acl_object_identity UNIQUE (object_id_class, object_id_identity), + CONSTRAINT fk_acl_object_identity_parent FOREIGN KEY (parent_object) REFERENCES acl_object_identity (id), + CONSTRAINT fk_acl_object_identity_class FOREIGN KEY (object_id_class) REFERENCES acl_class (id), + CONSTRAINT fk_acl_object_identity_owner FOREIGN KEY (owner_sid) REFERENCES acl_sid (id) +); + +CREATE TABLE acl_entry ( + id BIGINT NOT NULL IDENTITY PRIMARY KEY, + acl_object_identity BIGINT NOT NULL, + ace_order INTEGER NOT NULL, + sid BIGINT NOT NULL, + mask INTEGER NOT NULL, + granting BIT NOT NULL, + audit_success BIT NOT NULL, + audit_failure BIT NOT NULL, + CONSTRAINT unique_acl_entry UNIQUE (acl_object_identity, ace_order), + CONSTRAINT fk_acl_entry_object FOREIGN KEY (acl_object_identity) REFERENCES acl_object_identity (id), + CONSTRAINT fk_acl_entry_acl FOREIGN KEY (sid) REFERENCES acl_sid (id) +); +---- + +==== Oracle Database +[source,ddl] +---- +CREATE TABLE acl_sid ( + id NUMBER(38) NOT NULL PRIMARY KEY, + principal NUMBER(1) NOT NULL CHECK (principal in (0, 1)), + sid NVARCHAR2(100) NOT NULL, + CONSTRAINT unique_acl_sid UNIQUE (sid, principal) +); +CREATE SEQUENCE acl_sid_sequence START WITH 1 INCREMENT BY 1 NOMAXVALUE; +CREATE OR REPLACE TRIGGER acl_sid_id_trigger + BEFORE INSERT ON acl_sid + FOR EACH ROW +BEGIN + SELECT acl_sid_sequence.nextval INTO :new.id FROM dual; +END; + +CREATE TABLE acl_class ( + id NUMBER(38) NOT NULL PRIMARY KEY, + class NVARCHAR2(100) NOT NULL, + CONSTRAINT uk_acl_class UNIQUE (class) +); +CREATE SEQUENCE acl_class_sequence START WITH 1 INCREMENT BY 1 NOMAXVALUE; +CREATE OR REPLACE TRIGGER acl_class_id_trigger + BEFORE INSERT ON acl_class + FOR EACH ROW +BEGIN + SELECT acl_class_sequence.nextval INTO :new.id FROM dual; +END; + +CREATE TABLE acl_object_identity ( + id NUMBER(38) NOT NULL PRIMARY KEY, + object_id_class NUMBER(38) NOT NULL, + object_id_identity NVARCHAR2(36) NOT NULL, + parent_object NUMBER(38), + owner_sid NUMBER(38), + entries_inheriting NUMBER(1) NOT NULL CHECK (entries_inheriting in (0, 1)), + CONSTRAINT uk_acl_object_identity UNIQUE (object_id_class, object_id_identity), + CONSTRAINT fk_acl_object_identity_parent FOREIGN KEY (parent_object) REFERENCES acl_object_identity (id), + CONSTRAINT fk_acl_object_identity_class FOREIGN KEY (object_id_class) REFERENCES acl_class (id), + CONSTRAINT fk_acl_object_identity_owner FOREIGN KEY (owner_sid) REFERENCES acl_sid (id) +); +CREATE SEQUENCE acl_object_identity_sequence START WITH 1 INCREMENT BY 1 NOMAXVALUE; +CREATE OR REPLACE TRIGGER acl_object_identity_id_trigger + BEFORE INSERT ON acl_object_identity + FOR EACH ROW +BEGIN + SELECT acl_object_identity_sequence.nextval INTO :new.id FROM dual; +END; + +CREATE TABLE acl_entry ( + id NUMBER(38) NOT NULL PRIMARY KEY, + acl_object_identity NUMBER(38) NOT NULL, + ace_order INTEGER NOT NULL, + sid NUMBER(38) NOT NULL, + mask INTEGER NOT NULL, + granting NUMBER(1) NOT NULL CHECK (granting in (0, 1)), + audit_success NUMBER(1) NOT NULL CHECK (audit_success in (0, 1)), + audit_failure NUMBER(1) NOT NULL CHECK (audit_failure in (0, 1)), + CONSTRAINT unique_acl_entry UNIQUE (acl_object_identity, ace_order), + CONSTRAINT fk_acl_entry_object FOREIGN KEY (acl_object_identity) REFERENCES acl_object_identity (id), + CONSTRAINT fk_acl_entry_acl FOREIGN KEY (sid) REFERENCES acl_sid (id) +); +CREATE SEQUENCE acl_entry_sequence START WITH 1 INCREMENT BY 1 NOMAXVALUE; +CREATE OR REPLACE TRIGGER acl_entry_id_trigger + BEFORE INSERT ON acl_entry + FOR EACH ROW +BEGIN + SELECT acl_entry_sequence.nextval INTO :new.id FROM dual; +END; +---- diff --git a/docs/manual/src/docs/asciidoc/_includes/appendix/dependencies.adoc b/docs/manual/src/docs/asciidoc/_includes/appendix/dependencies.adoc new file mode 100644 index 0000000000..40bbd8d130 --- /dev/null +++ b/docs/manual/src/docs/asciidoc/_includes/appendix/dependencies.adoc @@ -0,0 +1,261 @@ + + +[[appendix-dependencies]] +== Spring Security Dependencies +This appendix provides a reference of the modules in Spring Security and the additional dependencies that they require in order to function in a running application. +We don't include dependencies that are only used when building or testing Spring Security itself. +Nor do we include transitive dependencies which are required by external dependencies. + +The version of Spring required is listed on the project website, so the specific versions are omitted for Spring dependencies below. +Note that some of the dependencies listed as "optional" below may still be required for other non-security functionality in a Spring application. +Also dependencies listed as "optional" may not actually be marked as such in the project's Maven POM files if they are used in most applications. +They are "optional" only in the sense that you don't need them unless you are using the specified functionality. + +Where a module depends on another Spring Security module, the non-optional dependencies of the module it depends on are also assumed to be required and are not listed separately. + + +=== spring-security-core + +The core module must be included in any project using Spring Security. + +.Core Dependencies +|=== +| Dependency | Version | Description + +| ehcache +| 1.6.2 +| Required if the Ehcache-based user cache implementation is used (optional). + +| spring-aop +| +| Method security is based on Spring AOP + +| spring-beans +| +| Required for Spring configuration + +| spring-expression +| +| Required for expression-based method security (optional) + +| spring-jdbc +| +| Required if using a database to store user data (optional). + +| spring-tx +| +| Required if using a database to store user data (optional). + +| aspectjrt +| 1.6.10 +| Required if using AspectJ support (optional). + +| jsr250-api +| 1.0 +| Required if you are using JSR-250 method-security annotations (optional). +|=== + +=== spring-security-remoting +This module is typically required in web applications which use the Servlet API. + +.Remoting Dependencies +|=== +| Dependency | Version | Description + +| spring-security-core +| +| + +| spring-web +| +| Required for clients which use HTTP remoting support. +|=== + +=== spring-security-web +This module is typically required in web applications which use the Servlet API. + +.Web Dependencies +|=== +| Dependency | Version | Description + +| spring-security-core +| +| + +| spring-web +| +| Spring web support classes are used extensively. + +| spring-jdbc +| +| Required for JDBC-based persistent remember-me token repository (optional). + +| spring-tx +| +| Required by remember-me persistent token repository implementations (optional). +|=== + +=== spring-security-ldap +This module is only required if you are using LDAP authentication. + +.LDAP Dependencies +|=== +| Dependency | Version | Description + +| spring-security-core +| +| + +| spring-ldap-core +| 1.3.0 +| LDAP support is based on Spring LDAP. + +| spring-tx +| +| Data exception classes are required. + +| apache-ds footnote:[The modules `apacheds-core`, `apacheds-core-entry`, `apacheds-protocol-shared`, `apacheds-protocol-ldap` and `apacheds-server-jndi` are required. +] +| 1.5.5 +| Required if you are using an embedded LDAP server (optional). + +| shared-ldap +| 0.9.15 +| Required if you are using an embedded LDAP server (optional). + +| ldapsdk +| 4.1 +| Mozilla LdapSDK. +Used for decoding LDAP password policy controls if you are using password-policy functionality with OpenLDAP, for example. +|=== + + +=== spring-security-config +This module is required if you are using Spring Security namespace configuration. + +.Config Dependencies +|=== +| Dependency | Version | Description + +| spring-security-core +| +| + +| spring-security-web +| +| Required if you are using any web-related namespace configuration (optional). + +| spring-security-ldap +| +| Required if you are using the LDAP namespace options (optional). + +| spring-security-openid +| +| Required if you are using OpenID authentication (optional). + +| aspectjweaver +| 1.6.10 +| Required if using the protect-pointcut namespace syntax (optional). +|=== + + +=== spring-security-acl +The ACL module. + +.ACL Dependencies +|=== +| Dependency | Version | Description + +| spring-security-core +| +| + +| ehcache +| 1.6.2 +| Required if the Ehcache-based ACL cache implementation is used (optional if you are using your own implementation). + +| spring-jdbc +| +| Required if you are using the default JDBC-based AclService (optional if you implement your own). + +| spring-tx +| +| Required if you are using the default JDBC-based AclService (optional if you implement your own). +|=== + +=== spring-security-cas +The CAS module provides integration with JA-SIG CAS. + +.CAS Dependencies +|=== +| Dependency | Version | Description + +| spring-security-core +| +| + +| spring-security-web +| +| + +| cas-client-core +| 3.1.12 +| The JA-SIG CAS Client. +This is the basis of the Spring Security integration. + +| ehcache +| 1.6.2 +| Required if you are using the Ehcache-based ticket cache (optional). +|=== + +=== spring-security-openid +The OpenID module. + +.OpenID Dependencies +|=== +| Dependency | Version | Description + +| spring-security-core +| +| + +| spring-security-web +| +| + +| openid4java-nodeps +| 0.9.6 +| Spring Security's OpenID integration uses OpenID4Java. + +| httpclient +| 4.1.1 +| openid4java-nodeps depends on HttpClient 4. + +| guice +| 2.0 +| openid4java-nodeps depends on Guice 2. +|=== + +=== spring-security-taglibs +Provides Spring Security's JSP tag implementations. + +.Taglib Dependencies +|=== +| Dependency | Version | Description + +| spring-security-core +| +| + +| spring-security-web +| +| + +| spring-security-acl +| +| Required if you are using the `accesscontrollist` tag or `hasPermission()` expressions with ACLs (optional). + +| spring-expression +| +| Required if you are using SPEL expressions in your tag access constraints. +|=== diff --git a/docs/manual/src/docs/asciidoc/_includes/faq.adoc b/docs/manual/src/docs/asciidoc/_includes/appendix/faq.adoc similarity index 100% rename from docs/manual/src/docs/asciidoc/_includes/faq.adoc rename to docs/manual/src/docs/asciidoc/_includes/appendix/faq.adoc diff --git a/docs/manual/src/docs/asciidoc/_includes/appendix/index.adoc b/docs/manual/src/docs/asciidoc/_includes/appendix/index.adoc new file mode 100644 index 0000000000..9c711172b8 --- /dev/null +++ b/docs/manual/src/docs/asciidoc/_includes/appendix/index.adoc @@ -0,0 +1,12 @@ + += Appendix + +include::database-schema.adoc[] + +include::namespace.adoc[] + +include::dependencies.adoc[] + +include::proxy-server.adoc[] + +include::faq.adoc[] diff --git a/docs/manual/src/docs/asciidoc/_includes/appendix.adoc b/docs/manual/src/docs/asciidoc/_includes/appendix/namespace.adoc similarity index 83% rename from docs/manual/src/docs/asciidoc/_includes/appendix.adoc rename to docs/manual/src/docs/asciidoc/_includes/appendix/namespace.adoc index 67137d3161..cc6c3a2bb8 100644 --- a/docs/manual/src/docs/asciidoc/_includes/appendix.adoc +++ b/docs/manual/src/docs/asciidoc/_includes/appendix/namespace.adoc @@ -1,359 +1,3 @@ - -= Appendix - -[[appendix-schema]] -== Security Database Schema -There are various database schema used by the framework and this appendix provides a single reference point to them all. -You only need to provide the tables for the areas of functionality you require. - -DDL statements are given for the HSQLDB database. -You can use these as a guideline for defining the schema for the database you are using. - - -=== User Schema -The standard JDBC implementation of the `UserDetailsService` (`JdbcDaoImpl`) requires tables to load the password, account status (enabled or disabled) and a list of authorities (roles) for the user. -You will need to adjust this schema to match the database dialect you are using. - -[source] ----- - -create table users( - username varchar_ignorecase(50) not null primary key, - password varchar_ignorecase(50) not null, - enabled boolean not null -); - -create table authorities ( - username varchar_ignorecase(50) not null, - authority varchar_ignorecase(50) not null, - constraint fk_authorities_users foreign key(username) references users(username) -); -create unique index ix_auth_username on authorities (username,authority); ----- - -==== Group Authorities -Spring Security 2.0 introduced support for group authorities in `JdbcDaoImpl`. -The table structure if groups are enabled is as follows. -You will need to adjust this schema to match the database dialect you are using. - -[source] ----- - -create table groups ( - id bigint generated by default as identity(start with 0) primary key, - group_name varchar_ignorecase(50) not null -); - -create table group_authorities ( - group_id bigint not null, - authority varchar(50) not null, - constraint fk_group_authorities_group foreign key(group_id) references groups(id) -); - -create table group_members ( - id bigint generated by default as identity(start with 0) primary key, - username varchar(50) not null, - group_id bigint not null, - constraint fk_group_members_group foreign key(group_id) references groups(id) -); ----- - -Remember that these tables are only required if you are using the provided JDBC `UserDetailsService` implementation. -If you write your own or choose to implement `AuthenticationProvider` without a `UserDetailsService`, then you have complete freedom over how you store the data, as long as the interface contract is satisfied. - - -=== Persistent Login (Remember-Me) Schema -This table is used to store data used by the more secure <> remember-me implementation. -If you are using `JdbcTokenRepositoryImpl` either directly or through the namespace, then you will need this table. -Remember to adjust this schema to match the database dialect you are using. - -[source] ----- - -create table persistent_logins ( - username varchar(64) not null, - series varchar(64) primary key, - token varchar(64) not null, - last_used timestamp not null -); - ----- - -[[dbschema-acl]] -=== ACL Schema -There are four tables used by the Spring Security <> implementation. - -. `acl_sid` stores the security identities recognised by the ACL system. -These can be unique principals or authorities which may apply to multiple principals. -. `acl_class` defines the domain object types to which ACLs apply. -The `class` column stores the Java class name of the object. -. `acl_object_identity` stores the object identity definitions of specific domai objects. -. `acl_entry` stores the ACL permissions which apply to a specific object identity and security identity. - -It is assumed that the database will auto-generate the primary keys for each of the identities. -The `JdbcMutableAclService` has to be able to retrieve these when it has created a new row in the `acl_sid` or `acl_class` tables. -It has two properties which define the SQL needed to retrieve these values `classIdentityQuery` and `sidIdentityQuery`. -Both of these default to `call identity()` - -The ACL artifact JAR contains files for creating the ACL schema in HyperSQL (HSQLDB), PostgreSQL, MySQL/MariaDB, Microsoft SQL Server, and Oracle Database. -These schemas are also demonstrated in the following sections. - -==== HyperSQL -The default schema works with the embedded HSQLDB database that is used in unit tests within the framework. - -[source,ddl] ----- - -create table acl_sid( - id bigint generated by default as identity(start with 100) not null primary key, - principal boolean not null, - sid varchar_ignorecase(100) not null, - constraint unique_uk_1 unique(sid,principal) -); - -create table acl_class( - id bigint generated by default as identity(start with 100) not null primary key, - class varchar_ignorecase(100) not null, - constraint unique_uk_2 unique(class) -); - -create table acl_object_identity( - id bigint generated by default as identity(start with 100) not null primary key, - object_id_class bigint not null, - object_id_identity varchar_ignorecase(36) not null, - parent_object bigint, - owner_sid bigint, - entries_inheriting boolean not null, - constraint unique_uk_3 unique(object_id_class,object_id_identity), - constraint foreign_fk_1 foreign key(parent_object)references acl_object_identity(id), - constraint foreign_fk_2 foreign key(object_id_class)references acl_class(id), - constraint foreign_fk_3 foreign key(owner_sid)references acl_sid(id) -); - -create table acl_entry( - id bigint generated by default as identity(start with 100) not null primary key, - acl_object_identity bigint not null, - ace_order int not null, - sid bigint not null, - mask integer not null, - granting boolean not null, - audit_success boolean not null, - audit_failure boolean not null, - constraint unique_uk_4 unique(acl_object_identity,ace_order), - constraint foreign_fk_4 foreign key(acl_object_identity) references acl_object_identity(id), - constraint foreign_fk_5 foreign key(sid) references acl_sid(id) -); ----- - -==== PostgreSQL -[source,ddl] ----- -create table acl_sid( - id bigserial not null primary key, - principal boolean not null, - sid varchar(100) not null, - constraint unique_uk_1 unique(sid,principal) -); - -create table acl_class( - id bigserial not null primary key, - class varchar(100) not null, - constraint unique_uk_2 unique(class) -); - -create table acl_object_identity( - id bigserial primary key, - object_id_class bigint not null, - object_id_identity varchar(36) not null, - parent_object bigint, - owner_sid bigint, - entries_inheriting boolean not null, - constraint unique_uk_3 unique(object_id_class,object_id_identity), - constraint foreign_fk_1 foreign key(parent_object)references acl_object_identity(id), - constraint foreign_fk_2 foreign key(object_id_class)references acl_class(id), - constraint foreign_fk_3 foreign key(owner_sid)references acl_sid(id) -); - -create table acl_entry( - id bigserial primary key, - acl_object_identity bigint not null, - ace_order int not null, - sid bigint not null, - mask integer not null, - granting boolean not null, - audit_success boolean not null, - audit_failure boolean not null, - constraint unique_uk_4 unique(acl_object_identity,ace_order), - constraint foreign_fk_4 foreign key(acl_object_identity) references acl_object_identity(id), - constraint foreign_fk_5 foreign key(sid) references acl_sid(id) -); ----- - -You will have to set the `classIdentityQuery` and `sidIdentityQuery` properties of `JdbcMutableAclService` to the following values, respectively: - -* `select currval(pg_get_serial_sequence('acl_class', 'id'))` -* `select currval(pg_get_serial_sequence('acl_sid', 'id'))` - -==== MySQL and MariaDB -[source,ddl] ----- -CREATE TABLE acl_sid ( - id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY, - principal BOOLEAN NOT NULL, - sid VARCHAR(100) NOT NULL, - UNIQUE KEY unique_acl_sid (sid, principal) -) ENGINE=InnoDB; - -CREATE TABLE acl_class ( - id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY, - class VARCHAR(100) NOT NULL, - UNIQUE KEY uk_acl_class (class) -) ENGINE=InnoDB; - -CREATE TABLE acl_object_identity ( - id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY, - object_id_class BIGINT UNSIGNED NOT NULL, - object_id_identity VARCHAR(36) NOT NULL, - parent_object BIGINT UNSIGNED, - owner_sid BIGINT UNSIGNED, - entries_inheriting BOOLEAN NOT NULL, - UNIQUE KEY uk_acl_object_identity (object_id_class, object_id_identity), - CONSTRAINT fk_acl_object_identity_parent FOREIGN KEY (parent_object) REFERENCES acl_object_identity (id), - CONSTRAINT fk_acl_object_identity_class FOREIGN KEY (object_id_class) REFERENCES acl_class (id), - CONSTRAINT fk_acl_object_identity_owner FOREIGN KEY (owner_sid) REFERENCES acl_sid (id) -) ENGINE=InnoDB; - -CREATE TABLE acl_entry ( - id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY, - acl_object_identity BIGINT UNSIGNED NOT NULL, - ace_order INTEGER NOT NULL, - sid BIGINT UNSIGNED NOT NULL, - mask INTEGER UNSIGNED NOT NULL, - granting BOOLEAN NOT NULL, - audit_success BOOLEAN NOT NULL, - audit_failure BOOLEAN NOT NULL, - UNIQUE KEY unique_acl_entry (acl_object_identity, ace_order), - CONSTRAINT fk_acl_entry_object FOREIGN KEY (acl_object_identity) REFERENCES acl_object_identity (id), - CONSTRAINT fk_acl_entry_acl FOREIGN KEY (sid) REFERENCES acl_sid (id) -) ENGINE=InnoDB; ----- - -==== Microsoft SQL Server -[source,ddl] ----- -CREATE TABLE acl_sid ( - id BIGINT NOT NULL IDENTITY PRIMARY KEY, - principal BIT NOT NULL, - sid VARCHAR(100) NOT NULL, - CONSTRAINT unique_acl_sid UNIQUE (sid, principal) -); - -CREATE TABLE acl_class ( - id BIGINT NOT NULL IDENTITY PRIMARY KEY, - class VARCHAR(100) NOT NULL, - CONSTRAINT uk_acl_class UNIQUE (class) -); - -CREATE TABLE acl_object_identity ( - id BIGINT NOT NULL IDENTITY PRIMARY KEY, - object_id_class BIGINT NOT NULL, - object_id_identity VARCHAR(36) NOT NULL, - parent_object BIGINT, - owner_sid BIGINT, - entries_inheriting BIT NOT NULL, - CONSTRAINT uk_acl_object_identity UNIQUE (object_id_class, object_id_identity), - CONSTRAINT fk_acl_object_identity_parent FOREIGN KEY (parent_object) REFERENCES acl_object_identity (id), - CONSTRAINT fk_acl_object_identity_class FOREIGN KEY (object_id_class) REFERENCES acl_class (id), - CONSTRAINT fk_acl_object_identity_owner FOREIGN KEY (owner_sid) REFERENCES acl_sid (id) -); - -CREATE TABLE acl_entry ( - id BIGINT NOT NULL IDENTITY PRIMARY KEY, - acl_object_identity BIGINT NOT NULL, - ace_order INTEGER NOT NULL, - sid BIGINT NOT NULL, - mask INTEGER NOT NULL, - granting BIT NOT NULL, - audit_success BIT NOT NULL, - audit_failure BIT NOT NULL, - CONSTRAINT unique_acl_entry UNIQUE (acl_object_identity, ace_order), - CONSTRAINT fk_acl_entry_object FOREIGN KEY (acl_object_identity) REFERENCES acl_object_identity (id), - CONSTRAINT fk_acl_entry_acl FOREIGN KEY (sid) REFERENCES acl_sid (id) -); ----- - -==== Oracle Database -[source,ddl] ----- -CREATE TABLE acl_sid ( - id NUMBER(38) NOT NULL PRIMARY KEY, - principal NUMBER(1) NOT NULL CHECK (principal in (0, 1)), - sid NVARCHAR2(100) NOT NULL, - CONSTRAINT unique_acl_sid UNIQUE (sid, principal) -); -CREATE SEQUENCE acl_sid_sequence START WITH 1 INCREMENT BY 1 NOMAXVALUE; -CREATE OR REPLACE TRIGGER acl_sid_id_trigger - BEFORE INSERT ON acl_sid - FOR EACH ROW -BEGIN - SELECT acl_sid_sequence.nextval INTO :new.id FROM dual; -END; - -CREATE TABLE acl_class ( - id NUMBER(38) NOT NULL PRIMARY KEY, - class NVARCHAR2(100) NOT NULL, - CONSTRAINT uk_acl_class UNIQUE (class) -); -CREATE SEQUENCE acl_class_sequence START WITH 1 INCREMENT BY 1 NOMAXVALUE; -CREATE OR REPLACE TRIGGER acl_class_id_trigger - BEFORE INSERT ON acl_class - FOR EACH ROW -BEGIN - SELECT acl_class_sequence.nextval INTO :new.id FROM dual; -END; - -CREATE TABLE acl_object_identity ( - id NUMBER(38) NOT NULL PRIMARY KEY, - object_id_class NUMBER(38) NOT NULL, - object_id_identity NVARCHAR2(36) NOT NULL, - parent_object NUMBER(38), - owner_sid NUMBER(38), - entries_inheriting NUMBER(1) NOT NULL CHECK (entries_inheriting in (0, 1)), - CONSTRAINT uk_acl_object_identity UNIQUE (object_id_class, object_id_identity), - CONSTRAINT fk_acl_object_identity_parent FOREIGN KEY (parent_object) REFERENCES acl_object_identity (id), - CONSTRAINT fk_acl_object_identity_class FOREIGN KEY (object_id_class) REFERENCES acl_class (id), - CONSTRAINT fk_acl_object_identity_owner FOREIGN KEY (owner_sid) REFERENCES acl_sid (id) -); -CREATE SEQUENCE acl_object_identity_sequence START WITH 1 INCREMENT BY 1 NOMAXVALUE; -CREATE OR REPLACE TRIGGER acl_object_identity_id_trigger - BEFORE INSERT ON acl_object_identity - FOR EACH ROW -BEGIN - SELECT acl_object_identity_sequence.nextval INTO :new.id FROM dual; -END; - -CREATE TABLE acl_entry ( - id NUMBER(38) NOT NULL PRIMARY KEY, - acl_object_identity NUMBER(38) NOT NULL, - ace_order INTEGER NOT NULL, - sid NUMBER(38) NOT NULL, - mask INTEGER NOT NULL, - granting NUMBER(1) NOT NULL CHECK (granting in (0, 1)), - audit_success NUMBER(1) NOT NULL CHECK (audit_success in (0, 1)), - audit_failure NUMBER(1) NOT NULL CHECK (audit_failure in (0, 1)), - CONSTRAINT unique_acl_entry UNIQUE (acl_object_identity, ace_order), - CONSTRAINT fk_acl_entry_object FOREIGN KEY (acl_object_identity) REFERENCES acl_object_identity (id), - CONSTRAINT fk_acl_entry_acl FOREIGN KEY (sid) REFERENCES acl_sid (id) -); -CREATE SEQUENCE acl_entry_sequence START WITH 1 INCREMENT BY 1 NOMAXVALUE; -CREATE OR REPLACE TRIGGER acl_entry_id_trigger - BEFORE INSERT ON acl_entry - FOR EACH ROW -BEGIN - SELECT acl_entry_sequence.nextval INTO :new.id FROM dual; -END; ----- - [[appendix-namespace]] == The Security Namespace This appendix provides a reference to the elements available in the security namespace and information on the underlying beans they create (a knowledge of the individual classes and how they work together is assumed - you can find more information in the project Javadoc and elsewhere in this document). @@ -2965,268 +2609,3 @@ Only used with a 'user-search-filter'. The LDAP filter used to search for users (optional). For example "(uid={0})". The substituted parameter is the user's login name. - - -[[appendix-dependencies]] -== Spring Security Dependencies -This appendix provides a reference of the modules in Spring Security and the additional dependencies that they require in order to function in a running application. -We don't include dependencies that are only used when building or testing Spring Security itself. -Nor do we include transitive dependencies which are required by external dependencies. - -The version of Spring required is listed on the project website, so the specific versions are omitted for Spring dependencies below. -Note that some of the dependencies listed as "optional" below may still be required for other non-security functionality in a Spring application. -Also dependencies listed as "optional" may not actually be marked as such in the project's Maven POM files if they are used in most applications. -They are "optional" only in the sense that you don't need them unless you are using the specified functionality. - -Where a module depends on another Spring Security module, the non-optional dependencies of the module it depends on are also assumed to be required and are not listed separately. - - -=== spring-security-core - -The core module must be included in any project using Spring Security. - -.Core Dependencies -|=== -| Dependency | Version | Description - -| ehcache -| 1.6.2 -| Required if the Ehcache-based user cache implementation is used (optional). - -| spring-aop -| -| Method security is based on Spring AOP - -| spring-beans -| -| Required for Spring configuration - -| spring-expression -| -| Required for expression-based method security (optional) - -| spring-jdbc -| -| Required if using a database to store user data (optional). - -| spring-tx -| -| Required if using a database to store user data (optional). - -| aspectjrt -| 1.6.10 -| Required if using AspectJ support (optional). - -| jsr250-api -| 1.0 -| Required if you are using JSR-250 method-security annotations (optional). -|=== - -=== spring-security-remoting -This module is typically required in web applications which use the Servlet API. - -.Remoting Dependencies -|=== -| Dependency | Version | Description - -| spring-security-core -| -| - -| spring-web -| -| Required for clients which use HTTP remoting support. -|=== - -=== spring-security-web -This module is typically required in web applications which use the Servlet API. - -.Web Dependencies -|=== -| Dependency | Version | Description - -| spring-security-core -| -| - -| spring-web -| -| Spring web support classes are used extensively. - -| spring-jdbc -| -| Required for JDBC-based persistent remember-me token repository (optional). - -| spring-tx -| -| Required by remember-me persistent token repository implementations (optional). -|=== - -=== spring-security-ldap -This module is only required if you are using LDAP authentication. - -.LDAP Dependencies -|=== -| Dependency | Version | Description - -| spring-security-core -| -| - -| spring-ldap-core -| 1.3.0 -| LDAP support is based on Spring LDAP. - -| spring-tx -| -| Data exception classes are required. - -| apache-ds footnote:[The modules `apacheds-core`, `apacheds-core-entry`, `apacheds-protocol-shared`, `apacheds-protocol-ldap` and `apacheds-server-jndi` are required. -] -| 1.5.5 -| Required if you are using an embedded LDAP server (optional). - -| shared-ldap -| 0.9.15 -| Required if you are using an embedded LDAP server (optional). - -| ldapsdk -| 4.1 -| Mozilla LdapSDK. -Used for decoding LDAP password policy controls if you are using password-policy functionality with OpenLDAP, for example. -|=== - - -=== spring-security-config -This module is required if you are using Spring Security namespace configuration. - -.Config Dependencies -|=== -| Dependency | Version | Description - -| spring-security-core -| -| - -| spring-security-web -| -| Required if you are using any web-related namespace configuration (optional). - -| spring-security-ldap -| -| Required if you are using the LDAP namespace options (optional). - -| spring-security-openid -| -| Required if you are using OpenID authentication (optional). - -| aspectjweaver -| 1.6.10 -| Required if using the protect-pointcut namespace syntax (optional). -|=== - - -=== spring-security-acl -The ACL module. - -.ACL Dependencies -|=== -| Dependency | Version | Description - -| spring-security-core -| -| - -| ehcache -| 1.6.2 -| Required if the Ehcache-based ACL cache implementation is used (optional if you are using your own implementation). - -| spring-jdbc -| -| Required if you are using the default JDBC-based AclService (optional if you implement your own). - -| spring-tx -| -| Required if you are using the default JDBC-based AclService (optional if you implement your own). -|=== - -=== spring-security-cas -The CAS module provides integration with JA-SIG CAS. - -.CAS Dependencies -|=== -| Dependency | Version | Description - -| spring-security-core -| -| - -| spring-security-web -| -| - -| cas-client-core -| 3.1.12 -| The JA-SIG CAS Client. -This is the basis of the Spring Security integration. - -| ehcache -| 1.6.2 -| Required if you are using the Ehcache-based ticket cache (optional). -|=== - -=== spring-security-openid -The OpenID module. - -.OpenID Dependencies -|=== -| Dependency | Version | Description - -| spring-security-core -| -| - -| spring-security-web -| -| - -| openid4java-nodeps -| 0.9.6 -| Spring Security's OpenID integration uses OpenID4Java. - -| httpclient -| 4.1.1 -| openid4java-nodeps depends on HttpClient 4. - -| guice -| 2.0 -| openid4java-nodeps depends on Guice 2. -|=== - -=== spring-security-taglibs -Provides Spring Security's JSP tag implementations. - -.Taglib Dependencies -|=== -| Dependency | Version | Description - -| spring-security-core -| -| - -| spring-security-web -| -| - -| spring-security-acl -| -| Required if you are using the `accesscontrollist` tag or `hasPermission()` expressions with ACLs (optional). - -| spring-expression -| -| Required if you are using SPEL expressions in your tag access constraints. -|=== - -include::proxy-server.adoc[] - -include::faq.adoc[] diff --git a/docs/manual/src/docs/asciidoc/_includes/proxy-server.adoc b/docs/manual/src/docs/asciidoc/_includes/appendix/proxy-server.adoc similarity index 100% rename from docs/manual/src/docs/asciidoc/_includes/proxy-server.adoc rename to docs/manual/src/docs/asciidoc/_includes/appendix/proxy-server.adoc diff --git a/docs/manual/src/docs/asciidoc/index.adoc b/docs/manual/src/docs/asciidoc/index.adoc index 2bfa2bc72b..f9cb7cbaff 100644 --- a/docs/manual/src/docs/asciidoc/index.adoc +++ b/docs/manual/src/docs/asciidoc/index.adoc @@ -20,6 +20,6 @@ include::{include-dir}/additional-topics/index.adoc[] include::{include-dir}/data/index.adoc[] -include::{include-dir}/appendix.adoc[] +include::{include-dir}/appendix/index.adoc[]