Skip to content

Commit ea1a5b1

Browse files
author
Steve Riesenberg
committed
Add documentation for OAuth 2.0 Device Authorization Grant
Closes gh-1158
1 parent 7c166a3 commit ea1a5b1

File tree

2 files changed

+111
-3
lines changed

2 files changed

+111
-3
lines changed

‎docs/src/docs/asciidoc/overview.adoc‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,13 +24,18 @@ Spring Authorization Server supports the following features:
2424
** xref:protocol-endpoints.adoc#oauth2-authorization-endpoint[User Consent]
2525
* Client Credentials
2626
* Refresh Token
27+
* Device Code
28+
** xref:protocol-endpoints.adoc#oauth2-device-verification-endpoint[User Consent]
2729
|
2830
* The OAuth 2.1 Authorization Framework (https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-07[draft])
2931
** https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-07#section-4.1[Authorization Code Grant]
3032
** https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-07#section-4.2[Client Credentials Grant]
3133
** https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-07#section-4.3[Refresh Token Grant]
3234
* OpenID Connect Core 1.0 (https://openid.net/specs/openid-connect-core-1_0.html[spec])
3335
** https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth[Authorization Code Flow]
36+
* OAuth 2.0 Device Authorization Grant
37+
(https://tools.ietf.org/html/rfc8628[spec])
38+
** https://tools.ietf.org/html/rfc8628#section-3[Device Flow]
3439

3540
|xref:core-model-components.adoc#oauth2-token-generator[Token Formats]
3641
|
@@ -55,6 +60,8 @@ Spring Authorization Server supports the following features:
5560
|xref:protocol-endpoints.adoc[Protocol Endpoints]
5661
|
5762
* xref:protocol-endpoints.adoc#oauth2-authorization-endpoint[OAuth2 Authorization Endpoint]
63+
* xref:protocol-endpoints.adoc#oauth2-device-authorization-endpoint[OAuth2 Device Authorization Endpoint]
64+
* xref:protocol-endpoints.adoc#oauth2-device-verification-endpoint[OAuth2 Device Verification Endpoint]
5865
* xref:protocol-endpoints.adoc#oauth2-token-endpoint[OAuth2 Token Endpoint]
5966
* xref:protocol-endpoints.adoc#oauth2-token-introspection-endpoint[OAuth2 Token Introspection Endpoint]
6067
* xref:protocol-endpoints.adoc#oauth2-token-revocation-endpoint[OAuth2 Token Revocation Endpoint]
@@ -67,6 +74,9 @@ Spring Authorization Server supports the following features:
6774
* The OAuth 2.1 Authorization Framework (https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-07[draft])
6875
** https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-07#section-3.1[Authorization Endpoint]
6976
** https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-07#section-3.2[Token Endpoint]
77+
* OAuth 2.0 Device Authorization Grant (https://tools.ietf.org/html/rfc8628[RFC 8628])
78+
** https://tools.ietf.org/html/rfc8628#section-3.1[Device Authorization Endpoint]
79+
** https://tools.ietf.org/html/rfc8628#section-3.3[Device Verification Endpoint]
7080
* OAuth 2.0 Token Introspection (https://tools.ietf.org/html/rfc7662[RFC 7662])
7181
* OAuth 2.0 Token Revocation (https://tools.ietf.org/html/rfc7009[RFC 7009])
7282
* OAuth 2.0 Authorization Server Metadata (https://tools.ietf.org/html/rfc8414[RFC 8414])

‎docs/src/docs/asciidoc/protocol-endpoints.adoc‎

Lines changed: 101 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -120,6 +120,104 @@ static class CustomRedirectUriValidator implements Consumer<OAuth2AuthorizationC
120120
}
121121
----
122122

123+
[[oauth2-device-authorization-endpoint]]
124+
== OAuth2 Device Authorization Endpoint
125+
126+
`OAuth2DeviceAuthorizationEndpointConfigurer` provides the ability to customize the https://datatracker.ietf.org/doc/html/rfc8628#section-3.1[OAuth2 Device Authorization Endpoint].
127+
It defines extension points that let you customize the pre-processing, main processing, and post-processing logic for OAuth2 device authorization requests.
128+
129+
`OAuth2DeviceAuthorizationEndpointConfigurer` provides the following configuration options:
130+
131+
[source,java]
132+
----
133+
@Bean
134+
public SecurityFilterChain authorizationServerSecurityFilterChain(HttpSecurity http) throws Exception {
135+
OAuth2AuthorizationServerConfigurer authorizationServerConfigurer =
136+
new OAuth2AuthorizationServerConfigurer();
137+
http.apply(authorizationServerConfigurer);
138+
139+
authorizationServerConfigurer
140+
.deviceAuthorizationEndpoint(deviceAuthorizationEndpoint ->
141+
deviceAuthorizationEndpoint
142+
.deviceAuthorizationRequestConverter(deviceAuthorizationRequestConverter) <1>
143+
.deviceAuthorizationRequestConverters(deviceAuthorizationRequestConvertersConsumer) <2>
144+
.authenticationProvider(authenticationProvider) <3>
145+
.authenticationProviders(authenticationProvidersConsumer) <4>
146+
.deviceAuthorizationResponseHandler(deviceAuthorizationResponseHandler) <5>
147+
.errorResponseHandler(errorResponseHandler) <6>
148+
.verificationUri("/oauth2/v1/device_authorization") <7>
149+
);
150+
151+
return http.build();
152+
}
153+
----
154+
<1> `deviceAuthorizationRequestConverter()`: Adds an `AuthenticationConverter` (_pre-processor_) used when attempting to extract an https://datatracker.ietf.org/doc/html/rfc8628#section-3.1[OAuth2 device authorization request] from `HttpServletRequest` to an instance of `OAuth2DeviceAuthorizationRequestAuthenticationToken`.
155+
<2> `deviceAuthorizationRequestConverters()`: Sets the `Consumer` providing access to the `List` of default and (optionally) added ``AuthenticationConverter``'s allowing the ability to add, remove, or customize a specific `AuthenticationConverter`.
156+
<3> `authenticationProvider()`: Adds an `AuthenticationProvider` (_main processor_) used for authenticating the `OAuth2DeviceAuthorizationRequestAuthenticationToken`.
157+
<4> `authenticationProviders()`: Sets the `Consumer` providing access to the `List` of default and (optionally) added ``AuthenticationProvider``'s allowing the ability to add, remove, or customize a specific `AuthenticationProvider`.
158+
<5> `deviceAuthorizationResponseHandler()`: The `AuthenticationSuccessHandler` (_post-processor_) used for handling an "`authenticated`" `OAuth2DeviceAuthorizationRequestAuthenticationToken` and returning the https://datatracker.ietf.org/doc/html/rfc8628#section-3.2[OAuth2DeviceAuthorizationResponse].
159+
<6> `errorResponseHandler()`: The `AuthenticationFailureHandler` (_post-processor_) used for handling an `OAuth2AuthenticationException` and returning the https://datatracker.ietf.org/doc/html/rfc6749#section-5.2[OAuth2Error response].
160+
<7> `verificationUri()`: The `URI` of the custom end-user verification page to direct resource owners to on a secondary device.
161+
162+
`OAuth2DeviceAuthorizationEndpointConfigurer` configures the `OAuth2DeviceAuthorizationEndpointFilter` and registers it with the OAuth2 authorization server `SecurityFilterChain` `@Bean`.
163+
`OAuth2DeviceAuthorizationEndpointFilter` is the `Filter` that processes OAuth2 device authorization requests.
164+
165+
`OAuth2DeviceAuthorizationEndpointFilter` is configured with the following defaults:
166+
167+
* `*AuthenticationConverter*` -- An `OAuth2DeviceAuthorizationRequestAuthenticationConverter`.
168+
* `*AuthenticationManager*` -- An `AuthenticationManager` composed of `OAuth2DeviceAuthorizationRequestAuthenticationProvider`.
169+
* `*AuthenticationSuccessHandler*` -- An internal implementation that handles an "`authenticated`" `OAuth2DeviceAuthorizationRequestAuthenticationToken` and returns the `OAuth2DeviceAuthorizationResponse`.
170+
* `*AuthenticationFailureHandler*` -- An internal implementation that uses the `OAuth2Error` associated with the `OAuth2AuthenticationException` and returns the `OAuth2Error` response.
171+
172+
[[oauth2-device-verification-endpoint]]
173+
== OAuth2 Device Verification Endpoint
174+
175+
`OAuth2DeviceVerificationEndpointConfigurer` provides the ability to customize the https://datatracker.ietf.org/doc/html/rfc8628#section-3.3[OAuth2 Device Verification endpoint] (or "User Interaction").
176+
It defines extension points that let you customize the pre-processing, main processing, and post-processing logic for OAuth2 device verification requests.
177+
178+
`OAuth2DeviceVerificationEndpointConfigurer` provides the following configuration options:
179+
180+
[source,java]
181+
----
182+
@Bean
183+
public SecurityFilterChain authorizationServerSecurityFilterChain(HttpSecurity http) throws Exception {
184+
OAuth2AuthorizationServerConfigurer authorizationServerConfigurer =
185+
new OAuth2AuthorizationServerConfigurer();
186+
http.apply(authorizationServerConfigurer);
187+
188+
authorizationServerConfigurer
189+
.deviceVerificationEndpoint(deviceVerificationEndpoint ->
190+
deviceVerificationEndpoint
191+
.deviceVerificationRequestConverter(deviceVerificationRequestConverter) <1>
192+
.deviceVerificationRequestConverters(deviceVerificationRequestConvertersConsumer) <2>
193+
.authenticationProvider(authenticationProvider) <3>
194+
.authenticationProviders(authenticationProvidersConsumer) <4>
195+
.deviceVerificationResponseHandler(deviceVerificationResponseHandler) <5>
196+
.errorResponseHandler(errorResponseHandler) <6>
197+
.consentPage("/oauth2/v1/consent") <7>
198+
);
199+
200+
return http.build();
201+
}
202+
----
203+
<1> `deviceVerificationRequestConverter()`: Adds an `AuthenticationConverter` (_pre-processor_) used when attempting to extract an https://datatracker.ietf.org/doc/html/rfc8628#section-3.3[OAuth2 device verification request] (or consent) from `HttpServletRequest` to an instance of `OAuth2DeviceVerificationAuthenticationToken` or `OAuth2DeviceAuthorizationConsentAuthenticationToken`.
204+
<2> `deviceVerificationRequestConverters()`: Sets the `Consumer` providing access to the `List` of default and (optionally) added ``AuthenticationConverter``'s allowing the ability to add, remove, or customize a specific `AuthenticationConverter`.
205+
<3> `authenticationProvider()`: Adds an `AuthenticationProvider` (_main processor_) used for authenticating the `OAuth2DeviceVerificationAuthenticationToken` or `OAuth2DeviceAuthorizationConsentAuthenticationToken`.
206+
<4> `authenticationProviders()`: Sets the `Consumer` providing access to the `List` of default and (optionally) added ``AuthenticationProvider``'s allowing the ability to add, remove, or customize a specific `AuthenticationProvider`.
207+
<5> `deviceVerificationResponseHandler()`: The `AuthenticationSuccessHandler` (_post-processor_) used for handling an "`authenticated`" `OAuth2DeviceVerificationAuthenticationToken` and directing the resource owner to return to their device.
208+
<6> `errorResponseHandler()`: The `AuthenticationFailureHandler` (_post-processor_) used for handling an `OAuth2AuthenticationException` and returning the error response.
209+
<7> `consentPage()`: The `URI` of the custom consent page to redirect resource owners to if consent is required during the device verification request flow.
210+
211+
`OAuth2DeviceVerificationEndpointConfigurer` configures the `OAuth2DeviceVerificationEndpointFilter` and registers it with the OAuth2 authorization server `SecurityFilterChain` `@Bean`.
212+
`OAuth2DeviceVerificationEndpointFilter` is the `Filter` that processes OAuth2 device verification requests (and consents).
213+
214+
`OAuth2DeviceVerificationEndpointFilter` is configured with the following defaults:
215+
216+
* `*AuthenticationConverter*` -- A `DelegatingAuthenticationConverter` composed of `OAuth2DeviceVerificationAuthenticationConverter` and `OAuth2DeviceAuthorizationConsentAuthenticationConverter`.
217+
* `*AuthenticationManager*` -- An `AuthenticationManager` composed of `OAuth2DeviceVerificationAuthenticationProvider` and `OAuth2DeviceAuthorizationConsentAuthenticationProvider`.
218+
* `*AuthenticationSuccessHandler*` -- A `SimpleUrlAuthenticationSuccessHandler` that handles an "`authenticated`" `OAuth2DeviceVerificationAuthenticationToken` and redirects the user to a success page (`/?success`).
219+
* `*AuthenticationFailureHandler*` -- An internal implementation that uses the `OAuth2Error` associated with the `OAuth2AuthenticationException` and returns the `OAuth2Error` response.
220+
123221
[[oauth2-token-endpoint]]
124222
== OAuth2 Token Endpoint
125223

@@ -159,12 +257,12 @@ public SecurityFilterChain authorizationServerSecurityFilterChain(HttpSecurity h
159257
`OAuth2TokenEndpointConfigurer` configures the `OAuth2TokenEndpointFilter` and registers it with the OAuth2 authorization server `SecurityFilterChain` `@Bean`.
160258
`OAuth2TokenEndpointFilter` is the `Filter` that processes OAuth2 access token requests.
161259

162-
The supported https://datatracker.ietf.org/doc/html/rfc6749#section-1.3[authorization grant types] are `authorization_code`, `refresh_token`, and `client_credentials`.
260+
The supported https://datatracker.ietf.org/doc/html/rfc6749#section-1.3[authorization grant types] are `authorization_code`, `refresh_token`, `client_credentials`, and `urn:ietf:params:oauth:grant-type:device_code`.
163261

164262
`OAuth2TokenEndpointFilter` is configured with the following defaults:
165263

166-
* `*AuthenticationConverter*` -- A `DelegatingAuthenticationConverter` composed of `OAuth2AuthorizationCodeAuthenticationConverter`, `OAuth2RefreshTokenAuthenticationConverter`, and `OAuth2ClientCredentialsAuthenticationConverter`.
167-
* `*AuthenticationManager*` -- An `AuthenticationManager` composed of `OAuth2AuthorizationCodeAuthenticationProvider`, `OAuth2RefreshTokenAuthenticationProvider`, and `OAuth2ClientCredentialsAuthenticationProvider`.
264+
* `*AuthenticationConverter*` -- A `DelegatingAuthenticationConverter` composed of `OAuth2AuthorizationCodeAuthenticationConverter`, `OAuth2RefreshTokenAuthenticationConverter`, `OAuth2ClientCredentialsAuthenticationConverter`, and `OAuth2DeviceCodeAuthenticationConverter`.
265+
* `*AuthenticationManager*` -- An `AuthenticationManager` composed of `OAuth2AuthorizationCodeAuthenticationProvider`, `OAuth2RefreshTokenAuthenticationProvider`, `OAuth2ClientCredentialsAuthenticationProvider`, and `OAuth2DeviceCodeAuthenticationProvider`.
168266
* `*AuthenticationSuccessHandler*` -- An internal implementation that handles an `OAuth2AccessTokenAuthenticationToken` and returns the `OAuth2AccessTokenResponse`.
169267
* `*AuthenticationFailureHandler*` -- An internal implementation that uses the `OAuth2Error` associated with the `OAuth2AuthenticationException` and returns the `OAuth2Error` response.
170268

0 commit comments

Comments
 (0)