此版本仍在开发中,尚未被视为稳定版本。对于最新的稳定版本,请使用 Spring Security 6.4.3! |
执行单点注销
在其其他注销机制中,Spring Security 附带了对 RP 和 AP 启动的 SAML 2.0 单点注销的支持。
简而言之,Spring Security 支持两种用例:
-
RP 启动的 - 您的应用程序有一个终端节点,当 POST 到该终端节点时,将注销用户并发送一个
saml2:LogoutRequest
对主张方。 此后,置位方将发回saml2:LogoutResponse
并允许应用程序响应 -
AP 启动的 - 您的应用程序有一个终端节点,该终端节点将接收
saml2:LogoutRequest
来自主张方。 您的应用程序将在此时完成注销,然后发送一个saml2:LogoutResponse
对主张方。
在 AP 发起的场景中,您的应用程序在注销后执行的任何本地重定向都将变得毫无意义。
应用程序发送saml2:LogoutResponse ,则它不再具有对浏览器的控制权。 |
单点注销的最小配置
要使用 Spring Security 的 SAML 2.0 单点注销功能,您需要满足以下条件:
-
首先,断言方必须支持 SAML 2.0 单点注销
-
其次,应将断言方配置为签名和 POST
saml2:LogoutRequest
s 和saml2:LogoutResponse
是应用程序的/logout/saml2/slo
端点 -
第三,您的应用程序必须具有 PKCS#8 私钥和 X.509 证书进行签名
saml2:LogoutRequest
s 和saml2:LogoutResponse
s
你可以通过以下方式在 Spring Boot 中实现这一点:
spring:
security:
saml2:
relyingparty:
registration:
metadata:
signing.credentials: (3)
- private-key-location: classpath:credentials/rp-private.key
certificate-location: classpath:credentials/rp-certificate.crt
singlelogout.url: "{baseUrl}/logout/saml2/slo" (2)
assertingparty:
metadata-uri: https://ap.example.com/metadata (1)
1 | - IDP 的元数据 URI,它将向您的应用程序表明它对 SLO 的支持 |
2 | - 应用程序中的 SLO 终端节点 |
3 | - 要签名的签名凭证<saml2:LogoutRequest> s 和<saml2:LogoutResponse> s |
An asserting party supports Single Logout if their metadata includes the `<SingleLogoutService>` element in their metadata.
就是这样!
Spring Security 的注销支持提供了许多配置点。 请考虑以下使用案例:
创业期望
使用这些属性时,除了登录之外,SAML 2.0 服务提供商还将通过以下方式自动配置自身以方便注销<saml2:LogoutRequest>
s 和<saml2:LogoutResponse>
使用 RP 或 AP 发起的注销。
它通过确定性启动过程来实现这一点:
-
查询 Identity Server 元数据端点以获取
<SingleLogoutService>
元素 -
扫描元数据并缓存任何公共签名验证密钥
-
准备适当的终端节点
此过程的结果是,Identity Server 必须启动并接收请求,Service Provider 才能成功启动。
如果 Service Provider 查询 Identity Server 时 Identity Server 已关闭(给定适当的超时),则启动将失败。 |
运行时预期
给定上述配置,任何登录用户都可以发送POST /logout
添加到您的应用程序以执行 RP 发起的 SLO。
然后,您的应用程序将执行以下作:
-
注销用户并使会话失效
-
生成一个
<saml2:LogoutRequest>
并将其 POST 到关联断言方的 SLO 端点 -
然后,如果置言方使用
<saml2:LogoutResponse>
,应用程序将验证它并重定向到配置的成功端点
此外,当置言方发送<saml2:LogoutRequest>
自/logout/saml2/slo
.
发生这种情况时,您的应用程序将执行以下作:
-
验证
<saml2:LogoutRequest>
-
注销用户并使会话失效
-
生成一个
<saml2:LogoutResponse>
并将其 POST 回断言方的 SLO 端点
最小配置 Sans Boot
除了 Boot 属性之外,您还可以通过直接发布 bean 来获得相同的结果,如下所示:
-
Java
-
Kotlin
@Configuration
public class SecurityConfig {
@Value("${private.key}") RSAPrivateKey key;
@Value("${public.certificate}") X509Certificate certificate;
@Bean
RelyingPartyRegistrationRepository registrations() {
Saml2X509Credential credential = Saml2X509Credential.signing(key, certificate);
RelyingPartyRegistration registration = RelyingPartyRegistrations
.fromMetadataLocation("https://ap.example.org/metadata") (1)
.registrationId("metadata")
.singleLogoutServiceLocation("{baseUrl}/logout/saml2/slo") (2)
.signingX509Credentials((signing) -> signing.add(credential)) (3)
.build();
return new InMemoryRelyingPartyRegistrationRepository(registration);
}
@Bean
SecurityFilterChain web(HttpSecurity http) throws Exception {
http
.authorizeHttpRequests((authorize) -> authorize
.anyRequest().authenticated()
)
.saml2Login(withDefaults())
.saml2Logout(withDefaults()); (4)
return http.build();
}
}
@Configuration
class SecurityConfig(@Value("${private.key}") val key: RSAPrivateKey,
@Value("${public.certificate}") val certificate: X509Certificate) {
@Bean
fun registrations(): RelyingPartyRegistrationRepository {
val credential = Saml2X509Credential.signing(key, certificate)
val registration = RelyingPartyRegistrations
.fromMetadataLocation("https://ap.example.org/metadata") (1)
.registrationId("metadata")
.singleLogoutServiceLocation("{baseUrl}/logout/saml2/slo") (2)
.signingX509Credentials({ signing: List<Saml2X509Credential> -> signing.add(credential) }) (3)
.build()
return InMemoryRelyingPartyRegistrationRepository(registration)
}
@Bean
fun web(http: HttpSecurity): SecurityFilterChain {
http {
authorizeHttpRequests {
anyRequest = authenticated
}
saml2Login {
}
saml2Logout { (4)
}
}
return http.build()
}
}
1 | - IDP 的元数据 URI,它将向您的应用程序表明它对 SLO 的支持 |
2 | - 应用程序中的 SLO 终端节点 |
3 | - 要签名的签名凭证<saml2:LogoutRequest> s 和<saml2:LogoutResponse> s,您也可以将其添加到多个信赖方 |
4 | - 其次,指示您的应用程序希望使用 SAML SLO 注销最终用户 |
添加saml2Logout 将注销功能添加到整个服务提供商。
因为它是一项可选功能,所以您需要为每个人启用它RelyingPartyRegistration .
您可以通过设置RelyingPartyRegistration.Builder#singleLogoutServiceLocation 属性,如上所示。 |
Saml 2.0 注销的工作原理
接下来,让我们看看 Spring Security 用于在基于 servlet 的应用程序中支持 SAML 2.0 注销的架构组件,就像我们刚刚看到的一样。
对于 RP 发起的注销:
Spring Security 执行其注销流,调用其
LogoutHandler
s 使会话失效并执行其他清理。
然后,它会调用Saml2RelyingPartyInitiatedLogoutSuccessHandler
.
注销成功处理程序使用
Saml2LogoutRequestResolver
要创建、签署和序列化<saml2:LogoutRequest>
.
它使用RelyingPartyRegistration
与当前Saml2AuthenticatedPrincipal
.
然后,它会重定向 POST<saml2:LogoutRequest>
到断言方 SLO 终端节点
浏览器将控制权移交给断言方。
如果断言方重定向回去(它可能不会重定向),则应用程序将继续执行步骤 。
这
Saml2LogoutResponseFilter
反序列化、验证和处理<saml2:LogoutResponse>
及其Saml2LogoutResponseValidator
.
如果有效,则它会通过重定向到
/login?logout
或任何已配置的内容。
如果无效,则以 400 响应。
对于 AP 发起的注销:
这
Saml2LogoutRequestFilter
反序列化、验证和处理<saml2:LogoutRequest>
及其Saml2LogoutRequestValidator
.
如果有效,则过滤器会调用配置的
LogoutHandler
s,使会话失效并执行其他清理。
它使用
Saml2LogoutResponseResolver
要创建、签署和序列化<saml2:LogoutResponse>
.
它使用RelyingPartyRegistration
派生自端点或<saml2:LogoutRequest>
.
然后,它会重定向 POST<saml2:LogoutResponse>
拖动到断言方 SLO 终端节点。
浏览器将控制权移交给断言方。
如果无效,则以 400 响应。
配置 Logout 端点
有三种行为可以由不同的终端节点触发:
-
RP 发起的注销,允许经过身份验证的用户
POST
并通过向断言方发送<saml2:LogoutRequest>
-
AP 发起的注销,允许断言方发送
<saml2:LogoutRequest>
前往应用 -
AP 注销响应,允许断言方发送
<saml2:LogoutResponse>
响应 RP 发起的<saml2:LogoutRequest>
第一个是通过执行 normal 触发的POST /logout
当 principal 的类型为Saml2AuthenticatedPrincipal
.
第二个是通过 POST 到/logout/saml2/slo
端点,其中SAMLRequest
由主张方签名。
第三个是通过 POST 到/logout/saml2/slo
端点,其中SAMLResponse
由主张方签名。
由于用户已登录或原始注销请求已知,因此registrationId
已经知道了。
因此,{registrationId}
默认情况下,它不是这些 URL 的一部分。
此 URL 可在 DSL 中自定义。
例如,如果要将现有的依赖方迁移到 Spring Security,则断言方可能已经指向GET /SLOService.saml2
.
要减少断言方的配置更改,您可以在 DSL 中配置过滤器,如下所示:
-
Java
-
Kotlin
http
.saml2Logout((saml2) -> saml2
.logoutRequest((request) -> request.logoutUrl("/SLOService.saml2"))
.logoutResponse((response) -> response.logoutUrl("/SLOService.saml2"))
);
http {
saml2Logout {
logoutRequest {
logoutUrl = "/SLOService.saml2"
}
logoutResponse {
logoutUrl = "/SLOService.saml2"
}
}
}
您还应该在RelyingPartyRegistration
.
此外,您还可以自定义用于在本地触发注销的终端节点,如下所示:
-
Java
-
Kotlin
http
.saml2Logout((saml2) -> saml2.logoutUrl("/saml2/logout"));
http {
saml2Logout {
logoutUrl = "/saml2/logout"
}
}
将本地注销与 SAML 2.0 注销分开
在某些情况下,您可能希望为本地注销公开一个注销终端节点,为 RP 发起的 SLO 公开另一个注销终端节点。 与其他注销机制一样,您可以注册多个,只要它们都有不同的终端节点即可。
因此,例如,您可以像这样连接 DSL:
-
Java
-
Kotlin
http
.logout((logout) -> logout.logoutUrl("/logout"))
.saml2Logout((saml2) -> saml2.logoutUrl("/saml2/logout"));
http {
logout {
logoutUrl = "/logout"
}
saml2Logout {
logoutUrl = "/saml2/logout"
}
}
现在,如果客户端发送POST /logout
,会话将被清除,但不会有<saml2:LogoutRequest>
发送给断言方。
但是,如果客户端发送POST /saml2/logout
,则应用程序将照常启动 SAML 2.0 SLO。
定制<saml2:LogoutRequest>
分辨率
通常需要在<saml2:LogoutRequest>
比 Spring Security 提供的默认值。
默认情况下,Spring Security 将发出<saml2:LogoutRequest>
和供应:
-
这
Destination
属性 - 从RelyingPartyRegistration#getAssertingPartyMetadata#getSingleLogoutServiceLocation
-
这
ID
属性 - 一个 GUID -
这
<Issuer>
元素 - 从RelyingPartyRegistration#getEntityId
-
这
<NameID>
元素 - 从Authentication#getName
要添加其他值,您可以使用 delegation,如下所示:
-
Java
-
Kotlin
@Bean
Saml2LogoutRequestResolver logoutRequestResolver(RelyingPartyRegistrationRepository registrations) {
OpenSaml4LogoutRequestResolver logoutRequestResolver =
new OpenSaml4LogoutRequestResolver(registrations);
logoutRequestResolver.setParametersConsumer((parameters) -> {
String name = ((Saml2AuthenticatedPrincipal) parameters.getAuthentication().getPrincipal()).getFirstAttribute("CustomAttribute");
String format = "urn:oasis:names:tc:SAML:2.0:nameid-format:transient";
LogoutRequest logoutRequest = parameters.getLogoutRequest();
NameID nameId = logoutRequest.getNameID();
nameId.setValue(name);
nameId.setFormat(format);
});
return logoutRequestResolver;
}
@Bean
open fun logoutRequestResolver(registrations:RelyingPartyRegistrationRepository?): Saml2LogoutRequestResolver {
val logoutRequestResolver = OpenSaml4LogoutRequestResolver(registrations)
logoutRequestResolver.setParametersConsumer { parameters: LogoutRequestParameters ->
val name: String = (parameters.getAuthentication().getPrincipal() as Saml2AuthenticatedPrincipal).getFirstAttribute("CustomAttribute")
val format = "urn:oasis:names:tc:SAML:2.0:nameid-format:transient"
val logoutRequest: LogoutRequest = parameters.getLogoutRequest()
val nameId: NameID = logoutRequest.getNameID()
nameId.setValue(name)
nameId.setFormat(format)
}
return logoutRequestResolver
}
然后,您可以提供您的自定义Saml2LogoutRequestResolver
在 DSL 中,如下所示:
-
Java
-
Kotlin
http
.saml2Logout((saml2) -> saml2
.logoutRequest((request) -> request
.logoutRequestResolver(this.logoutRequestResolver)
)
);
http {
saml2Logout {
logoutRequest {
logoutRequestResolver = this.logoutRequestResolver
}
}
}
定制<saml2:LogoutResponse>
分辨率
通常需要在<saml2:LogoutResponse>
比 Spring Security 提供的默认值。
默认情况下,Spring Security 将发出<saml2:LogoutResponse>
和供应:
-
这
Destination
属性 - 从RelyingPartyRegistration#getAssertingPartyMetadata#getSingleLogoutServiceResponseLocation
-
这
ID
属性 - 一个 GUID -
这
<Issuer>
元素 - 从RelyingPartyRegistration#getEntityId
-
这
<Status>
元素-SUCCESS
要添加其他值,您可以使用 delegation,如下所示:
-
Java
-
Kotlin
@Bean
public Saml2LogoutResponseResolver logoutResponseResolver(RelyingPartyRegistrationRepository registrations) {
OpenSaml4LogoutResponseResolver logoutRequestResolver =
new OpenSaml4LogoutResponseResolver(registrations);
logoutRequestResolver.setParametersConsumer((parameters) -> {
if (checkOtherPrevailingConditions(parameters.getRequest())) {
parameters.getLogoutRequest().getStatus().getStatusCode().setCode(StatusCode.PARTIAL_LOGOUT);
}
});
return logoutRequestResolver;
}
@Bean
open fun logoutResponseResolver(registrations: RelyingPartyRegistrationRepository?): Saml2LogoutResponseResolver {
val logoutRequestResolver = OpenSaml4LogoutResponseResolver(registrations)
logoutRequestResolver.setParametersConsumer { LogoutResponseParameters parameters ->
if (checkOtherPrevailingConditions(parameters.getRequest())) {
parameters.getLogoutRequest().getStatus().getStatusCode().setCode(StatusCode.PARTIAL_LOGOUT)
}
}
return logoutRequestResolver
}
然后,您可以提供您的自定义Saml2LogoutResponseResolver
在 DSL 中,如下所示:
-
Java
-
Kotlin
http
.saml2Logout((saml2) -> saml2
.logoutRequest((request) -> request
.logoutRequestResolver(this.logoutRequestResolver)
)
);
http {
saml2Logout {
logoutRequest {
logoutRequestResolver = this.logoutRequestResolver
}
}
}
定制<saml2:LogoutRequest>
认证
要自定义验证,您可以实现自己的验证Saml2LogoutRequestValidator
.
此时,验证是最小的,因此您可以首先委托给默认的Saml2LogoutRequestValidator
这样:
-
Java
-
Kotlin
@Component
public class MyOpenSamlLogoutRequestValidator implements Saml2LogoutRequestValidator {
private final Saml2LogoutRequestValidator delegate = new OpenSamlLogoutRequestValidator();
@Override
public Saml2LogoutRequestValidator logout(Saml2LogoutRequestValidatorParameters parameters) {
// verify signature, issuer, destination, and principal name
Saml2LogoutValidatorResult result = delegate.authenticate(authentication);
LogoutRequest logoutRequest = // ... parse using OpenSAML
// perform custom validation
}
}
@Component
open class MyOpenSamlLogoutRequestValidator: Saml2LogoutRequestValidator {
private val delegate = OpenSamlLogoutRequestValidator()
@Override
fun logout(parameters: Saml2LogoutRequestValidatorParameters): Saml2LogoutRequestValidator {
// verify signature, issuer, destination, and principal name
val result = delegate.authenticate(authentication)
val logoutRequest: LogoutRequest = // ... parse using OpenSAML
// perform custom validation
}
}
然后,您可以提供您的自定义Saml2LogoutRequestValidator
在 DSL 中,如下所示:
-
Java
-
Kotlin
http
.saml2Logout((saml2) -> saml2
.logoutRequest((request) -> request
.logoutRequestValidator(myOpenSamlLogoutRequestValidator)
)
);
http {
saml2Logout {
logoutRequest {
logoutRequestValidator = myOpenSamlLogoutRequestValidator
}
}
}
定制<saml2:LogoutResponse>
认证
要自定义验证,您可以实现自己的验证Saml2LogoutResponseValidator
.
此时,验证是最小的,因此您可以首先委托给默认的Saml2LogoutResponseValidator
这样:
-
Java
-
Kotlin
@Component
public class MyOpenSamlLogoutResponseValidator implements Saml2LogoutResponseValidator {
private final Saml2LogoutResponseValidator delegate = new OpenSamlLogoutResponseValidator();
@Override
public Saml2LogoutValidatorResult logout(Saml2LogoutResponseValidatorParameters parameters) {
// verify signature, issuer, destination, and status
Saml2LogoutValidatorResult result = delegate.authenticate(parameters);
LogoutResponse logoutResponse = // ... parse using OpenSAML
// perform custom validation
}
}
@Component
open class MyOpenSamlLogoutResponseValidator: Saml2LogoutResponseValidator {
private val delegate = OpenSaml4LogoutResponseValidator()
@Override
fun logout(parameters: Saml2LogoutResponseValidatorParameters): Saml2LogoutResponseValidator {
// verify signature, issuer, destination, and status
val result = delegate.authenticate(authentication)
val logoutResponse: LogoutResponse = // ... parse using OpenSAML
// perform custom validation
}
}
然后,您可以提供您的自定义Saml2LogoutResponseValidator
在 DSL 中,如下所示:
-
Java
-
Kotlin
http
.saml2Logout((saml2) -> saml2
.logoutResponse((response) -> response
.logoutResponseAuthenticator(myOpenSamlLogoutResponseAuthenticator)
)
);
http {
saml2Logout {
logoutResponse {
logoutResponseValidator = myOpenSamlLogoutResponseValidator
}
}
}
定制<saml2:LogoutRequest>
存储
当您的应用程序发送<saml2:LogoutRequest>
,该值将存储在会话中,以便RelayState
参数和InResponseTo
属性中的<saml2:LogoutResponse>
可以验证。
如果你想将注销请求存储在会话以外的某个地方,你可以在 DSL 中提供你的自定义实现,如下所示:
-
Java
-
Kotlin
http
.saml2Logout((saml2) -> saml2
.logoutRequest((request) -> request
.logoutRequestRepository(myCustomLogoutRequestRepository)
)
);
http {
saml2Logout {
logoutRequest {
logoutRequestRepository = myCustomLogoutRequestRepository
}
}
}
更多与 Logout 相关的参考
-
在 CSRF 注意事项 一节中注销