Skip to content

Commit 93742a4

Browse files
jgrandjajgrandja
committed
Manual move of spring-projects/spring-authorization-server docs
Issue gh-17880
1 parent e5dc462 commit 93742a4

File tree

7 files changed

+2276
-0
lines changed

7 files changed

+2276
-0
lines changed

‎docs/modules/ROOT/pages/servlet/oauth2/authorization-server/configuration-model.adoc‎

Lines changed: 430 additions & 0 deletions
Large diffs are not rendered by default.

‎docs/modules/ROOT/pages/servlet/oauth2/authorization-server/core-model-components.adoc‎

Lines changed: 534 additions & 0 deletions
Large diffs are not rendered by default.

‎docs/modules/ROOT/pages/servlet/oauth2/authorization-server/getting-help.adoc‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
[[getting-help]]
2+
= Getting Help
3+
:page-section-summary-toc: 1
4+
5+
[[community]]
6+
== Community
7+
8+
Welcome to the https://docs.spring.io/spring-security/reference/community.html[Spring Security Community].
9+
Spring Authorization Server is an open source project led by the Spring Security team.
10+
If you need help with Spring Authorization Server, we are here to help.
11+
12+
[[resources]]
13+
== Resources
14+
15+
The following are some of the best ways to get help:
16+
17+
* Try the xref:how-to.adoc[How-to guides]. They provide solutions to the most common questions.
18+
* Learn the Spring Security basics that Spring Authorization Server builds on. If you are starting out with Spring Security, check the https://spring.io/projects/spring-security#learn[reference documentation] or try one of the https://github.com/spring-projects/spring-security-samples[samples].
19+
* Read through xref:index.adoc[this documentation].
20+
* Try one of our many https://github.com/spring-projects/spring-authorization-server/tree/main/samples[sample applications].
21+
* Ask a question on Stack Overflow with the https://stackoverflow.com/questions/tagged/spring-authorization-server[`spring-authorization-server`] tag.
22+
* Report bugs and enhancement requests on https://github.com/spring-projects/spring-authorization-server/issues[GitHub].
23+
24+
NOTE: Spring Authorization Server is open source, including the documentation. If you find problems with the docs or if you want to improve them, please https://github.com/spring-projects/spring-authorization-server[get involved].

‎docs/modules/ROOT/pages/servlet/oauth2/authorization-server/getting-started.adoc‎

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
2+
[[getting-started]]
3+
= Getting Started
4+
5+
If you are just getting started with Spring Authorization Server, the following sections walk you through creating your first application.
6+
7+
[[system-requirements]]
8+
== System Requirements
9+
10+
Spring Authorization Server requires a Java 17 or higher Runtime Environment.
11+
12+
[[installing-spring-authorization-server]]
13+
== Installing Spring Authorization Server
14+
15+
Spring Authorization Server can be used anywhere you already use https://docs.spring.io/spring-security/reference/prerequisites.html[Spring Security].
16+
17+
The easiest way to begin using Spring Authorization Server is by creating a https://spring.io/projects/spring-boot[Spring Boot]-based application.
18+
You can use https://start.spring.io[start.spring.io] to generate a basic project or use the https://github.com/spring-projects/spring-authorization-server/tree/main/samples/default-authorizationserver[default authorization server sample] as a guide.
19+
Then add Spring Boot's starter for Spring Authorization Server as a dependency:
20+
21+
[tabs]
22+
======
23+
Maven::
24+
+
25+
[[spring-boot-maven-dependency]]
26+
[source,xml,role="primary",subs="attributes,verbatim"]
27+
----
28+
<dependency>
29+
<groupId>org.springframework.boot</groupId>
30+
<artifactId>spring-boot-starter-oauth2-authorization-server</artifactId>
31+
</dependency>
32+
----
33+
34+
Gradle::
35+
+
36+
[[spring-boot-gradle-dependency]]
37+
[source,gradle,role="secondary",subs="attributes,verbatim"]
38+
----
39+
implementation "org.springframework.boot:spring-boot-starter-oauth2-authorization-server"
40+
----
41+
======
42+
43+
TIP: See https://docs.spring.io/spring-boot/docs/current/reference/html/getting-started.html#getting-started.installing[Installing Spring Boot] for more information on using Spring Boot with Maven or Gradle.
44+
45+
Alternatively, you can add Spring Authorization Server without Spring Boot using the following example:
46+
47+
[tabs]
48+
======
49+
Maven::
50+
+
51+
[[maven-dependency]]
52+
[source,xml,role="primary",subs="attributes,verbatim"]
53+
----
54+
<dependency>
55+
<groupId>org.springframework.security</groupId>
56+
<artifactId>spring-security-oauth2-authorization-server</artifactId>
57+
<version>{spring-authorization-server-version}</version>
58+
</dependency>
59+
----
60+
61+
Gradle::
62+
+
63+
[[gradle-dependency]]
64+
[source,gradle,role="secondary",subs="attributes,verbatim"]
65+
----
66+
implementation "org.springframework.security:spring-security-oauth2-authorization-server:{spring-authorization-server-version}"
67+
----
68+
======
69+
70+
[[developing-your-first-application]]
71+
== Developing Your First Application
72+
73+
To get started, you need the minimum required components defined as a `@Bean`. When using the `spring-boot-starter-oauth2-authorization-server` dependency, define the following properties and Spring Boot will provide the necessary `@Bean` definitions for you:
74+
75+
[[application-yml]]
76+
.application.yml
77+
[source,yaml]
78+
----
79+
include::{docs-java}/sample/gettingstarted/application.yml[]
80+
----
81+
82+
TIP: Beyond the Getting Started experience, most users will want to customize the default configuration. The xref:getting-started.adoc#defining-required-components[next section] demonstrates providing all of the necessary beans yourself.
83+
84+
[[defining-required-components]]
85+
== Defining Required Components
86+
87+
If you want to customize the default configuration (regardless of whether you're using Spring Boot), you can define the minimum required components as a `@Bean` in a Spring `@Configuration`.
88+
89+
These components can be defined as follows:
90+
91+
[[sample.gettingstarted]]
92+
.SecurityConfig.java
93+
[source,java]
94+
----
95+
include::{docs-java}/sample/gettingstarted/SecurityConfig.java[]
96+
----
97+
98+
This is a minimal configuration for getting started quickly. To understand what each component is used for, see the following descriptions:
99+
100+
<1> A Spring Security filter chain for the xref:protocol-endpoints.adoc[Protocol Endpoints].
101+
<2> A Spring Security filter chain for https://docs.spring.io/spring-security/reference/servlet/authentication/index.html[authentication].
102+
<3> An instance of {spring-security-api-base-url}/org/springframework/security/core/userdetails/UserDetailsService.html[`UserDetailsService`] for retrieving users to authenticate.
103+
<4> An instance of xref:core-model-components.adoc#registered-client-repository[`RegisteredClientRepository`] for managing clients.
104+
<5> An instance of `com.nimbusds.jose.jwk.source.JWKSource` for signing access tokens.
105+
<6> An instance of `java.security.KeyPair` with keys generated on startup used to create the `JWKSource` above.
106+
<7> An instance of {spring-security-api-base-url}/org/springframework/security/oauth2/jwt/JwtDecoder.html[`JwtDecoder`] for decoding signed access tokens.
107+
<8> An instance of xref:configuration-model#configuring-authorization-server-settings[`AuthorizationServerSettings`] to configure Spring Authorization Server.

‎docs/modules/ROOT/pages/servlet/oauth2/authorization-server/index.adoc‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
:noheader:
2+
[[top]]
3+
= Spring Authorization Server Reference
4+
5+
[horizontal]
6+
xref:overview.adoc[Overview] :: Introduction, use cases and feature list
7+
xref:getting-help.adoc[Getting Help] :: Links to samples, questions and issues
8+
xref:getting-started.adoc[Getting Started] :: System requirements, dependencies and developing your first application
9+
xref:configuration-model.adoc[Configuration Model] :: Default configuration and customizing the configuration
10+
xref:core-model-components.adoc[Core Model / Components] :: Core domain model and component interfaces
11+
xref:protocol-endpoints.adoc[Protocol Endpoints] :: OAuth2 and OpenID Connect 1.0 protocol endpoint implementations
12+
xref:how-to.adoc[How-to Guides] :: Guides to get the most from Spring Authorization Server
13+
14+
Joe Grandja, Steve Riesenberg
15+
16+
Copyright © 2020 - 2024
17+
18+
Copies of this document may be made for your own use and for distribution to others, provided that you do not charge any fee for such copies and further provided that each copy contains this Copyright Notice, whether distributed in print or electronically.

‎docs/modules/ROOT/pages/servlet/oauth2/authorization-server/overview.adoc‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
[[overview]]
2+
= Overview
3+
4+
This site contains reference documentation and how-to guides for Spring Authorization Server.
5+
6+
[[introducing-spring-authorization-server]]
7+
== Introducing Spring Authorization Server
8+
9+
Spring Authorization Server is a framework that provides implementations of the https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-07[OAuth 2.1] and https://openid.net/specs/openid-connect-core-1_0.html[OpenID Connect 1.0] specifications and other related specifications.
10+
It is built on top of https://spring.io/projects/spring-security[Spring Security] to provide a secure, light-weight, and customizable foundation for building OpenID Connect 1.0 Identity Providers and OAuth2 Authorization Server products.
11+
12+
[[use-cases]]
13+
== Use Cases
14+
15+
The following list provides some use cases for using Spring Authorization Server compared to using an open source or commercial OAuth2 or OpenID Connect 1.0 Provider product.
16+
17+
* Provides full control of configuration and customization when advanced customization scenarios are required.
18+
* Preference for a light-weight authorization server compared to a commercial product that includes all the "bells and whistles".
19+
* Potential savings in software licensing and/or hosting costs.
20+
* Quick startup and ease of use during development using the familiar Spring programming model.
21+
22+
[[feature-list]]
23+
== Feature List
24+
25+
Spring Authorization Server supports the following features:
26+
27+
[cols="2a,4a,6a"]
28+
|===
29+
|Category |Feature |Related specifications
30+
31+
|xref:protocol-endpoints.adoc#oauth2-token-endpoint[Authorization Grant]
32+
|
33+
* Authorization Code
34+
** xref:protocol-endpoints.adoc#oauth2-authorization-endpoint[User Consent]
35+
* Client Credentials
36+
* Refresh Token
37+
* Device Code
38+
** xref:protocol-endpoints.adoc#oauth2-device-verification-endpoint[User Consent]
39+
* Token Exchange
40+
|
41+
* The OAuth 2.1 Authorization Framework (https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-07[draft])
42+
** https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-07#section-4.1[Authorization Code Grant]
43+
** https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-07#section-4.2[Client Credentials Grant]
44+
** https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-07#section-4.3[Refresh Token Grant]
45+
* OpenID Connect Core 1.0 (https://openid.net/specs/openid-connect-core-1_0.html[spec])
46+
** https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth[Authorization Code Flow]
47+
* OAuth 2.0 Device Authorization Grant
48+
(https://tools.ietf.org/html/rfc8628[spec])
49+
** https://tools.ietf.org/html/rfc8628#section-3[Device Flow]
50+
* OAuth 2.0 Token Exchange (https://datatracker.ietf.org/doc/html/rfc8693[spec])
51+
** https://datatracker.ietf.org/doc/html/rfc8693#section-2[Token Exchange Flow]
52+
53+
|xref:core-model-components.adoc#oauth2-token-generator[Token Formats]
54+
|
55+
* Self-contained (JWT)
56+
* Reference (Opaque)
57+
|
58+
* JSON Web Token (JWT) (https://tools.ietf.org/html/rfc7519[RFC 7519])
59+
* JSON Web Signature (JWS) (https://tools.ietf.org/html/rfc7515[RFC 7515])
60+
61+
|Token Types
62+
|
63+
* xref:protocol-endpoints.adoc#oauth2-token-endpoint-dpop-bound-access-tokens[DPoP-bound Access Tokens]
64+
|
65+
* OAuth 2.0 Demonstrating Proof of Possession (DPoP) (https://datatracker.ietf.org/doc/html/rfc9449[RFC 9449])
66+
67+
|xref:configuration-model.adoc#configuring-client-authentication[Client Authentication]
68+
|
69+
* `client_secret_basic`
70+
* `client_secret_post`
71+
* `client_secret_jwt`
72+
* `private_key_jwt`
73+
* `tls_client_auth`
74+
* `self_signed_tls_client_auth`
75+
* `none` (public clients)
76+
|
77+
* The OAuth 2.1 Authorization Framework (https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-07#section-2.4[Client Authentication])
78+
* JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication (https://tools.ietf.org/html/rfc7523[RFC 7523])
79+
* OAuth 2.0 Mutual-TLS Client Authentication and Certificate-Bound Access Tokens (https://datatracker.ietf.org/doc/html/rfc8705[RFC 8705])
80+
* Proof Key for Code Exchange by OAuth Public Clients (PKCE) (https://tools.ietf.org/html/rfc7636[RFC 7636])
81+
82+
|xref:protocol-endpoints.adoc[Protocol Endpoints]
83+
|
84+
* xref:protocol-endpoints.adoc#oauth2-authorization-endpoint[OAuth2 Authorization Endpoint]
85+
* xref:protocol-endpoints.adoc#oauth2-pushed-authorization-request-endpoint[OAuth2 Pushed Authorization Request Endpoint]
86+
* xref:protocol-endpoints.adoc#oauth2-device-authorization-endpoint[OAuth2 Device Authorization Endpoint]
87+
* xref:protocol-endpoints.adoc#oauth2-device-verification-endpoint[OAuth2 Device Verification Endpoint]
88+
* xref:protocol-endpoints.adoc#oauth2-token-endpoint[OAuth2 Token Endpoint]
89+
* xref:protocol-endpoints.adoc#oauth2-token-introspection-endpoint[OAuth2 Token Introspection Endpoint]
90+
* xref:protocol-endpoints.adoc#oauth2-token-revocation-endpoint[OAuth2 Token Revocation Endpoint]
91+
* xref:protocol-endpoints.adoc#oauth2-authorization-server-metadata-endpoint[OAuth2 Authorization Server Metadata Endpoint]
92+
* xref:protocol-endpoints.adoc#jwk-set-endpoint[JWK Set Endpoint]
93+
* xref:protocol-endpoints.adoc#oidc-provider-configuration-endpoint[OpenID Connect 1.0 Provider Configuration Endpoint]
94+
* xref:protocol-endpoints.adoc#oidc-logout-endpoint[OpenID Connect 1.0 Logout Endpoint]
95+
* xref:protocol-endpoints.adoc#oidc-user-info-endpoint[OpenID Connect 1.0 UserInfo Endpoint]
96+
* xref:protocol-endpoints.adoc#oidc-client-registration-endpoint[OpenID Connect 1.0 Client Registration Endpoint]
97+
|
98+
* The OAuth 2.1 Authorization Framework (https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-07[draft])
99+
** https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-07#section-3.1[Authorization Endpoint]
100+
** https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-07#section-3.2[Token Endpoint]
101+
* OAuth 2.0 Pushed Authorization Requests (https://datatracker.ietf.org/doc/html/rfc9126[RFC 9126])
102+
** https://datatracker.ietf.org/doc/html/rfc9126#section-2[Pushed Authorization Request Endpoint]
103+
* OAuth 2.0 Device Authorization Grant (https://tools.ietf.org/html/rfc8628[RFC 8628])
104+
** https://tools.ietf.org/html/rfc8628#section-3.1[Device Authorization Endpoint]
105+
** https://tools.ietf.org/html/rfc8628#section-3.3[Device Verification Endpoint]
106+
* OAuth 2.0 Token Introspection (https://tools.ietf.org/html/rfc7662[RFC 7662])
107+
* OAuth 2.0 Token Revocation (https://tools.ietf.org/html/rfc7009[RFC 7009])
108+
* OAuth 2.0 Authorization Server Metadata (https://tools.ietf.org/html/rfc8414[RFC 8414])
109+
* JSON Web Key (JWK) (https://tools.ietf.org/html/rfc7517[RFC 7517])
110+
* OpenID Connect Discovery 1.0 (https://openid.net/specs/openid-connect-discovery-1_0.html[spec])
111+
** https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfig[Provider Configuration Endpoint]
112+
* OpenID Connect RP-Initiated Logout 1.0 (https://openid.net/specs/openid-connect-rpinitiated-1_0.html[spec])
113+
** https://openid.net/specs/openid-connect-rpinitiated-1_0.html#RPLogout[Logout Endpoint]
114+
* OpenID Connect Core 1.0 (https://openid.net/specs/openid-connect-core-1_0.html[spec])
115+
** https://openid.net/specs/openid-connect-core-1_0.html#UserInfo[UserInfo Endpoint]
116+
* OpenID Connect Dynamic Client Registration 1.0 (https://openid.net/specs/openid-connect-registration-1_0.html[spec])
117+
** https://openid.net/specs/openid-connect-registration-1_0.html#ClientRegistration[Client Registration Endpoint]
118+
** https://openid.net/specs/openid-connect-registration-1_0.html#ClientConfigurationEndpoint[Client Configuration Endpoint]
119+
|===

0 commit comments

Comments
 (0)