SAML 2 Login - Documentation
Fixes gh-7472 https://github.com/spring-projects/spring-security/issues/7472
This commit is contained in:
Filip Hanik
parent
fc8a0184b0
commit
8bc3ad16ef
|
|
@ -12,6 +12,8 @@ include::authorization/index.adoc[leveloffset=+1]
|
|||
|
||||
include::oauth2/index.adoc[leveloffset=+1]
|
||||
|
||||
include::saml2/index.adoc[leveloffset=+1]
|
||||
|
||||
include::exploits/index.adoc[leveloffset=+1]
|
||||
|
||||
include::integrations/index.adoc[leveloffset=+1]
|
||||
|
|
|
|||
|
|
@ -0,0 +1,3 @@
|
|||
= SAML2
|
||||
|
||||
include::saml2-login.adoc[]
|
||||
|
|
@ -0,0 +1,312 @@
|
|||
[[saml2login]]
|
||||
== SAML 2.0 Login
|
||||
|
||||
The SAML 2.0 Login, `saml2Login()`, feature provides an application with the capability to have users log in to the application by using their existing account at an SAML 2.0 Identity Provider (Okta, ADFS, etc).
|
||||
|
||||
NOTE: SAML 2.0 Login is implemented by using the *Web Browser SSO Profile*, as specified in
|
||||
https://www.oasis-open.org/committees/download.php/35389/sstc-saml-profiles-errata-2.0-wd-06-diff.pdf#page=15[SAML 2 Profiles].
|
||||
Our implementation is currently limited to a simple authentication scheme.
|
||||
|
||||
[[saml2login-spring-security-saml2-history]]
|
||||
=== SAML 2 Support in Spring Security
|
||||
|
||||
SAML 2 Service Provider, SP a.k.a. a relying party, support existed as an
|
||||
https://github.com/spring-projects/spring-security-saml/tree/1e013b07a7772defd6a26fcfae187c9bf661ee8f#spring-saml[independent project]
|
||||
since 2009. The 1.0.x branch is still in use, including in the
|
||||
https://github.com/cloudfoundry/uaa[Cloud Foundry User Account and Authentication Server] that
|
||||
also created a SAML 2.0 Identity Provider implementation based on the SP implementation.
|
||||
|
||||
In 2018 we experimented with creating an updated implementation of both a
|
||||
https://github.com/spring-projects/spring-security-saml#spring-saml[Service Provider and Identity Provider]
|
||||
as a standalone library. After careful, and lengthy, deliberation we, the Spring Security team, decided
|
||||
to discontinue that effort. While this effort created a replacement for that standalone 1.0.x library
|
||||
we didn't feel that we should build a library on top of another library.
|
||||
|
||||
Instead we opted to provide framework support for SAML 2 authentication as part of
|
||||
https://github.com/spring-projects/spring-security[core Spring Security] instead.
|
||||
|
||||
[[samllogin-concepts]]
|
||||
=== Saml 2 Login - High Level Concepts
|
||||
|
||||
`saml2Login()` is aimed to support a fraction of the https://saml.xml.org/saml-specifications[SAML 2 feature set]
|
||||
with a focus on authentication being a Service Provider, SP, a relying party, receiving XML assertions from an
|
||||
Identity Provider, aka an asserting party.
|
||||
|
||||
A SAML 2 login, or authentication, is the concept that the SP receives and validates an XML message called
|
||||
an assertion from an IDP.
|
||||
|
||||
There are currently two supported authentication flows
|
||||
|
||||
1. IDP Initiated flow - example: You login in directly to Okta, and then select a web application to be authenticated for.
|
||||
Okta, the IDP, sends an assertion to the web application, the SP.
|
||||
2. SP Initiated flow - example: You access a web application, a SP, the application sends an
|
||||
authentication request to the IDP requesting an assertion. Upon successful authentication on the IDP,
|
||||
the IDP sends an assertion to the SP.
|
||||
|
||||
[[samllogin-feature-set]]
|
||||
=== Saml 2 Login - Current Feature Set
|
||||
|
||||
1. Service Provider (SP/Relying Party) is identified by `entityId = {baseUrl}/saml2/service-provider-metadata/{registrationId}`
|
||||
2. Receive assertion embedded in a SAML response via Http-POST or Http-Redirect at `{baseUrl}/login/saml2/sso/{registrationId}`
|
||||
3. Requires the assertion to be signed, unless the response is signed
|
||||
4. Supports encrypted assertions
|
||||
5. Supports encrypted NameId elements
|
||||
6. Allows for extraction of assertion attributes into authorities using a `Converter<Assertion, Collection<? extends GrantedAuthority>>`
|
||||
7. Allows mapping and white listing of authorities using a `GrantedAuthoritiesMapper`
|
||||
8. Public keys in `java.security.cert.X509Certificate` format.
|
||||
9. SP Initiated Authentication via an `AuthNRequest`
|
||||
|
||||
==== Saml 2 Login - Not Yet Supported
|
||||
|
||||
1. Mappings assertion conditions and attributes to session features (timeout, tracking, etc)
|
||||
2. Single logout
|
||||
3. Dynamic metadata generation
|
||||
4. Receiving and validating standalone assertion (not wrapped in a response object)
|
||||
|
||||
[[samllogin-introduction-java-config]]
|
||||
=== Saml 2 Login - Introduction to Java Configuration
|
||||
|
||||
To add `saml2Login()` to a Spring Security filter chain,
|
||||
the minimal Java configuration requires a configuration repository,
|
||||
the `RelyingPartyRegistrationRepository`, that contains the SAML configuration and
|
||||
the invocation of the `HttpSecurity.saml2Login()` method:
|
||||
[source,java]
|
||||
----
|
||||
@EnableWebSecurity
|
||||
public class SecurityConfig extends WebSecurityConfigurerAdapter {
|
||||
|
||||
@Bean
|
||||
public RelyingPartyRegistrationRepository relyingPartyRegistrationRepository() {
|
||||
//SAML configuration
|
||||
//Mapping this application to one or more Identity Providers
|
||||
return new InMemoryRelyingPartyRegistrationRepository(...);
|
||||
}
|
||||
|
||||
@Override
|
||||
protected void configure(HttpSecurity http) throws Exception {
|
||||
http
|
||||
.authorizeRequests()
|
||||
.anyRequest().authenticated()
|
||||
.and()
|
||||
.saml2Login()
|
||||
;
|
||||
}
|
||||
}
|
||||
----
|
||||
|
||||
The bean declaration is a convenient, but optional, approach.
|
||||
You can directly wire up the repository using a method call
|
||||
[source,java]
|
||||
----
|
||||
@EnableWebSecurity
|
||||
public class SecurityConfig extends WebSecurityConfigurerAdapter {
|
||||
|
||||
@Override
|
||||
protected void configure(HttpSecurity http) throws Exception {
|
||||
http
|
||||
.authorizeRequests()
|
||||
.anyRequest().authenticated()
|
||||
.and()
|
||||
.saml2Login()
|
||||
.relyingPartyRegistrationRepository(...)
|
||||
;
|
||||
}
|
||||
}
|
||||
----
|
||||
|
||||
==== RelyingPartyRegistration
|
||||
The https://github.com/spring-projects/spring-security/blob/5.2.0.RELEASE/saml2/saml2-service-provider/src/main/java/org/springframework/security/saml2/provider/service/registration/RelyingPartyRegistration.java[`RelyingPartyRegistration`]
|
||||
object represents the mapping between this application, the SP, and the asserting party, the IDP.
|
||||
|
||||
===== URI Patterns
|
||||
|
||||
URI patterns are frequenty used to automatically generate URIs based on
|
||||
an incoming request. The URI patterns in `saml2Login` can contain the following variables
|
||||
|
||||
* `baseUrl`
|
||||
* `registrationId`
|
||||
* `baseScheme`
|
||||
* `baseHost`
|
||||
* `basePort`
|
||||
|
||||
For example:
|
||||
```
|
||||
{baseUrl}/login/saml2/sso/{registrationId}
|
||||
```
|
||||
|
||||
===== Relying Party
|
||||
|
||||
|
||||
* `registrationId` - (required) a unique identifer for this configuration mapping.
|
||||
This identifier may be used in URI paths, so care should be taken that no URI encoding is required.
|
||||
* `localEntityIdTemplate` - (optional) A URI pattern that creates an entity ID for this application based on the incoming request. The default is
|
||||
`{baseUrl}/saml2/service-provider-metadata/{registrationId}` and for a small sample application
|
||||
it would look like
|
||||
```
|
||||
http://localhost:8080/saml2/service-provider-metadata/my-test-configuration
|
||||
```
|
||||
There is no requirement that this configuration option is a pattern, it can be a fixed URI value.
|
||||
|
||||
* `remoteIdpEntityId` - (required) the entity ID of the Identity Provider. Always a fixed URI value or string,
|
||||
no patterns allowed.
|
||||
* `assertionConsumerServiceUrlTemplate` - (optional) A URI pattern that denotes the assertion
|
||||
consumer service URI to be sent with any `AuthNRequest` from the SP to the IDP during the SP initiated flow.
|
||||
While this can be a pattern the actual URI must resolve to the ACS endpoint on the SP.
|
||||
The default value is `{baseUrl}/login/saml2/sso/{registrationId}` and maps directly to the
|
||||
https://github.com/spring-projects/spring-security/blob/5.2.0.RELEASE/saml2/saml2-service-provider/src/main/java/org/springframework/security/saml2/provider/service/servlet/filter/Saml2WebSsoAuthenticationFilter.java#L42[`Saml2WebSsoAuthenticationFilter`] endpoint
|
||||
* `idpWebSsoUrl` - (required) a fixed URI value for the IDP Single Sign On endpoint where
|
||||
the SP sends the `AuthNRequest` messages.
|
||||
* `credentials` - A list of credentials, private keys and x509 certificates, used for
|
||||
message signing, verification, encryption and decryption.
|
||||
This list can contain redundant credentials to allow for easy rotation of credentials.
|
||||
For example
|
||||
** [0] - X509Certificate{VERIFICATION,ENCRYPTION} - The IDP's first public key used for
|
||||
verification and encryption.
|
||||
** [1] - X509Certificate/{VERIFICATION,ENCRYPTION} - The IDP's second verification key used for verification.
|
||||
Encryption is always done using the first `ENCRYPTION` key in the list.
|
||||
** [2] - PrivateKey/X509Certificate{SIGNING,DECRYPTION} - The SP's first signing and decryption credential.
|
||||
** [3] - PrivateKey/X509Certificate{SIGNING,DECRYPTION} - The SP's second decryption credential.
|
||||
Signing is always done using the first `SIGNING` key in the list.
|
||||
|
||||
When an incoming message is received, signatures are always required, the system will first attempt
|
||||
to validate the signature using the certificate at index [0] and only move to the second
|
||||
credential if the first one fails.
|
||||
|
||||
In a similar fashion, the SP configured private keys are used for decryption and attempted in the same order.
|
||||
The first SP credential (`type=SIGNING`) will be used when messages to the IDP are signed.
|
||||
|
||||
===== Duplicated Relying Party Configurations
|
||||
|
||||
In the use case where an application uses multiple identity providers it becomes
|
||||
obvious that some configuration is duplicated between two `RelyingPartyRegistration` objects
|
||||
|
||||
* localEntityIdTemplate
|
||||
* credentials (all SP credentials, IDP credentials change)
|
||||
* assertionConsumerServiceUrlTemplate
|
||||
|
||||
While there is some drawback in duplicating configuration values the back end
|
||||
configuration repository does not need to replicate this data storage model.
|
||||
|
||||
There is a benefit that comes with this setup. Credentials may be more easily rotated
|
||||
for some identity providers vs others. This object model can ensure that there is no
|
||||
disruption when configuration is changed in a multi IDP use case and you're not able to rotate
|
||||
credentials on all the identity providers.
|
||||
|
||||
==== Service Provider Metadata
|
||||
|
||||
The Spring Security SAML 2 implementation does not yet provide an endpoint for downloading
|
||||
SP metadata in XML format. The minimal pieces that are exchanged
|
||||
|
||||
* *entity ID* - defaults to `{baseUrl}/saml2/service-provider-metadata/{registrationId}`
|
||||
Other known configuration names that also use this same value
|
||||
** Audience Restriction
|
||||
* *single signon URL* - defaults to `{baseUrl}/login/saml2/sso/{registrationId}`
|
||||
Other known configuration names that also use this same value
|
||||
** Recipient URL
|
||||
** Destination URL
|
||||
** Assertion Consumer Service URL
|
||||
* X509Certificate - the certificate that you configure as part of your {SIGNING,DECRYPTION}
|
||||
credentials must be shared with the Identity Provider
|
||||
|
||||
==== Authentication Requests - SP Initiated Flow
|
||||
|
||||
To initiate an authentication from the web application, a simple redirect to
|
||||
```
|
||||
{baseUrl}/saml2/authenticate/{registrationId}
|
||||
```
|
||||
The endpoint will generate an `AuthNRequest` by invoking the `createAuthenticationRequest` method on a
|
||||
configurable factory. Just expose the `Saml2AuthenticationRequestFactory` as a bean in your configuration.
|
||||
[source,java]
|
||||
----
|
||||
public interface Saml2AuthenticationRequestFactory {
|
||||
String createAuthenticationRequest(Saml2AuthenticationRequest request);
|
||||
}
|
||||
----
|
||||
|
||||
[[samllogin-sample-boot]]
|
||||
=== Spring Boot 2.x Sample
|
||||
|
||||
We are currently working with the the Spring Boot team on the
|
||||
https://github.com/spring-projects/spring-boot/issues/18260[Auto Configuration for Spring Security SAML Login].
|
||||
In the meantime, we have provided a Spring Boot sample that supports a Yaml configuration.
|
||||
|
||||
To run the sample, follow these three steps
|
||||
|
||||
1. Launch the Spring Boot application
|
||||
** `./gradlew :spring-security-samples-boot-saml2login:bootRun`
|
||||
2. Open a browser
|
||||
** http://localhost:8080/[http://localhost:8080/]
|
||||
3. This will take you to an identity provider, log in using:
|
||||
** User: `user`
|
||||
** Password: `password`
|
||||
|
||||
==== Multiple Identity Provider Sample
|
||||
|
||||
It's very simple to use multiple providers, but there are some defaults that
|
||||
may trip you up if you don't pay attention. In our SAML configuration of
|
||||
`RelyingPartyRegistration` objects, we default an SP entity ID to
|
||||
```
|
||||
{baseUrl}/saml2/service-provider-metadata/{registrationId}
|
||||
```
|
||||
|
||||
That means in our two provider configuration, our system would look like
|
||||
|
||||
```
|
||||
registration-1 (Identity Provider 1) - Our local SP Entity ID is:
|
||||
http://localhost:8080/saml2/service-provider-metadata/registration-1
|
||||
|
||||
registration-2 (Identity Provider 2) - Our local SP Entity ID is:
|
||||
http://localhost:8080/saml2/service-provider-metadata/registration-2
|
||||
```
|
||||
|
||||
In this configuration, illustrated in the sample below, to the outside world,
|
||||
we have actually created two virtual Service Provider identities
|
||||
hosted within the same application.
|
||||
|
||||
[source,yaml]
|
||||
----
|
||||
spring:
|
||||
security:
|
||||
saml2:
|
||||
login:
|
||||
relying-parties:
|
||||
- entity-id: &idp-entity-id https://simplesaml-for-spring-saml.cfapps.io/saml2/idp/metadata.php
|
||||
registration-id: simplesamlphp
|
||||
web-sso-url: &idp-sso-url https://simplesaml-for-spring-saml.cfapps.io/saml2/idp/SSOService.php
|
||||
signing-credentials: &service-provider-credentials
|
||||
- private-key: |
|
||||
-----BEGIN PRIVATE KEY-----
|
||||
MIICeAIBADANBgkqhkiG9w0BAQEFAASCAmIwggJeAgEAAoGBANG7v8QjQGU3MwQE
|
||||
...................SHORTENED FOR READ ABILITY...................
|
||||
INrtuLp4YHbgk1mi
|
||||
-----END PRIVATE KEY-----
|
||||
certificate: |
|
||||
-----BEGIN CERTIFICATE-----
|
||||
MIICgTCCAeoCCQCuVzyqFgMSyDANBgkqhkiG9w0BAQsFADCBhDELMAkGA1UEBhMC
|
||||
...................SHORTENED FOR READ ABILITY...................
|
||||
RZ/nbTJ7VTeZOSyRoVn5XHhpuJ0B
|
||||
-----END CERTIFICATE-----
|
||||
verification-credentials: &idp-certificates
|
||||
- |
|
||||
-----BEGIN CERTIFICATE-----
|
||||
MIIEEzCCAvugAwIBAgIJAIc1qzLrv+5nMA0GCSqGSIb3DQEBCwUAMIGfMQswCQYD
|
||||
...................SHORTENED FOR READ ABILITY...................
|
||||
lx13Y1YlQ4/tlpgTgfIJxKV6nyPiLoK0nywbMd+vpAirDt2Oc+hk
|
||||
-----END CERTIFICATE-----
|
||||
- entity-id: *idp-entity-id
|
||||
registration-id: simplesamlphp2
|
||||
web-sso-url: *idp-sso-url
|
||||
signing-credentials: *service-provider-credentials
|
||||
verification-credentials: *idp-certificates
|
||||
----
|
||||
|
||||
If this is not desirable, you can manually override the local SP entity ID by using the
|
||||
```
|
||||
localEntityIdTemplate = {baseUrl}/saml2/service-provider-metadata
|
||||
```
|
||||
If we change our local SP entity ID to this value, it is still important that we give
|
||||
out the correct single sign on URL (the assertion consumer service URL)
|
||||
for each registered identity provider based on the registration Id.
|
||||
`{baseUrl}/login/saml2/sso/{registrationId}`
|
||||
|
||||
|
||||
Loading…
Reference in New Issue