Rewrite Preface
Issue gh-2567 Co-authored-by: Jay Bryant <jbryant@pivotal.io> Co-authored-by: Rob Winch <rwinch@users.noreply.github.com>
This commit is contained in:
Josh Cummings
parent
f832d08814
commit
25b5f48884
|
|
@ -0,0 +1,37 @@
|
|||
[[community]]
|
||||
= Spring Security Community
|
||||
|
||||
Welcome to the Spring Security Community!
|
||||
This section discusses how you can make the most of our vast community.
|
||||
|
||||
|
||||
[[community-help]]
|
||||
== Getting Help
|
||||
If you need help with Spring Security, we are here to help.
|
||||
The following are some of the best ways to get help:
|
||||
|
||||
* Read through this documentation.
|
||||
* Try one of our many <<samples,sample applications>>.
|
||||
* Ask a question on https://stackoverflow.com/questions/tagged/spring-security[https://stackoverflow.com] with the `spring-security` tag.
|
||||
* Report bugs and enhancement requests at https://github.com/spring-projects/spring-security/issues
|
||||
|
||||
[[community-becoming-involved]]
|
||||
== Becoming Involved
|
||||
We welcome your involvement in the Spring Security project.
|
||||
There are many ways to contribute, including answering questions on StackOverflow, writing new code, improving existing code, assisting with documentation, developing samples or tutorials, reporting bugs, or simply making suggestions.
|
||||
For more information, see our https://github.com/spring-projects/spring-security/blob/master/CONTRIBUTING.md[Contributing] documentation.
|
||||
|
||||
[[community-source]]
|
||||
== Source Code
|
||||
|
||||
You can find Spring Security's source code on GitHub at https://github.com/spring-projects/spring-security/
|
||||
|
||||
[[community-license]]
|
||||
== Apache 2 License
|
||||
|
||||
Spring Security is Open Source software released under the https://www.apache.org/licenses/LICENSE-2.0.html[Apache 2.0 license].
|
||||
|
||||
== Social Media
|
||||
|
||||
You can follow https://twitter.com/SpringSecurity[@SpringSecurity] and the https://twitter.com/SpringSecurity/lists/team[Spring Security team] on Twitter to stay up to date with the latest news.
|
||||
You can also follow https://twitter.com/SpringCentral[@SpringCentral] to keep up to date with the entire Spring portfolio.
|
||||
|
|
@ -0,0 +1,344 @@
|
|||
[[getting]]
|
||||
= Getting Spring Security
|
||||
|
||||
This section discusses all you need to know about getting the Spring Security binaries.
|
||||
See <<community-source>> for how to obtain the source code.
|
||||
|
||||
== Release Numbering
|
||||
|
||||
Spring Security versions are formatted as MAJOR.MINOR.PATCH such that:
|
||||
|
||||
* MAJOR versions may contain breaking changes.
|
||||
Typically, these are done to provide improved security to match modern security practices.
|
||||
* MINOR versions contain enhancements but are considered passive updates
|
||||
* PATCH level should be perfectly compatible, forwards and backwards, with the possible exception of changes that fix bugs.
|
||||
|
||||
|
||||
[[maven]]
|
||||
== Usage with Maven
|
||||
|
||||
As most open source projects, Spring Security deploys its dependencies as Maven artifacts.
|
||||
The topics in this section provide detail on how to consume Spring Security when using Maven.
|
||||
|
||||
[[getting-maven-boot]]
|
||||
=== Spring Boot with Maven
|
||||
|
||||
Spring Boot provides a `spring-boot-starter-security` starter that aggregates Spring Security-related dependencies together.
|
||||
The simplest and preferred way to use the starter is to use https://docs.spring.io/initializr/docs/current/reference/htmlsingle/[Spring Initializr] by using an IDE integration (http://joshlong.com/jl/blogPost/tech_tip_geting_started_with_spring_boot.html[Eclipse], https://www.jetbrains.com/help/idea/spring-boot.html#d1489567e2[IntelliJ], https://github.com/AlexFalappa/nb-springboot/wiki/Quick-Tour[NetBeans]) or through https://start.spring.io.
|
||||
|
||||
Alternatively, you can manually add the starter, as the following example shows:
|
||||
|
||||
|
||||
.pom.xml
|
||||
====
|
||||
[source,xml]
|
||||
[subs="verbatim,attributes"]
|
||||
----
|
||||
<dependencies>
|
||||
<!-- ... other dependency elements ... -->
|
||||
<dependency>
|
||||
<groupId>org.springframework.boot</groupId>
|
||||
<artifactId>spring-boot-starter-security</artifactId>
|
||||
</dependency>
|
||||
</dependencies>
|
||||
----
|
||||
====
|
||||
|
||||
Since Spring Boot provides a Maven BOM to manage dependency versions, you do not need to specify a version.
|
||||
If you wish to override the Spring Security version, you may do so by providing a Maven property, as the following example shows:
|
||||
|
||||
.pom.xml
|
||||
====
|
||||
[source,xml]
|
||||
[subs="verbatim,attributes"]
|
||||
----
|
||||
<properties>
|
||||
<!-- ... -->
|
||||
<spring-security.version>{spring-security-version}</spring-security.version>
|
||||
</dependencies>
|
||||
----
|
||||
====
|
||||
|
||||
Since Spring Security makes breaking changes only in major releases, it is safe to use a newer version of Spring Security with Spring Boot.
|
||||
However, at times, you may need to update the version of Spring Framework as well.
|
||||
You can do so by adding a Maven property, as the following example shows:
|
||||
|
||||
.pom.xml
|
||||
====
|
||||
[source,xml]
|
||||
[subs="verbatim,attributes"]
|
||||
----
|
||||
<properties>
|
||||
<!-- ... -->
|
||||
<spring.version>{spring-version}</spring.version>
|
||||
</dependencies>
|
||||
----
|
||||
====
|
||||
|
||||
If you use additional features (such as LDAP, OpenID, and others), you need to also include the appropriate <<modules>>.
|
||||
|
||||
=== Maven Without Spring Boot
|
||||
|
||||
When you use Spring Security without Spring Boot, the preferred way is to use Spring Security's BOM to ensure a consistent version of Spring Security is used throughout the entire project. The following example shows how to do so:
|
||||
|
||||
.pom.xml
|
||||
====
|
||||
[source,xml]
|
||||
[subs="verbatim,attributes"]
|
||||
----
|
||||
<dependencyManagement>
|
||||
<dependencies>
|
||||
<!-- ... other dependency elements ... -->
|
||||
<dependency>
|
||||
<groupId>org.springframework.security</groupId>
|
||||
<artifactId>spring-security-bom</artifactId>
|
||||
<version>{spring-security-version}</version>
|
||||
<type>pom</type>
|
||||
<scope>import</scope>
|
||||
</dependency>
|
||||
</dependencies>
|
||||
</dependencyManagement>
|
||||
----
|
||||
====
|
||||
|
||||
A minimal Spring Security Maven set of dependencies typically looks like the following:
|
||||
|
||||
.pom.xml
|
||||
====
|
||||
[source,xml]
|
||||
[subs="verbatim,attributes"]
|
||||
----
|
||||
<dependencies>
|
||||
<!-- ... other dependency elements ... -->
|
||||
<dependency>
|
||||
<groupId>org.springframework.security</groupId>
|
||||
<artifactId>spring-security-web</artifactId>
|
||||
</dependency>
|
||||
<dependency>
|
||||
<groupId>org.springframework.security</groupId>
|
||||
<artifactId>spring-security-config</artifactId>
|
||||
</dependency>
|
||||
</dependencies>
|
||||
----
|
||||
====
|
||||
|
||||
If you use additional features (such as LDAP, OpenID, and others), you need to also include the appropriate <<modules>>.
|
||||
|
||||
Spring Security builds against Spring Framework {spring-version} but should generally work with any newer version of Spring Framework 5.x.
|
||||
Many users are likely to run afoul of the fact that Spring Security's transitive dependencies resolve Spring Framework {spring-version}, which can cause strange classpath problems.
|
||||
The easiest way to resolve this is to use the `spring-framework-bom` within the `<dependencyManagement>` section of your `pom.xml` as the following example shows:
|
||||
|
||||
.pom.xml
|
||||
====
|
||||
[source,xml]
|
||||
[subs="verbatim,attributes"]
|
||||
----
|
||||
<dependencyManagement>
|
||||
<dependencies>
|
||||
<!-- ... other dependency elements ... -->
|
||||
<dependency>
|
||||
<groupId>org.springframework</groupId>
|
||||
<artifactId>spring-framework-bom</artifactId>
|
||||
<version>{spring-version}</version>
|
||||
<type>pom</type>
|
||||
<scope>import</scope>
|
||||
</dependency>
|
||||
</dependencies>
|
||||
</dependencyManagement>
|
||||
----
|
||||
====
|
||||
|
||||
The preceding example ensures that all the transitive dependencies of Spring Security use the Spring {spring-version} modules.
|
||||
|
||||
NOTE: This approach uses Maven's "`bill of materials`" (BOM) concept and is only available in Maven 2.0.9+.
|
||||
For additional details about how dependencies are resolved, see http://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html[Maven's Introduction to the Dependency Mechanism documentation].
|
||||
|
||||
[[maven-repositories]]
|
||||
=== Maven Repositories
|
||||
All GA releases (that is, versions ending in .RELEASE) are deployed to Maven Central, so no additional Maven repositories need to be declared in your pom.
|
||||
|
||||
If you use a SNAPSHOT version, you need to ensure that you have the Spring Snapshot repository defined, as the following example shows:
|
||||
|
||||
.pom.xml
|
||||
====
|
||||
[source,xml]
|
||||
----
|
||||
<repositories>
|
||||
<!-- ... possibly other repository elements ... -->
|
||||
<repository>
|
||||
<id>spring-snapshot</id>
|
||||
<name>Spring Snapshot Repository</name>
|
||||
<url>https://repo.spring.io/snapshot</url>
|
||||
</repository>
|
||||
</repositories>
|
||||
----
|
||||
====
|
||||
|
||||
If you use a milestone or release candidate version, you need to ensure that you have the Spring Milestone repository defined, as the following example shows:
|
||||
|
||||
.pom.xml
|
||||
====
|
||||
[source,xml]
|
||||
----
|
||||
<repositories>
|
||||
<!-- ... possibly other repository elements ... -->
|
||||
<repository>
|
||||
<id>spring-milestone</id>
|
||||
<name>Spring Milestone Repository</name>
|
||||
<url>https://repo.spring.io/milestone</url>
|
||||
</repository>
|
||||
</repositories>
|
||||
----
|
||||
====
|
||||
|
||||
[[getting-gradle]]
|
||||
== Gradle
|
||||
|
||||
As most open source projects, Spring Security deploys its dependencies as Maven artifacts, which allows for for first-class Gradle support.
|
||||
The following topics provide detail on how to consume Spring Security when using Gradle.
|
||||
|
||||
[[getting-gradle-boot]]
|
||||
=== Spring Boot with Gradle
|
||||
|
||||
Spring Boot provides a `spring-boot-starter-security` starter that aggregates Spring Security related dependencies together.
|
||||
The simplest and preferred method to use the starter is to use https://docs.spring.io/initializr/docs/current/reference/htmlsingle/[Spring Initializr] by using an IDE integration (http://joshlong.com/jl/blogPost/tech_tip_geting_started_with_spring_boot.html[Eclipse], https://www.jetbrains.com/help/idea/spring-boot.html#d1489567e2[IntelliJ], https://github.com/AlexFalappa/nb-springboot/wiki/Quick-Tour[NetBeans]) or through https://start.spring.io.
|
||||
|
||||
Alternatively, you can manually add the starter, as the following example shows:
|
||||
|
||||
.build.gradle
|
||||
====
|
||||
[source,groovy]
|
||||
[subs="verbatim,attributes"]
|
||||
----
|
||||
dependencies {
|
||||
compile "org.springframework.boot:spring-boot-starter-security"
|
||||
}
|
||||
----
|
||||
====
|
||||
|
||||
Since Spring Boot provides a Maven BOM to manage dependency versions, you need not specify a version.
|
||||
If you wish to override the Spring Security version, you may do so by providing a Gradle property, as the following example shows:
|
||||
|
||||
.build.gradle
|
||||
====
|
||||
[source,groovy]
|
||||
[subs="verbatim,attributes"]
|
||||
----
|
||||
ext['spring-security.version']='{spring-security-version}'
|
||||
----
|
||||
====
|
||||
|
||||
Since Spring Security makes breaking changes only in major releases, it is safe to use a newer version of Spring Security with Spring Boot.
|
||||
However, at times, you may need to update the version of Spring Framework as well.
|
||||
You can do so by adding a Gradle property, as the following example shows:
|
||||
|
||||
.build.gradle
|
||||
====
|
||||
[source,groovy]
|
||||
[subs="verbatim,attributes"]
|
||||
----
|
||||
ext['spring.version']='{spring-version}'
|
||||
----
|
||||
====
|
||||
|
||||
If you use additional features (such as LDAP, OpenID, and others), you need to also include the appropriate <<modules>>.
|
||||
|
||||
=== Gradle Without Spring Boot
|
||||
|
||||
When you use Spring Security without Spring Boot, the preferred way is to use Spring Security's BOM to ensure a consistent version of Spring Security is used throughout the entire project.
|
||||
You can do so by using the https://github.com/spring-gradle-plugins/dependency-management-plugin[Dependency Management Plugin], as the following example shows:
|
||||
|
||||
.build.gradle
|
||||
====
|
||||
[source,groovy]
|
||||
[subs="verbatim,attributes"]
|
||||
----
|
||||
plugins {
|
||||
id "io.spring.dependency-management" version "1.0.6.RELEASE"
|
||||
}
|
||||
|
||||
dependencyManagement {
|
||||
imports {
|
||||
mavenBom 'org.springframework.security:spring-security-bom:{spring-security-version}'
|
||||
}
|
||||
}
|
||||
----
|
||||
====
|
||||
|
||||
A minimal Spring Security Maven set of dependencies typically looks like the following:
|
||||
|
||||
.build.gradle
|
||||
====
|
||||
[source,groovy]
|
||||
[subs="verbatim,attributes"]
|
||||
----
|
||||
dependencies {
|
||||
compile "org.springframework.security:spring-security-web"
|
||||
compile "org.springframework.security:spring-security-config"
|
||||
}
|
||||
----
|
||||
====
|
||||
|
||||
If you use additional features (such as LDAP, OpenID, and others), you need to also include the appropriate <<modules>>.
|
||||
|
||||
Spring Security builds against Spring Framework {spring-version} but should generally work with any newer version of Spring Framework 5.x. {JB}
|
||||
Many users are likely to run afoul of the fact that Spring Security's transitive dependencies resolve Spring Framework {spring-version}, which can cause strange classpath problems.
|
||||
The easiest way to resolve this is to use the `spring-framework-bom` within your `<dependencyManagement>` section of your `pom.xml`.
|
||||
You can do so by using the https://github.com/spring-gradle-plugins/dependency-management-plugin[Dependency Management Plugin], as the following example shows:
|
||||
|
||||
.build.gradle
|
||||
====
|
||||
[source,groovy]
|
||||
[subs="verbatim,attributes"]
|
||||
----
|
||||
plugins {
|
||||
id "io.spring.dependency-management" version "1.0.6.RELEASE"
|
||||
}
|
||||
|
||||
dependencyManagement {
|
||||
imports {
|
||||
mavenBom 'org.springframework:spring-framework-bom:{spring-version}'
|
||||
}
|
||||
}
|
||||
----
|
||||
====
|
||||
|
||||
The preceding example ensures that all the transitive dependencies of Spring Security use the Spring {spring-version} modules.
|
||||
|
||||
[[gradle-repositories]]
|
||||
=== Gradle Repositories
|
||||
All GA releases (that is, versions ending in .RELEASE) are deployed to Maven Central, so using the mavenCentral() repository is sufficient for GA releases. The following example shows how to do so:
|
||||
|
||||
.build.gradle
|
||||
====
|
||||
[source,groovy]
|
||||
----
|
||||
repositories {
|
||||
mavenCentral()
|
||||
}
|
||||
----
|
||||
====
|
||||
|
||||
If you use a SNAPSHOT version, you need to ensure you have the Spring Snapshot repository defined, as the following example shows:
|
||||
|
||||
.build.gradle
|
||||
====
|
||||
[source,groovy]
|
||||
----
|
||||
repositories {
|
||||
maven { url 'https://repo.spring.io/snapshot' }
|
||||
}
|
||||
----
|
||||
====
|
||||
|
||||
If you use a milestone or release candidate version, you need to ensure that you have the Spring Milestone repository defined, as the following example shows:
|
||||
|
||||
.build.gradle
|
||||
====
|
||||
[source,groovy]
|
||||
----
|
||||
repositories {
|
||||
maven { url 'https://repo.spring.io/milestone' }
|
||||
}
|
||||
----
|
||||
====
|
||||
|
|
@ -2,7 +2,9 @@
|
|||
|
||||
This section discusses the logistics of Spring Security.
|
||||
|
||||
include::community.adoc[]
|
||||
include::prerequisites.adoc[leveloffset=+1]
|
||||
|
||||
include::community.adoc[leveloffset=+1]
|
||||
|
||||
include::whats-new.adoc[]
|
||||
|
||||
|
|
@ -10,4 +12,4 @@ include::getting-spring-security.adoc[leveloffset=+1]
|
|||
|
||||
include::modules.adoc[leveloffset=+1]
|
||||
|
||||
include::samples.adoc[]
|
||||
include::samples.adoc[leveloffset=+1]
|
||||
|
|
@ -0,0 +1,108 @@
|
|||
// FIXME: This might make sense in Getting Spring Security along with the artifact information
|
||||
|
||||
[[modules]]
|
||||
= Project Modules
|
||||
In Spring Security 3.0, the codebase was sub-divided into separate jars which more clearly separate different functionality areas and third-party dependencies.
|
||||
If you use Maven to build your project, these are the modules you should add to your `pom.xml`.
|
||||
Even if you do not use Maven, we recommend that you consult the `pom.xml` files to get an idea of third-party dependencies and versions.
|
||||
Another good idea is to examine the libraries that are included in the sample applications.
|
||||
|
||||
|
||||
[[spring-security-core]]
|
||||
== Core -- `spring-security-core.jar`
|
||||
This module contains core authentication and access-contol classes and interfaces, remoting support, and basic provisioning APIs.
|
||||
It is required by any application that uses Spring Security.
|
||||
It supports standalone applications, remote clients, method (service layer) security, and JDBC user provisioning.
|
||||
It contains the following top-level packages:
|
||||
|
||||
* `org.springframework.security.core`
|
||||
* `org.springframework.security.access`
|
||||
* `org.springframework.security.authentication`
|
||||
* `org.springframework.security.provisioning`
|
||||
|
||||
[[spring-security-remoting]]
|
||||
== Remoting -- `spring-security-remoting.jar`
|
||||
This module provides integration with Spring Remoting.
|
||||
You do not need this unless you are writing a remote client that uses Spring Remoting.
|
||||
The main package is `org.springframework.security.remoting`.
|
||||
|
||||
|
||||
[[spring-security-web]]
|
||||
== Web -- `spring-security-web.jar`
|
||||
This module contains filters and related web-security infrastructure code.
|
||||
It contains anything with a servlet API dependency.
|
||||
You need it if you require Spring Security web authentication services and URL-based access-control.
|
||||
The main package is `org.springframework.security.web`.
|
||||
|
||||
|
||||
[[spring-security-config]]
|
||||
== Config -- `spring-security-config.jar`
|
||||
This module contains the security namespace parsing code and Java configuration code.
|
||||
You need it if you use the Spring Security XML namespace for configuration or Spring Security's Java Configuration support.
|
||||
The main package is `org.springframework.security.config`.
|
||||
None of the classes are intended for direct use in an application.
|
||||
|
||||
|
||||
[[spring-security-ldap]]
|
||||
== LDAP -- `spring-security-ldap.jar`
|
||||
This module provides LDAP authentication and provisioning code.
|
||||
It is required if you need to use LDAP authentication or manage LDAP user entries.
|
||||
The top-level package is `org.springframework.security.ldap`.
|
||||
|
||||
|
||||
[[spring-security-oauth2-core]]
|
||||
== OAuth 2.0 Core -- `spring-security-oauth2-core.jar`
|
||||
`spring-security-oauth2-core.jar` contains core classes and interfaces that provide support for the OAuth 2.0 Authorization Framework and for OpenID Connect Core 1.0.
|
||||
It is required by applications that use OAuth 2.0 or OpenID Connect Core 1.0, such as client, resource server, and authorization server.
|
||||
The top-level package is `org.springframework.security.oauth2.core`.
|
||||
|
||||
|
||||
[[spring-security-oauth2-client]]
|
||||
== OAuth 2.0 Client -- `spring-security-oauth2-client.jar`
|
||||
`spring-security-oauth2-client.jar` contains Spring Security's client support for OAuth 2.0 Authorization Framework and OpenID Connect Core 1.0.
|
||||
It is required by applications that use OAuth 2.0 Login or OAuth Client support.
|
||||
The top-level package is `org.springframework.security.oauth2.client`.
|
||||
|
||||
|
||||
[[spring-security-oauth2-jose]]
|
||||
== OAuth 2.0 JOSE -- `spring-security-oauth2-jose.jar`
|
||||
`spring-security-oauth2-jose.jar` contains Spring Security's support for the JOSE (Javascript Object Signing and Encryption) framework.
|
||||
The JOSE framework is intended to provide a method to securely transfer claims between parties.
|
||||
It is built from a collection of specifications:
|
||||
|
||||
* JSON Web Token (JWT)
|
||||
* JSON Web Signature (JWS)
|
||||
* JSON Web Encryption (JWE)
|
||||
* JSON Web Key (JWK)
|
||||
|
||||
It contains the following top-level packages:
|
||||
|
||||
* `org.springframework.security.oauth2.jwt`
|
||||
* `org.springframework.security.oauth2.jose`
|
||||
|
||||
|
||||
[[spring-security-acl]]
|
||||
== ACL -- `spring-security-acl.jar`
|
||||
This module contains a specialized domain object ACL implementation.
|
||||
It is used to apply security to specific domain object instances within your application.
|
||||
The top-level package is `org.springframework.security.acls`.
|
||||
|
||||
|
||||
[[spring-security-cas]]
|
||||
== CAS -- `spring-security-cas.jar`
|
||||
This module contains Spring Security's CAS client integration.
|
||||
You should use it if you want to use Spring Security web authentication with a CAS single sign-on server.
|
||||
The top-level package is `org.springframework.security.cas`.
|
||||
|
||||
|
||||
[[spring-security-openid]]
|
||||
== OpenID -- `spring-security-openid.jar`
|
||||
This module contains OpenID web authentication support.
|
||||
It is used to authenticate users against an external OpenID server.
|
||||
The top-level package is `org.springframework.security.openid`.
|
||||
It requires OpenID4Java.
|
||||
|
||||
|
||||
[[spring-security-test]]
|
||||
== Test -- `spring-security-test.jar`
|
||||
This module contains support for testing with Spring Security.
|
||||
|
|
@ -0,0 +1,12 @@
|
|||
[[prerequisites]]
|
||||
= Prerequisites
|
||||
|
||||
Spring Security requires a Java 8 or higher Runtime Environment.
|
||||
|
||||
As Spring Security aims to operate in a self-contained manner, you do not need to place any special configuration files in your Java Runtime Environment.
|
||||
In particular, you need not configure a special Java Authentication and Authorization Service (JAAS) policy file or place Spring Security into common classpath locations.
|
||||
|
||||
Similarly, if you use an EJB Container or Servlet Container, you need not put any special configuration files anywhere nor include Spring Security in a server classloader.
|
||||
All the required files are contained within your application.
|
||||
|
||||
This design offers maximum deployment time flexibility, as you can copy your target artifact (be it a JAR, WAR, or EAR) from one system to another and it immediately works.
|
||||
|
|
@ -0,0 +1,3 @@
|
|||
= Samples
|
||||
|
||||
Spring Security includes many {gh-samples-url}[samples] applications.
|
||||
|
|
@ -1,40 +0,0 @@
|
|||
[[community]]
|
||||
== Spring Security Community
|
||||
|
||||
Welcome to the Spring Security Community!
|
||||
This section discusses how you to make the most of our vast community.
|
||||
|
||||
|
||||
[[community-help]]
|
||||
=== Getting Help
|
||||
If you need help with Spring Security, we are here to help.
|
||||
Below are some of the best steps to getting help:
|
||||
|
||||
* Read our reference documentation
|
||||
* Try one of our many sample applications
|
||||
// FIXME: Add a link to the samples section
|
||||
* Ask a question on https://stackoverflow.com with the tag `spring-security`
|
||||
* Report a bugs and enhancement requests at https://github.com/spring-projects/spring-security/issues
|
||||
|
||||
[[community-becoming-involved]]
|
||||
=== Becoming Involved
|
||||
We welcome your involvement in the Spring Security project.
|
||||
There are many ways of contributing, including answering questions on StackOverflow, writing new code, improving existing code, assisting with documentation, developing samples or tutorials, reporting bugs, or simply making suggestions.
|
||||
|
||||
[[community-source]]
|
||||
=== Source Code
|
||||
|
||||
Spring Security's source code can be found on GitHub at https://github.com/spring-projects/spring-security/
|
||||
|
||||
[[community-license]]
|
||||
=== Apache 2 License
|
||||
|
||||
Spring Security is Open Source software released under the https://www.apache.org/licenses/LICENSE-2.0.html[Apache 2.0 license].
|
||||
|
||||
=== Social Media
|
||||
|
||||
You may follow https://twitter.com/SpringSecurity[@SpringSecurity] and https://twitter.com/SpringSecurity/lists/team[Spring Security team] on Twitter to stay up to date with the latest news.
|
||||
You can also follow https://twitter.com/SpringCentral[@SpringCentral] to keep up to date with the entire Spring portfolio.
|
||||
|
||||
// == Getting Started
|
||||
// FIXME: Add links to samples
|
||||
|
|
@ -1,310 +0,0 @@
|
|||
[[get-spring-security]]
|
||||
= Getting Spring Security
|
||||
|
||||
This section discusses all you need to know about getting the Spring Security binaries.
|
||||
Please refer to <<community-source>> for how to obtain the source code.
|
||||
|
||||
== Release Numbering
|
||||
|
||||
Spring Security versions are formatted as MAJOR.MINOR.PATCH such that
|
||||
|
||||
* MAJOR versions may contain breaking changes.
|
||||
Typically these are done to provide improved security to match modern security practices.
|
||||
* MINOR versions contain enhancements, but are considered passive updates
|
||||
* PATCH level should be perfectly compatible, forwards and backwards, with the possible exception of changes which are to fix bugs
|
||||
|
||||
|
||||
[[maven]]
|
||||
== Usage with Maven
|
||||
|
||||
Like most open source projects, Spring Security deploys its dependencies as Maven artifacts.
|
||||
The following sections provide details on how to consume Spring Security when using Maven.
|
||||
|
||||
=== Spring Boot with Maven
|
||||
|
||||
Spring Boot provides a spring-boot-starter-security starter which aggregates Spring Security related dependencies together.
|
||||
The simplest and preferred method to leverage the starter is to use https://docs.spring.io/initializr/docs/current/reference/htmlsingle/[Spring Initializr] using an IDE integration (https://joshlong.com/jl/blogPost/tech_tip_geting_started_with_spring_boot.html[Eclipse], https://www.jetbrains.com/help/idea/spring-boot.html#d1489567e2[IntelliJ], https://github.com/AlexFalappa/nb-springboot/wiki/Quick-Tour[NetBeans]) or through https://start.spring.io.
|
||||
|
||||
Alternatively, the starter can be added manually:
|
||||
|
||||
.pom.xml
|
||||
[source,xml]
|
||||
[subs="verbatim,attributes"]
|
||||
----
|
||||
<dependencies>
|
||||
<!-- ... other dependency elements ... -->
|
||||
<dependency>
|
||||
<groupId>org.springframework.boot</groupId>
|
||||
<artifactId>spring-boot-starter-security</artifactId>
|
||||
</dependency>
|
||||
</dependencies>
|
||||
----
|
||||
|
||||
Since Spring Boot provides a Maven BOM to manage dependency versions, there is no need to specify a version.
|
||||
If you wish to override the Spring Security version, you may do so by providing a Maven property:
|
||||
|
||||
.pom.xml
|
||||
[source,xml]
|
||||
[subs="verbatim,attributes"]
|
||||
----
|
||||
<properties>
|
||||
<!-- ... -->
|
||||
<spring-security.version>{spring-security-version}</spring-security.version>
|
||||
</dependencies>
|
||||
----
|
||||
|
||||
Since Spring Security only makes breaking changes in major releases, it is safe to use a newer version of Spring Security with Spring Boot.
|
||||
However, at times it may be necessary to update the version of Spring Framework as well.
|
||||
This can easily be done by adding a Maven property as well:
|
||||
|
||||
.pom.xml
|
||||
[source,xml]
|
||||
[subs="verbatim,attributes"]
|
||||
----
|
||||
<properties>
|
||||
<!-- ... -->
|
||||
<spring.version>{spring-version}</spring.version>
|
||||
</dependencies>
|
||||
----
|
||||
|
||||
If you are using additional features like LDAP, OpenID, etc. you will need to also include the appropriate <<modules>>.
|
||||
|
||||
=== Maven Without Spring Boot
|
||||
|
||||
When using Spring Security without Spring Boot, the preferred way is to leverage Spring Security's BOM to ensure a consistent version of Spring Security is used throughout the entire project.
|
||||
|
||||
.pom.xml
|
||||
[source,xml]
|
||||
[subs="verbatim,attributes"]
|
||||
----
|
||||
<dependencyManagement>
|
||||
<dependencies>
|
||||
<!-- ... other dependency elements ... -->
|
||||
<dependency>
|
||||
<groupId>org.springframework.security</groupId>
|
||||
<artifactId>spring-security-bom</artifactId>
|
||||
<version>{spring-security-version}</version>
|
||||
<type>pom</type>
|
||||
<scope>import</scope>
|
||||
</dependency>
|
||||
</dependencies>
|
||||
</dependencyManagement>
|
||||
----
|
||||
|
||||
|
||||
A minimal Spring Security Maven set of dependencies typically looks like the following:
|
||||
|
||||
.pom.xml
|
||||
[source,xml]
|
||||
[subs="verbatim,attributes"]
|
||||
----
|
||||
<dependencies>
|
||||
<!-- ... other dependency elements ... -->
|
||||
<dependency>
|
||||
<groupId>org.springframework.security</groupId>
|
||||
<artifactId>spring-security-web</artifactId>
|
||||
</dependency>
|
||||
<dependency>
|
||||
<groupId>org.springframework.security</groupId>
|
||||
<artifactId>spring-security-config</artifactId>
|
||||
</dependency>
|
||||
</dependencies>
|
||||
----
|
||||
|
||||
If you are using additional features like LDAP, OpenID, etc. you will need to also include the appropriate <<modules>>.
|
||||
|
||||
Spring Security builds against Spring Framework {spring-version}, but should generally work with any newer version of Spring Framework 5.x
|
||||
The problem that many users will have is that Spring Security's transitive dependencies resolve Spring Framework {spring-version} which can cause strange classpath problems.
|
||||
The easiest way to resolve this is to use the `spring-framework-bom` within your `<dependencyManagement>` section of your `pom.xml` as shown below:
|
||||
|
||||
.pom.xml
|
||||
[source,xml]
|
||||
[subs="verbatim,attributes"]
|
||||
----
|
||||
<dependencyManagement>
|
||||
<dependencies>
|
||||
<!-- ... other dependency elements ... -->
|
||||
<dependency>
|
||||
<groupId>org.springframework</groupId>
|
||||
<artifactId>spring-framework-bom</artifactId>
|
||||
<version>{spring-version}</version>
|
||||
<type>pom</type>
|
||||
<scope>import</scope>
|
||||
</dependency>
|
||||
</dependencies>
|
||||
</dependencyManagement>
|
||||
----
|
||||
|
||||
This will ensure that all the transitive dependencies of Spring Security use the Spring {spring-version} modules.
|
||||
|
||||
NOTE: This approach uses Maven's "bill of materials" (BOM) concept and is only available in Maven 2.0.9+.
|
||||
For additional details about how dependencies are resolved refer to https://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html[Maven's Introduction to the Dependency Mechanism documentation].
|
||||
|
||||
[[maven-repositories]]
|
||||
=== Maven Repositories
|
||||
All GA releases (i.e. versions ending in .RELEASE) are deployed to Maven Central, so no additional Maven repositories need to be declared in your pom.
|
||||
|
||||
If you are using a SNAPSHOT version, you will need to ensure you have the Spring Snapshot repository defined as shown below:
|
||||
|
||||
.pom.xml
|
||||
[source,xml]
|
||||
----
|
||||
<repositories>
|
||||
<!-- ... possibly other repository elements ... -->
|
||||
<repository>
|
||||
<id>spring-snapshot</id>
|
||||
<name>Spring Snapshot Repository</name>
|
||||
<url>https://repo.spring.io/snapshot</url>
|
||||
</repository>
|
||||
</repositories>
|
||||
----
|
||||
|
||||
If you are using a milestone or release candidate version, you will need to ensure you have the Spring Milestone repository defined as shown below:
|
||||
|
||||
.pom.xml
|
||||
[source,xml]
|
||||
----
|
||||
<repositories>
|
||||
<!-- ... possibly other repository elements ... -->
|
||||
<repository>
|
||||
<id>spring-milestone</id>
|
||||
<name>Spring Milestone Repository</name>
|
||||
<url>https://repo.spring.io/milestone</url>
|
||||
</repository>
|
||||
</repositories>
|
||||
----
|
||||
|
||||
|
||||
[[gradle]]
|
||||
== Gradle
|
||||
|
||||
Like most open source projects, Spring Security deploys its dependencies as Maven artifacts which allows for first class Gradle support.
|
||||
The following sections provide details on how to consume Spring Security when using Gradle.
|
||||
|
||||
=== Spring Boot with Gradle
|
||||
|
||||
Spring Boot provides a spring-boot-starter-security starter which aggregates Spring Security related dependencies together.
|
||||
The simplest and preferred method to leverage the starter is to use https://docs.spring.io/initializr/docs/current/reference/htmlsingle/[Spring Initializr] using an IDE integration (https://joshlong.com/jl/blogPost/tech_tip_geting_started_with_spring_boot.html[Eclipse], https://www.jetbrains.com/help/idea/spring-boot.html#d1489567e2[IntelliJ], https://github.com/AlexFalappa/nb-springboot/wiki/Quick-Tour[NetBeans]) or through https://start.spring.io.
|
||||
|
||||
Alternatively, the starter can be added manually:
|
||||
|
||||
.build.gradle
|
||||
[source,groovy]
|
||||
[subs="verbatim,attributes"]
|
||||
----
|
||||
dependencies {
|
||||
compile "org.springframework.boot:spring-boot-starter-security"
|
||||
}
|
||||
----
|
||||
|
||||
Since Spring Boot provides a Maven BOM to manage dependency versions, there is no need to specify a version.
|
||||
If you wish to override the Spring Security version, you may do so by providing a Gradle property:
|
||||
|
||||
.build.gradle
|
||||
[source,groovy]
|
||||
[subs="verbatim,attributes"]
|
||||
----
|
||||
ext['spring-security.version']='{spring-security-version}'
|
||||
----
|
||||
|
||||
Since Spring Security only makes breaking changes in major releases, it is safe to use a newer version of Spring Security with Spring Boot.
|
||||
However, at times it may be necessary to update the version of Spring Framework as well.
|
||||
This can easily be done by adding a Gradle property as well:
|
||||
|
||||
.build.gradle
|
||||
[source,groovy]
|
||||
[subs="verbatim,attributes"]
|
||||
----
|
||||
ext['spring.version']='{spring-version}'
|
||||
----
|
||||
|
||||
If you are using additional features like LDAP, OpenID, etc. you will need to also include the appropriate <<modules>>.
|
||||
|
||||
=== Gradle Without Spring Boot
|
||||
|
||||
When using Spring Security without Spring Boot, the preferred way is to leverage Spring Security's BOM to ensure a consistent version of Spring Security is used throughout the entire project.
|
||||
This can be done by using the https://github.com/spring-gradle-plugins/dependency-management-plugin[Dependency Management Plugin].
|
||||
|
||||
.build.gradle
|
||||
[source,groovy]
|
||||
[subs="verbatim,attributes"]
|
||||
----
|
||||
plugins {
|
||||
id "io.spring.dependency-management" version "1.0.6.RELEASE"
|
||||
}
|
||||
|
||||
dependencyManagement {
|
||||
imports {
|
||||
mavenBom 'org.springframework.security:spring-security-bom:{spring-security-version}'
|
||||
}
|
||||
}
|
||||
----
|
||||
|
||||
|
||||
A minimal Spring Security Maven set of dependencies typically looks like the following:
|
||||
|
||||
.build.gradle
|
||||
[source,groovy]
|
||||
[subs="verbatim,attributes"]
|
||||
----
|
||||
dependencies {
|
||||
compile "org.springframework.security:spring-security-web"
|
||||
compile "org.springframework.security:spring-security-config"
|
||||
}
|
||||
----
|
||||
|
||||
If you are using additional features like LDAP, OpenID, etc. you will need to also include the appropriate <<modules>>.
|
||||
|
||||
Spring Security builds against Spring Framework {spring-version}, but should generally work with any newer version of Spring Framework 5.x
|
||||
The problem that many users will have is that Spring Security's transitive dependencies resolve Spring Framework {spring-version} which can cause strange classpath problems.
|
||||
The easiest way to resolve this is to use the `spring-framework-bom` within your `<dependencyManagement>` section of your `pom.xml` as shown below:
|
||||
This can be done by using the https://github.com/spring-gradle-plugins/dependency-management-plugin[Dependency Management Plugin].
|
||||
|
||||
.build.gradle
|
||||
[source,groovy]
|
||||
[subs="verbatim,attributes"]
|
||||
----
|
||||
plugins {
|
||||
id "io.spring.dependency-management" version "1.0.6.RELEASE"
|
||||
}
|
||||
|
||||
dependencyManagement {
|
||||
imports {
|
||||
mavenBom 'org.springframework:spring-framework-bom:{spring-version}'
|
||||
}
|
||||
}
|
||||
----
|
||||
|
||||
This will ensure that all the transitive dependencies of Spring Security use the Spring {spring-version} modules.
|
||||
|
||||
[[gradle-repositories]]
|
||||
=== Gradle Repositories
|
||||
All GA releases (i.e. versions ending in .RELEASE) are deployed to Maven Central, so using the mavenCentral() repository is sufficient for GA releases.
|
||||
|
||||
.build.gradle
|
||||
[source,groovy]
|
||||
----
|
||||
repositories {
|
||||
mavenCentral()
|
||||
}
|
||||
----
|
||||
|
||||
If you are using a SNAPSHOT version, you will need to ensure you have the Spring Snapshot repository defined as shown below:
|
||||
|
||||
.build.gradle
|
||||
[source,groovy]
|
||||
----
|
||||
repositories {
|
||||
maven { url 'https://repo.spring.io/snapshot' }
|
||||
}
|
||||
----
|
||||
|
||||
If you are using a milestone or release candidate version, you will need to ensure you have the Spring Milestone repository defined as shown below:
|
||||
|
||||
.build.gradle
|
||||
[source,groovy]
|
||||
----
|
||||
repositories {
|
||||
maven { url 'https://repo.spring.io/milestone' }
|
||||
}
|
||||
----
|
||||
|
|
@ -1,114 +0,0 @@
|
|||
|
||||
[[modules]]
|
||||
= Project Modules
|
||||
In Spring Security 3.0, the codebase has been sub-divided into separate jars which more clearly separate different functionality areas and third-party dependencies.
|
||||
If you are using Maven to build your project, then these are the modules you will add to your `pom.xml`.
|
||||
Even if you're not using Maven, we'd recommend that you consult the `pom.xml` files to get an idea of third-party dependencies and versions.
|
||||
Alternatively, a good idea is to examine the libraries that are included in the sample applications.
|
||||
|
||||
|
||||
[[spring-security-core]]
|
||||
== Core - spring-security-core.jar
|
||||
Contains core authentication and access-contol classes and interfaces, remoting support and basic provisioning APIs.
|
||||
Required by any application which uses Spring Security.
|
||||
Supports standalone applications, remote clients, method (service layer) security and JDBC user provisioning.
|
||||
Contains the top-level packages:
|
||||
|
||||
* `org.springframework.security.core`
|
||||
|
||||
* `org.springframework.security.access`
|
||||
|
||||
* `org.springframework.security.authentication`
|
||||
|
||||
* `org.springframework.security.provisioning`
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
[[spring-security-remoting]]
|
||||
== Remoting - spring-security-remoting.jar
|
||||
Provides integration with Spring Remoting.
|
||||
You don't need this unless you are writing a remote client which uses Spring Remoting.
|
||||
The main package is `org.springframework.security.remoting`.
|
||||
|
||||
|
||||
[[spring-security-web]]
|
||||
== Web - spring-security-web.jar
|
||||
Contains filters and related web-security infrastructure code.
|
||||
Anything with a servlet API dependency.
|
||||
You'll need it if you require Spring Security web authentication services and URL-based access-control.
|
||||
The main package is `org.springframework.security.web`.
|
||||
|
||||
|
||||
[[spring-security-config]]
|
||||
== Config - spring-security-config.jar
|
||||
Contains the security namespace parsing code & Java configuration code.
|
||||
You need it if you are using the Spring Security XML namespace for configuration or Spring Security's Java Configuration support.
|
||||
The main package is `org.springframework.security.config`.
|
||||
None of the classes are intended for direct use in an application.
|
||||
|
||||
|
||||
[[spring-security-ldap]]
|
||||
== LDAP - spring-security-ldap.jar
|
||||
LDAP authentication and provisioning code.
|
||||
Required if you need to use LDAP authentication or manage LDAP user entries.
|
||||
The top-level package is `org.springframework.security.ldap`.
|
||||
|
||||
|
||||
[[spring-security-oauth2-core]]
|
||||
== OAuth 2.0 Core - spring-security-oauth2-core.jar
|
||||
`spring-security-oauth2-core.jar` contains core classes and interfaces that provide support for the _OAuth 2.0 Authorization Framework_ and for _OpenID Connect Core 1.0_.
|
||||
It is required by applications that use _OAuth 2.0_ or _OpenID Connect Core 1.0_, such as Client, Resource Server, and Authorization Server.
|
||||
The top-level package is `org.springframework.security.oauth2.core`.
|
||||
|
||||
|
||||
[[spring-security-oauth2-client]]
|
||||
== OAuth 2.0 Client - spring-security-oauth2-client.jar
|
||||
`spring-security-oauth2-client.jar` is Spring Security's client support for _OAuth 2.0 Authorization Framework_ and _OpenID Connect Core 1.0_.
|
||||
Required by applications leveraging *OAuth 2.0 Login* and/or OAuth Client support.
|
||||
The top-level package is `org.springframework.security.oauth2.client`.
|
||||
|
||||
|
||||
[[spring-security-oauth2-jose]]
|
||||
== OAuth 2.0 JOSE - spring-security-oauth2-jose.jar
|
||||
`spring-security-oauth2-jose.jar` contains Spring Security's support for the _JOSE_ (Javascript Object Signing and Encryption) framework.
|
||||
The _JOSE_ framework is intended to provide a method to securely transfer claims between parties.
|
||||
It is built from a collection of specifications:
|
||||
|
||||
* JSON Web Token (JWT)
|
||||
* JSON Web Signature (JWS)
|
||||
* JSON Web Encryption (JWE)
|
||||
* JSON Web Key (JWK)
|
||||
|
||||
It contains the top-level packages:
|
||||
|
||||
* `org.springframework.security.oauth2.jwt`
|
||||
* `org.springframework.security.oauth2.jose`
|
||||
|
||||
|
||||
[[spring-security-acl]]
|
||||
== ACL - spring-security-acl.jar
|
||||
Specialized domain object ACL implementation.
|
||||
Used to apply security to specific domain object instances within your application.
|
||||
The top-level package is `org.springframework.security.acls`.
|
||||
|
||||
|
||||
[[spring-security-cas]]
|
||||
== CAS - spring-security-cas.jar
|
||||
Spring Security's CAS client integration.
|
||||
If you want to use Spring Security web authentication with a CAS single sign-on server.
|
||||
The top-level package is `org.springframework.security.cas`.
|
||||
|
||||
|
||||
[[spring-security-openid]]
|
||||
== OpenID - spring-security-openid.jar
|
||||
OpenID web authentication support.
|
||||
Used to authenticate users against an external OpenID server.
|
||||
`org.springframework.security.openid`.
|
||||
Requires OpenID4Java.
|
||||
|
||||
|
||||
[[spring-security-test]]
|
||||
== Test - spring-security-test.jar
|
||||
Support for testing with Spring Security.
|
||||
|
|
@ -1,118 +0,0 @@
|
|||
|
||||
|
||||
[[sample-apps]]
|
||||
== Sample Applications
|
||||
There are several {gh-samples-url}[sample web applications] that ship with the project's <<community-source,source code>>.
|
||||
You can find the ones described below in the ({gh-samples-url}/xml[samples/xml/] subdirectory of the root project)
|
||||
|
||||
All paths referred to in this chapter are relative to the project source directory.
|
||||
|
||||
|
||||
[[tutorial-sample]]
|
||||
=== Tutorial Sample
|
||||
The tutorial sample is a nice basic example to get you started.
|
||||
It uses simple namespace configuration throughout.
|
||||
The compiled application is included in the distribution zip file, ready to be deployed into your web container (`spring-security-samples-tutorial-3.1.x.war`).
|
||||
The <<ns-form-and-basic,form-based>> authentication mechanism is used in combination with the commonly-used <<remember-me,remember-me>> authentication provider to automatically remember the login using cookies.
|
||||
|
||||
We recommend you start with the tutorial sample, as the XML is minimal and easy to follow.
|
||||
Most importantly, you can easily add this one XML file (and its corresponding `web.xml` entries) to your existing application.
|
||||
Only when this basic integration is achieved do we suggest you attempt adding in method authorization or domain object security.
|
||||
|
||||
|
||||
[[contacts-sample]]
|
||||
=== Contacts
|
||||
The Contacts Sample is an advanced example in that it illustrates the more powerful features of domain object access control lists (ACLs) in addition to basic application security.
|
||||
The application provides an interface with which the users are able to administer a simple database of contacts (the domain objects).
|
||||
|
||||
To deploy, simply copy the WAR file from Spring Security distribution into your container's `webapps` directory.
|
||||
The war should be called `spring-security-samples-contacts-3.1.x.war` (the appended version number will vary depending on what release you are using).
|
||||
|
||||
After starting your container, check the application can load.
|
||||
Visit http://localhost:8080/contacts (or whichever URL is appropriate for your web container and the WAR you deployed).
|
||||
|
||||
Next, click "Debug".
|
||||
You will be prompted to authenticate, and a series of usernames and passwords are suggested on that page.
|
||||
Simply authenticate with any of these and view the resulting page.
|
||||
It should contain a success message similar to the following:
|
||||
----
|
||||
|
||||
Security Debug Information
|
||||
|
||||
Authentication object is of type:
|
||||
org.springframework.security.authentication.UsernamePasswordAuthenticationToken
|
||||
|
||||
Authentication object as a String:
|
||||
|
||||
org.springframework.security.authentication.UsernamePasswordAuthenticationToken@1f127853:
|
||||
Principal: org.springframework.security.core.userdetails.User@b07ed00: Username: rod; \
|
||||
Password: [PROTECTED]; Enabled: true; AccountNonExpired: true;
|
||||
credentialsNonExpired: true; AccountNonLocked: true; \
|
||||
Granted Authorities: ROLE_SUPERVISOR, ROLE_USER; \
|
||||
Password: [PROTECTED]; Authenticated: true; \
|
||||
Details: org.springframework.security.web.authentication.WebAuthenticationDetails@0: \
|
||||
RemoteIpAddress: 127.0.0.1; SessionId: 8fkp8t83ohar; \
|
||||
Granted Authorities: ROLE_SUPERVISOR, ROLE_USER
|
||||
|
||||
Authentication object holds the following granted authorities:
|
||||
|
||||
ROLE_SUPERVISOR (getAuthority(): ROLE_SUPERVISOR)
|
||||
ROLE_USER (getAuthority(): ROLE_USER)
|
||||
|
||||
Success! Your web filters appear to be properly configured!
|
||||
|
||||
----
|
||||
|
||||
|
||||
Once you successfully receive the above message, return to the sample application's home page and click "Manage".
|
||||
You can then try out the application.
|
||||
Notice that only the contacts available to the currently logged on user are displayed, and only users with `ROLE_SUPERVISOR` are granted access to delete their contacts.
|
||||
Behind the scenes, the `MethodSecurityInterceptor` is securing the business objects.
|
||||
|
||||
The application allows you to modify the access control lists associated with different contacts.
|
||||
Be sure to give this a try and understand how it works by reviewing the application context XML files.
|
||||
|
||||
|
||||
[[ldap-sample]]
|
||||
=== LDAP Sample
|
||||
The LDAP sample application provides a basic configuration and sets up both a namespace configuration and an equivalent configuration using traditional beans, both in the same application context file.
|
||||
This means there are actually two identical authentication providers configured in this application.
|
||||
|
||||
|
||||
[[openid-sample]]
|
||||
=== OpenID Sample
|
||||
The OpenID sample demonstrates how to use the namespace to configure OpenID and how to set up https://openid.net/specs/openid-attribute-exchange-1_0.html[attribute exchange] configurations for Google, Yahoo and MyOpenID identity providers (you can experiment with adding others if you wish).
|
||||
It uses the JQuery-based https://code.google.com/p/openid-selector/[openid-selector] project to provide a user-friendly login page which allows the user to easily select a provider, rather than typing in the full OpenID identifier.
|
||||
|
||||
The application differs from normal authentication scenarios in that it allows any user to access the site (provided their OpenID authentication is successful).
|
||||
The first time you login, you will get a "Welcome [your name]"" message.
|
||||
If you logout and log back in (with the same OpenID identity) then this should change to "Welcome Back".
|
||||
This is achieved by using a custom `UserDetailsService` which assigns a standard role to any user and stores the identities internally in a map.
|
||||
Obviously a real application would use a database instead.
|
||||
Have a look at the source form more information.
|
||||
This class also takes into account the fact that different attributes may be returned from different providers and builds the name with which it addresses the user accordingly.
|
||||
|
||||
|
||||
[[cas-sample]]
|
||||
=== CAS Sample
|
||||
The CAS sample requires that you run both a CAS server and CAS client.
|
||||
It isn't included in the distribution so you should check out the project code as described in <<get-source,the introduction>>.
|
||||
You'll find the relevant files under the `sample/cas` directory.
|
||||
There's also a `Readme.txt` file in there which explains how to run both the server and the client directly from the source tree, complete with SSL support.
|
||||
|
||||
|
||||
[[jaas-sample]]
|
||||
=== JAAS Sample
|
||||
The JAAS sample is very simple example of how to use a JAAS LoginModule with Spring Security.
|
||||
The provided LoginModule will successfully authenticate a user if the username equals the password otherwise a LoginException is thrown.
|
||||
The AuthorityGranter used in this example always grants the role ROLE_USER.
|
||||
The sample application also demonstrates how to run as the JAAS Subject returned by the LoginModule by setting <<nsa-http-jaas-api-provision,jaas-api-provision>> equal to "true".
|
||||
|
||||
|
||||
[[preauth-sample]]
|
||||
=== Pre-Authentication Sample
|
||||
This sample application demonstrates how to wire up beans from the <<preauth,pre-authentication>> framework to make use of login information from a Java EE container.
|
||||
The user name and roles are those setup by the container.
|
||||
|
||||
The code is in `samples/preauth`.
|
||||
|
||||
|
|
@ -10,7 +10,7 @@ Spring Security is a framework that provides authentication, authorization, and
|
|||
// FIXME: Add links for imperative and reactive applications
|
||||
With first class support for both imperative and reactive applications, it is the de-facto standard for securing Spring-based applications.
|
||||
|
||||
include::{include-dir}/preface/index.adoc[]
|
||||
include::{include-dir}/about/index.adoc[]
|
||||
|
||||
include::{include-dir}/servlet/index.adoc[]
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue