From 7b70811f62c64060cb029c9e9d51d3b955fdda37 Mon Sep 17 00:00:00 2001 From: Rob Winch Date: Mon, 3 Jul 2023 13:36:26 -0500 Subject: [PATCH 01/12] Migrate Structure --- docs/{src/docs/asciidoc => modules/ROOT/pages}/attributes.adoc | 0 .../docs/asciidoc => modules/ROOT/pages}/configuration-model.adoc | 0 .../asciidoc => modules/ROOT/pages}/core-model-components.adoc | 0 docs/{src/docs/asciidoc => modules/ROOT/pages}/getting-help.adoc | 0 .../docs/asciidoc => modules/ROOT/pages}/getting-started.adoc | 0 .../docs/asciidoc => modules/ROOT/pages}/guides/attributes.adoc | 0 .../ROOT/pages}/guides/how-to-ext-grant-type.adoc | 0 .../docs/asciidoc => modules/ROOT/pages}/guides/how-to-jpa.adoc | 0 .../docs/asciidoc => modules/ROOT/pages}/guides/how-to-pkce.adoc | 0 .../ROOT/pages}/guides/how-to-social-login.adoc | 0 .../asciidoc => modules/ROOT/pages}/guides/how-to-userinfo.adoc | 0 docs/{src/docs/asciidoc => modules/ROOT/pages}/how-to.adoc | 0 docs/{src/docs/asciidoc => modules/ROOT/pages}/index.adoc | 0 docs/{src/docs/asciidoc => modules/ROOT/pages}/overview.adoc | 0 .../docs/asciidoc => modules/ROOT/pages}/protocol-endpoints.adoc | 0 15 files changed, 0 insertions(+), 0 deletions(-) rename docs/{src/docs/asciidoc => modules/ROOT/pages}/attributes.adoc (100%) rename docs/{src/docs/asciidoc => modules/ROOT/pages}/configuration-model.adoc (100%) rename docs/{src/docs/asciidoc => modules/ROOT/pages}/core-model-components.adoc (100%) rename docs/{src/docs/asciidoc => modules/ROOT/pages}/getting-help.adoc (100%) rename docs/{src/docs/asciidoc => modules/ROOT/pages}/getting-started.adoc (100%) rename docs/{src/docs/asciidoc => modules/ROOT/pages}/guides/attributes.adoc (100%) rename docs/{src/docs/asciidoc => modules/ROOT/pages}/guides/how-to-ext-grant-type.adoc (100%) rename docs/{src/docs/asciidoc => modules/ROOT/pages}/guides/how-to-jpa.adoc (100%) rename docs/{src/docs/asciidoc => modules/ROOT/pages}/guides/how-to-pkce.adoc (100%) rename docs/{src/docs/asciidoc => modules/ROOT/pages}/guides/how-to-social-login.adoc (100%) rename docs/{src/docs/asciidoc => modules/ROOT/pages}/guides/how-to-userinfo.adoc (100%) rename docs/{src/docs/asciidoc => modules/ROOT/pages}/how-to.adoc (100%) rename docs/{src/docs/asciidoc => modules/ROOT/pages}/index.adoc (100%) rename docs/{src/docs/asciidoc => modules/ROOT/pages}/overview.adoc (100%) rename docs/{src/docs/asciidoc => modules/ROOT/pages}/protocol-endpoints.adoc (100%) diff --git a/docs/src/docs/asciidoc/attributes.adoc b/docs/modules/ROOT/pages/attributes.adoc similarity index 100% rename from docs/src/docs/asciidoc/attributes.adoc rename to docs/modules/ROOT/pages/attributes.adoc diff --git a/docs/src/docs/asciidoc/configuration-model.adoc b/docs/modules/ROOT/pages/configuration-model.adoc similarity index 100% rename from docs/src/docs/asciidoc/configuration-model.adoc rename to docs/modules/ROOT/pages/configuration-model.adoc diff --git a/docs/src/docs/asciidoc/core-model-components.adoc b/docs/modules/ROOT/pages/core-model-components.adoc similarity index 100% rename from docs/src/docs/asciidoc/core-model-components.adoc rename to docs/modules/ROOT/pages/core-model-components.adoc diff --git a/docs/src/docs/asciidoc/getting-help.adoc b/docs/modules/ROOT/pages/getting-help.adoc similarity index 100% rename from docs/src/docs/asciidoc/getting-help.adoc rename to docs/modules/ROOT/pages/getting-help.adoc diff --git a/docs/src/docs/asciidoc/getting-started.adoc b/docs/modules/ROOT/pages/getting-started.adoc similarity index 100% rename from docs/src/docs/asciidoc/getting-started.adoc rename to docs/modules/ROOT/pages/getting-started.adoc diff --git a/docs/src/docs/asciidoc/guides/attributes.adoc b/docs/modules/ROOT/pages/guides/attributes.adoc similarity index 100% rename from docs/src/docs/asciidoc/guides/attributes.adoc rename to docs/modules/ROOT/pages/guides/attributes.adoc diff --git a/docs/src/docs/asciidoc/guides/how-to-ext-grant-type.adoc b/docs/modules/ROOT/pages/guides/how-to-ext-grant-type.adoc similarity index 100% rename from docs/src/docs/asciidoc/guides/how-to-ext-grant-type.adoc rename to docs/modules/ROOT/pages/guides/how-to-ext-grant-type.adoc diff --git a/docs/src/docs/asciidoc/guides/how-to-jpa.adoc b/docs/modules/ROOT/pages/guides/how-to-jpa.adoc similarity index 100% rename from docs/src/docs/asciidoc/guides/how-to-jpa.adoc rename to docs/modules/ROOT/pages/guides/how-to-jpa.adoc diff --git a/docs/src/docs/asciidoc/guides/how-to-pkce.adoc b/docs/modules/ROOT/pages/guides/how-to-pkce.adoc similarity index 100% rename from docs/src/docs/asciidoc/guides/how-to-pkce.adoc rename to docs/modules/ROOT/pages/guides/how-to-pkce.adoc diff --git a/docs/src/docs/asciidoc/guides/how-to-social-login.adoc b/docs/modules/ROOT/pages/guides/how-to-social-login.adoc similarity index 100% rename from docs/src/docs/asciidoc/guides/how-to-social-login.adoc rename to docs/modules/ROOT/pages/guides/how-to-social-login.adoc diff --git a/docs/src/docs/asciidoc/guides/how-to-userinfo.adoc b/docs/modules/ROOT/pages/guides/how-to-userinfo.adoc similarity index 100% rename from docs/src/docs/asciidoc/guides/how-to-userinfo.adoc rename to docs/modules/ROOT/pages/guides/how-to-userinfo.adoc diff --git a/docs/src/docs/asciidoc/how-to.adoc b/docs/modules/ROOT/pages/how-to.adoc similarity index 100% rename from docs/src/docs/asciidoc/how-to.adoc rename to docs/modules/ROOT/pages/how-to.adoc diff --git a/docs/src/docs/asciidoc/index.adoc b/docs/modules/ROOT/pages/index.adoc similarity index 100% rename from docs/src/docs/asciidoc/index.adoc rename to docs/modules/ROOT/pages/index.adoc diff --git a/docs/src/docs/asciidoc/overview.adoc b/docs/modules/ROOT/pages/overview.adoc similarity index 100% rename from docs/src/docs/asciidoc/overview.adoc rename to docs/modules/ROOT/pages/overview.adoc diff --git a/docs/src/docs/asciidoc/protocol-endpoints.adoc b/docs/modules/ROOT/pages/protocol-endpoints.adoc similarity index 100% rename from docs/src/docs/asciidoc/protocol-endpoints.adoc rename to docs/modules/ROOT/pages/protocol-endpoints.adoc From 10dfc831d3a4ae1d3c51df94add7333970029640 Mon Sep 17 00:00:00 2001 From: Rob Winch Date: Mon, 3 Jul 2023 13:36:26 -0500 Subject: [PATCH 02/12] Copy default antora files --- docs/.github/workflows/deploy-docs.yml | 33 ++++ docs/antora-playbook.yml | 36 ++++ docs/antora.yml | 32 ++++ docs/framework-docs.gradle | 218 +++++++++++++++++++++++++ 4 files changed, 319 insertions(+) create mode 100644 docs/.github/workflows/deploy-docs.yml create mode 100644 docs/antora-playbook.yml create mode 100644 docs/antora.yml create mode 100644 docs/framework-docs.gradle diff --git a/docs/.github/workflows/deploy-docs.yml b/docs/.github/workflows/deploy-docs.yml new file mode 100644 index 000000000..1435fc217 --- /dev/null +++ b/docs/.github/workflows/deploy-docs.yml @@ -0,0 +1,33 @@ +name: Deploy Docs +on: + push: + branches-ignore: [ gh-pages ] + tags: '**' + repository_dispatch: + types: request-build-reference # legacy + #schedule: + #- cron: '0 10 * * *' # Once per day at 10am UTC + workflow_dispatch: +permissions: + actions: write +jobs: + build: + runs-on: ubuntu-latest + # FIXME enable when pushed to spring-projects + # if: github.repository_owner == 'spring-projects' + steps: + - name: Checkout + uses: actions/checkout@v3 + with: + ref: docs-build + fetch-depth: 1 + - name: Dispatch (partial build) + if: github.ref_type == 'branch' + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: gh workflow run deploy-docs.yml -r $(git rev-parse --abbrev-ref HEAD) -f build-refname=${{ github.ref_name }} + - name: Dispatch (full build) + if: github.ref_type == 'tag' + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: gh workflow run deploy-docs.yml -r $(git rev-parse --abbrev-ref HEAD) diff --git a/docs/antora-playbook.yml b/docs/antora-playbook.yml new file mode 100644 index 000000000..ffae717c2 --- /dev/null +++ b/docs/antora-playbook.yml @@ -0,0 +1,36 @@ +# PACKAGES antora@3.2.0-alpha.2 @antora/atlas-extension:1.0.0-alpha.1 @antora/collector-extension@1.0.0-alpha.3 @springio/antora-extensions@1.1.0-alpha.2 @asciidoctor/tabs@1.0.0-alpha.12 @opendevise/antora-release-line-extension@1.0.0-alpha.2 +# +# The purpose of this Antora playbook is to build the docs in the current branch. +antora: + extensions: + - '@antora/collector-extension' + - require: '@springio/antora-extensions/tabs-migration-extension' + unwrap_example_block: always +site: + title: Spring Framework Reference + url: https://https://rwinch.github.io/spring-framework/ +content: + sources: + - url: https://github.com/rwinch/spring-framework + branches: ./.. + start_path: framework-docs + worktrees: true +asciidoc: + attributes: + page-pagination: '' + hide-uri-scheme: '@' + tabs-sync-option: '@' + chomp: 'all' + extensions: + - '@asciidoctor/tabs' + - '@springio/asciidoctor-extensions' + sourcemap: true +urls: + latest_version_segment: '' +runtime: + log: + failure_level: warn +ui: + bundle: + url: https://github.com/spring-io/antora-ui-spring/releases/download/latest/ui-bundle.zip + snapshot: true \ No newline at end of file diff --git a/docs/antora.yml b/docs/antora.yml new file mode 100644 index 000000000..cc7d6eb16 --- /dev/null +++ b/docs/antora.yml @@ -0,0 +1,32 @@ +name: framework +version: true +title: Spring Framework Documentation +nav: + - modules/ROOT/nav.adoc +ext: + collector: + run: + command: gradlew -q -PbuildSrc.skipTests=true "-Dorg.gradle.jvmargs=-Xmx3g -XX:+HeapDumpOnOutOfMemoryError" :spring-boot-project:spring-boot-docs:generateAntoraResources + local: true + scan: + dir: ./build/generated-antora-resources + +asciidoc: + attributes: + attribute-missing: 'warn' + # FIXME: the copyright is not removed + # FIXME: The package is not renamed + chomp: 'all' + import-java: 'example$docs-src/main/java/org/springframework/docs' + spring-framework-main-code: 'https://github.com/spring-projects/spring-framework/tree/main' + docs-site: 'https://docs.spring.io' + docs-spring: "{docs-site}/spring-framework/docs/{spring-version}" + docs-spring-framework: '{docs_site}/spring-framework/docs/{spring-version}' + api-spring-framework: '{docs-spring-framework}/javadoc-api/org/springframework' + docs-graalvm: 'https://www.graalvm.org/22.3/reference-manual' + docs-spring-boot: '{docs-site}/spring-boot/docs/current/reference' + docs-spring-gemfire: '{docs_site}/spring-gemfire/docs/current/reference' + docs-spring-security: '{docs_site}/spring-security/reference' + gh-rsocket: 'https://github.com/rsocket' + gh-rsocket-extensions: '{gh-rsocket}/rsocket/blob/master/Extensions' + gh-rsocket-java: '{gh-rsocket}/rsocket-java{gh-rsocket}/rsocket-java' \ No newline at end of file diff --git a/docs/framework-docs.gradle b/docs/framework-docs.gradle new file mode 100644 index 000000000..5c26a91b4 --- /dev/null +++ b/docs/framework-docs.gradle @@ -0,0 +1,218 @@ +plugins { + id 'kotlin' + id 'io.spring.antora.generate-antora-yml' version '0.0.1' + id 'org.antora' version '1.0.0' +} + +description = "Spring Framework Docs" + +apply from: "${rootDir}/gradle/publications.gradle" + + +antora { + version = '3.2.0-alpha.2' + playbook = 'antora-playbook.yml' +// playbookProvider { +// repository = 'rwinch/spring-framework' +// branch = 'docs-build' +// path = 'lib/antora/templates/per-branch-antora-playbook.yml' +// checkLocalBranch = true +// } + options = ['--clean', '--stacktrace'] + environment = [ + 'ALGOLIA_API_KEY': '82c7ead946afbac3cf98c32446154691', + 'ALGOLIA_APP_ID': '244V8V9FGG', + 'ALGOLIA_INDEX_NAME': 'framework-docs' + ] + dependencies = [ + '@antora/atlas-extension': '1.0.0-alpha.1', + '@antora/collector-extension': '1.0.0-alpha.3', + '@asciidoctor/tabs': '1.0.0-beta.3', + '@opendevise/antora-release-line-extension': '1.0.0-alpha.2', + '@springio/antora-extensions': '1.1.0', + '@springio/asciidoctor-extensions': '1.0.0-alpha.9' + ] +} + + +tasks.named("generateAntoraYml") { + dependsOn dependencyVersions + asciidocAttributes = project.provider( { + return ["spring-version": project.version ] + } ) +} + + +jar { + enabled = false +} + +javadoc { + enabled = false +} + +repositories { + maven { + url "https://repo.spring.io/release" + } +} + +/** + * Produce Javadoc for all Spring Framework modules in "build/docs/javadoc" + */ +task api(type: Javadoc) { + group = "Documentation" + description = "Generates aggregated Javadoc API documentation." + title = "${rootProject.description} ${version} API" + + dependsOn { + moduleProjects.collect { + it.tasks.getByName("jar") + } + } + doFirst { + classpath = files( + // ensure the javadoc process can resolve types compiled from .aj sources + project(":spring-aspects").sourceSets.main.output + ) + classpath += files(moduleProjects.collect { it.sourceSets.main.compileClasspath }) + } + + options { + encoding = "UTF-8" + memberLevel = JavadocMemberLevel.PROTECTED + author = true + header = rootProject.description + use = true + overview = "framework-docs/src/docs/api/overview.html" + splitIndex = true + links(project.ext.javadocLinks) + addBooleanOption('Xdoclint:syntax', true) // only check syntax with doclint + addBooleanOption('Werror', true) // fail build on Javadoc warnings + } + source moduleProjects.collect { project -> + project.sourceSets.main.allJava + } + maxMemory = "1024m" + destinationDir = file("$buildDir/docs/javadoc") +} + +/** + * Produce KDoc for all Spring Framework modules in "build/docs/kdoc" + */ +rootProject.tasks.dokkaHtmlMultiModule.configure { + dependsOn { + tasks.getByName("api") + } + moduleName.set("spring-framework") + outputDirectory.set(project.file("$buildDir/docs/kdoc")) +} + +/** + * Zip all docs (API and reference) into a single archive + */ +task docsZip(type: Zip, dependsOn: ['api', 'antora', rootProject.tasks.dokkaHtmlMultiModule]) { + group = "Distribution" + description = "Builds -${archiveClassifier} archive containing api and reference " + + "for deployment at https://docs.spring.io/spring-framework/docs/." + + archiveBaseName.set("spring-framework") + archiveClassifier.set("docs") + from("src/dist") { + include "changelog.txt" + } + from (api) { + into "javadoc-api" + } + from ("build/site") { + into "reference/html" + } + from (rootProject.tasks.dokkaHtmlMultiModule.outputDirectory) { + into "kdoc-api" + } +} + +/** + * Zip all Spring Framework schemas into a single archive + */ +task schemaZip(type: Zip) { + group = "Distribution" + archiveBaseName.set("spring-framework") + archiveClassifier.set("schema") + description = "Builds -${archiveClassifier} archive containing all " + + "XSDs for deployment at https://springframework.org/schema." + duplicatesStrategy DuplicatesStrategy.EXCLUDE + moduleProjects.each { module -> + def Properties schemas = new Properties(); + + module.sourceSets.main.resources.find { + (it.path.endsWith("META-INF/spring.schemas") || it.path.endsWith("META-INF\\spring.schemas")) + }?.withInputStream { schemas.load(it) } + + for (def key : schemas.keySet()) { + def shortName = key.replaceAll(/http.*schema.(.*).spring-.*/, '$1') + assert shortName != key + File xsdFile = module.sourceSets.main.resources.find { + (it.path.endsWith(schemas.get(key)) || it.path.endsWith(schemas.get(key).replaceAll('\\/','\\\\'))) + } + assert xsdFile != null + into (shortName) { + from xsdFile.path + } + } + } +} + +/** + * Create a distribution zip with everything: + * docs, schemas, jars, source jars, javadoc jars + */ +task distZip(type: Zip, dependsOn: [docsZip, schemaZip]) { + group = "Distribution" + archiveBaseName.set("spring-framework") + archiveClassifier.set("dist") + description = "Builds -${archiveClassifier} archive, containing all jars and docs, " + + "suitable for community download page." + + ext.baseDir = "spring-framework-${project.version}"; + + from("src/docs/dist") { + include "readme.txt" + include "license.txt" + include "notice.txt" + into "${baseDir}" + expand(copyright: new Date().format("yyyy"), version: project.version) + } + + from(zipTree(docsZip.archiveFile)) { + into "${baseDir}/docs" + } + + from(zipTree(schemaZip.archiveFile)) { + into "${baseDir}/schema" + } + + moduleProjects.each { module -> + into ("${baseDir}/libs") { + from module.jar + if (module.tasks.findByPath("sourcesJar")) { + from module.sourcesJar + } + if (module.tasks.findByPath("javadocJar")) { + from module.javadocJar + } + } + } +} + +distZip.mustRunAfter moduleProjects.check + +publishing { + publications { + mavenJava(MavenPublication) { + artifact docsZip + artifact schemaZip + artifact distZip + } + } +} \ No newline at end of file From 690696fdb9cb54d384cb2c1b35ec524b1ef1a697 Mon Sep 17 00:00:00 2001 From: Rob Winch Date: Mon, 3 Jul 2023 13:36:26 -0500 Subject: [PATCH 03/12] Generate a default navigation --- docs/modules/ROOT/nav.adoc | 15 +++++++++++++++ 1 file changed, 15 insertions(+) create mode 100644 docs/modules/ROOT/nav.adoc diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc new file mode 100644 index 000000000..fc67e965b --- /dev/null +++ b/docs/modules/ROOT/nav.adoc @@ -0,0 +1,15 @@ +* xref:index.adoc[] +* xref:overview.adoc[] +* xref:getting-help.adoc[] +* xref:getting-started.adoc[] +* xref:attributes.adoc[] +* xref:configuration-model.adoc[] +* xref:core-model-components.adoc[] +* xref:protocol-endpoints.adoc[] +* xref:how-to.adoc[] +** xref:guides/attributes.adoc[] +** xref:guides/how-to-ext-grant-type.adoc[] +** xref:guides/how-to-jpa.adoc[] +** xref:guides/how-to-pkce.adoc[] +** xref:guides/how-to-social-login.adoc[] +** xref:guides/how-to-userinfo.adoc[] From b8d87c21fe5561460b92daebfbb19cbe17fe4e98 Mon Sep 17 00:00:00 2001 From: Rob Winch Date: Mon, 3 Jul 2023 13:36:26 -0500 Subject: [PATCH 04/12] Remove includes --- docs/modules/ROOT/pages/getting-started.adoc | 1 - docs/modules/ROOT/pages/guides/how-to-ext-grant-type.adoc | 1 - docs/modules/ROOT/pages/guides/how-to-jpa.adoc | 1 - docs/modules/ROOT/pages/guides/how-to-pkce.adoc | 1 - docs/modules/ROOT/pages/guides/how-to-social-login.adoc | 1 - docs/modules/ROOT/pages/guides/how-to-userinfo.adoc | 1 - docs/modules/ROOT/pages/how-to.adoc | 1 - 7 files changed, 7 deletions(-) diff --git a/docs/modules/ROOT/pages/getting-started.adoc b/docs/modules/ROOT/pages/getting-started.adoc index cb6103c71..e9ed718f9 100644 --- a/docs/modules/ROOT/pages/getting-started.adoc +++ b/docs/modules/ROOT/pages/getting-started.adoc @@ -1,4 +1,3 @@ -include::attributes.adoc[] [[getting-started]] = Getting Started diff --git a/docs/modules/ROOT/pages/guides/how-to-ext-grant-type.adoc b/docs/modules/ROOT/pages/guides/how-to-ext-grant-type.adoc index 5b0d2d8b9..d1957db3a 100644 --- a/docs/modules/ROOT/pages/guides/how-to-ext-grant-type.adoc +++ b/docs/modules/ROOT/pages/guides/how-to-ext-grant-type.adoc @@ -1,4 +1,3 @@ -include::attributes.adoc[] [[how-to-extension-grant-type]] = How-to: Implement an Extension Authorization Grant Type diff --git a/docs/modules/ROOT/pages/guides/how-to-jpa.adoc b/docs/modules/ROOT/pages/guides/how-to-jpa.adoc index 3e99478e9..276ec79a8 100644 --- a/docs/modules/ROOT/pages/guides/how-to-jpa.adoc +++ b/docs/modules/ROOT/pages/guides/how-to-jpa.adoc @@ -1,4 +1,3 @@ -include::attributes.adoc[] [[how-to-jpa]] = How-to: Implement core services with JPA diff --git a/docs/modules/ROOT/pages/guides/how-to-pkce.adoc b/docs/modules/ROOT/pages/guides/how-to-pkce.adoc index 4fd497deb..8bf800214 100644 --- a/docs/modules/ROOT/pages/guides/how-to-pkce.adoc +++ b/docs/modules/ROOT/pages/guides/how-to-pkce.adoc @@ -1,4 +1,3 @@ -include::attributes.adoc[] [[how-to-pkce]] = How-to: Authenticate using a Single Page Application with PKCE diff --git a/docs/modules/ROOT/pages/guides/how-to-social-login.adoc b/docs/modules/ROOT/pages/guides/how-to-social-login.adoc index 8ccf25a01..47a054224 100644 --- a/docs/modules/ROOT/pages/guides/how-to-social-login.adoc +++ b/docs/modules/ROOT/pages/guides/how-to-social-login.adoc @@ -1,4 +1,3 @@ -include::attributes.adoc[] [[how-to-social-login]] = How-to: Authenticate using Social Login diff --git a/docs/modules/ROOT/pages/guides/how-to-userinfo.adoc b/docs/modules/ROOT/pages/guides/how-to-userinfo.adoc index 1b6f78318..e91e4fe84 100644 --- a/docs/modules/ROOT/pages/guides/how-to-userinfo.adoc +++ b/docs/modules/ROOT/pages/guides/how-to-userinfo.adoc @@ -1,4 +1,3 @@ -include::attributes.adoc[] [[how-to-userinfo]] = How-to: Customize the OpenID Connect 1.0 UserInfo response diff --git a/docs/modules/ROOT/pages/how-to.adoc b/docs/modules/ROOT/pages/how-to.adoc index 8eab80287..5a67c36c3 100644 --- a/docs/modules/ROOT/pages/how-to.adoc +++ b/docs/modules/ROOT/pages/how-to.adoc @@ -1,4 +1,3 @@ -include::attributes.adoc[] [[how-to]] = How-to Guides From 51f6c79d52c002e6a798af9b4ca7530c75c3f598 Mon Sep 17 00:00:00 2001 From: Rob Winch Date: Mon, 3 Jul 2023 13:36:26 -0500 Subject: [PATCH 05/12] Fix cross references --- .../ROOT/pages/configuration-model.adoc | 8 +-- .../ROOT/pages/core-model-components.adoc | 26 ++++---- docs/modules/ROOT/pages/getting-started.adoc | 2 +- .../pages/guides/how-to-ext-grant-type.adoc | 20 +++---- .../modules/ROOT/pages/guides/how-to-jpa.adoc | 60 +++++++++---------- .../ROOT/pages/guides/how-to-pkce.adoc | 16 ++--- .../pages/guides/how-to-social-login.adoc | 26 ++++---- .../ROOT/pages/guides/how-to-userinfo.adoc | 22 +++---- .../ROOT/pages/protocol-endpoints.adoc | 2 +- 9 files changed, 91 insertions(+), 91 deletions(-) diff --git a/docs/modules/ROOT/pages/configuration-model.adoc b/docs/modules/ROOT/pages/configuration-model.adoc index 1afa75d28..84515780a 100644 --- a/docs/modules/ROOT/pages/configuration-model.adoc +++ b/docs/modules/ROOT/pages/configuration-model.adoc @@ -6,7 +6,7 @@ `OAuth2AuthorizationServerConfiguration` is a `@Configuration` that provides the minimal default configuration for an OAuth2 authorization server. -`OAuth2AuthorizationServerConfiguration` uses <> to apply the default configuration and registers a `SecurityFilterChain` `@Bean` composed of all the infrastructure components supporting an OAuth2 authorization server. +`OAuth2AuthorizationServerConfiguration` uses xref:configuration-model.adoc#customizing-the-configuration[`OAuth2AuthorizationServerConfigurer`] to apply the default configuration and registers a `SecurityFilterChain` `@Bean` composed of all the infrastructure components supporting an OAuth2 authorization server. [TIP] `OAuth2AuthorizationServerConfiguration.applyDefaultSecurity(HttpSecurity)` is a convenience (`static`) utility method that applies the default OAuth2 security configuration to `HttpSecurity`. @@ -135,9 +135,9 @@ public SecurityFilterChain authorizationServerSecurityFilterChain(HttpSecurity h <1> `registeredClientRepository()`: The xref:core-model-components.adoc#registered-client-repository[`RegisteredClientRepository`] (*REQUIRED*) for managing new and existing clients. <2> `authorizationService()`: The xref:core-model-components.adoc#oauth2-authorization-service[`OAuth2AuthorizationService`] for managing new and existing authorizations. <3> `authorizationConsentService()`: The xref:core-model-components.adoc#oauth2-authorization-consent-service[`OAuth2AuthorizationConsentService`] for managing new and existing authorization consents. -<4> `authorizationServerSettings()`: The <> (*REQUIRED*) for customizing configuration settings for the OAuth2 authorization server. +<4> `authorizationServerSettings()`: The xref:configuration-model.adoc#configuring-authorization-server-settings[`AuthorizationServerSettings`] (*REQUIRED*) for customizing configuration settings for the OAuth2 authorization server. <5> `tokenGenerator()`: The xref:core-model-components.adoc#oauth2-token-generator[`OAuth2TokenGenerator`] for generating tokens supported by the OAuth2 authorization server. -<6> `clientAuthentication()`: The configurer for <>. +<6> `clientAuthentication()`: The configurer for xref:configuration-model.adoc#configuring-client-authentication[OAuth2 Client Authentication]. <7> `authorizationEndpoint()`: The configurer for the xref:protocol-endpoints.adoc#oauth2-authorization-endpoint[OAuth2 Authorization endpoint]. <8> `deviceAuthorizationEndpoint()`: The configurer for the xref:protocol-endpoints.adoc#oauth2-device-authorization-endpoint[OAuth2 Device Authorization endpoint]. <9> `deviceVerificationEndpoint()`: The configurer for the xref:protocol-endpoints.adoc#oauth2-device-verification-endpoint[OAuth2 Device Verification endpoint]. @@ -186,7 +186,7 @@ public final class AuthorizationServerSettings extends AbstractSettings { `AuthorizationServerSettings` is a *REQUIRED* component. [TIP] -<> automatically registers an `AuthorizationServerSettings` `@Bean`, if not already provided. +xref:configuration-model.adoc#default-configuration[`@Import(OAuth2AuthorizationServerConfiguration.class)`] automatically registers an `AuthorizationServerSettings` `@Bean`, if not already provided. The following example shows how to customize the configuration settings and register an `AuthorizationServerSettings` `@Bean`: diff --git a/docs/modules/ROOT/pages/core-model-components.adoc b/docs/modules/ROOT/pages/core-model-components.adoc index 755148e18..c1c12582c 100644 --- a/docs/modules/ROOT/pages/core-model-components.adoc +++ b/docs/modules/ROOT/pages/core-model-components.adoc @@ -141,7 +141,7 @@ The `OAuth2AuthorizationServerConfigurer` is useful when applying multiple confi [[oauth2-authorization]] == OAuth2Authorization -An `OAuth2Authorization` is a representation of an OAuth2 authorization, which holds state related to the authorization granted to a <>, by the resource owner or itself in the case of the `client_credentials` authorization grant type. +An `OAuth2Authorization` is a representation of an OAuth2 authorization, which holds state related to the authorization granted to a xref:core-model-components.adoc#registered-client[client], by the resource owner or itself in the case of the `client_credentials` authorization grant type. [TIP] The corresponding authorization model in Spring Security's OAuth2 Client support is {spring-security-reference-base-url}/servlet/oauth2/client/core.html#oauth2Client-authorized-client[OAuth2AuthorizedClient]. @@ -174,7 +174,7 @@ public class OAuth2Authorization implements Serializable { } ---- <1> `id`: The ID that uniquely identifies the `OAuth2Authorization`. -<2> `registeredClientId`: The ID that uniquely identifies the <>. +<2> `registeredClientId`: The ID that uniquely identifies the xref:core-model-components.adoc#registered-client[RegisteredClient]. <3> `principalName`: The principal name of the resource owner (or client). <4> `authorizationGrantType`: The `AuthorizationGrantType` used. <5> `authorizedScopes`: The `Set` of scope(s) authorized for the client. @@ -236,7 +236,7 @@ The `OAuth2AuthorizationServerConfigurer` is useful when applying multiple confi [[oauth2-authorization-consent]] == OAuth2AuthorizationConsent -An `OAuth2AuthorizationConsent` is a representation of an authorization "consent" (decision) from an https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.1[OAuth2 authorization request flow] – for example, the `authorization_code` grant, which holds the authorities granted to a <> by the resource owner. +An `OAuth2AuthorizationConsent` is a representation of an authorization "consent" (decision) from an https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.1[OAuth2 authorization request flow] – for example, the `authorization_code` grant, which holds the authorities granted to a xref:core-model-components.adoc#registered-client[client] by the resource owner. When authorizing access to a client, the resource owner may grant only a subset of the authorities requested by the client. The typical use case is the `authorization_code` grant flow, in which the client requests scope(s) and the resource owner grants (or denies) access to the requested scope(s). @@ -256,7 +256,7 @@ public final class OAuth2AuthorizationConsent implements Serializable { } ---- -<1> `registeredClientId`: The ID that uniquely identifies the <>. +<1> `registeredClientId`: The ID that uniquely identifies the xref:core-model-components.adoc#registered-client[RegisteredClient]. <2> `principalName`: The principal name of the resource owner. <3> `authorities`: The authorities granted to the client by the resource owner. An authority can represent a scope, a claim, a permission, a role, and others. @@ -308,7 +308,7 @@ The `OAuth2AuthorizationServerConfigurer` is useful when applying multiple confi [[oauth2-token-context]] == OAuth2TokenContext -An `OAuth2TokenContext` is a context object that holds information associated with an `OAuth2Token` and is used by an <> and <>. +An `OAuth2TokenContext` is a context object that holds information associated with an `OAuth2Token` and is used by an xref:core-model-components.adoc#oauth2-token-generator[OAuth2TokenGenerator] and xref:core-model-components.adoc#oauth2-token-customizer[OAuth2TokenCustomizer]. `OAuth2TokenContext` provides the following accessors: @@ -337,10 +337,10 @@ public interface OAuth2TokenContext extends Context { } ---- -<1> `getRegisteredClient()`: The <> associated with the authorization grant. +<1> `getRegisteredClient()`: The xref:core-model-components.adoc#registered-client[RegisteredClient] associated with the authorization grant. <2> `getPrincipal()`: The `Authentication` instance of the resource owner (or client). <3> `getAuthorizationServerContext()`: The xref:configuration-model.adoc#configuring-authorization-server-settings[`AuthorizationServerContext`] object that holds information of the Authorization Server runtime environment. -<4> `getAuthorization()`: The <> associated with the authorization grant. +<4> `getAuthorization()`: The xref:core-model-components.adoc#oauth2-authorization[OAuth2Authorization] associated with the authorization grant. <5> `getAuthorizedScopes()`: The scope(s) authorized for the client. <6> `getTokenType()`: The `OAuth2TokenType` to generate. The supported values are `code`, `access_token`, `refresh_token`, and `id_token`. <7> `getAuthorizationGrantType()`: The `AuthorizationGrantType` associated with the authorization grant. @@ -349,7 +349,7 @@ public interface OAuth2TokenContext extends Context { [[oauth2-token-generator]] == OAuth2TokenGenerator -An `OAuth2TokenGenerator` is responsible for generating an `OAuth2Token` from the information contained in the provided <>. +An `OAuth2TokenGenerator` is responsible for generating an `OAuth2Token` from the information contained in the provided xref:core-model-components.adoc#oauth2-token-context[OAuth2TokenContext]. The `OAuth2Token` generated primarily depends on the type of `OAuth2TokenType` specified in the `OAuth2TokenContext`. @@ -360,11 +360,11 @@ For example, when the `value` for `OAuth2TokenType` is: * `refresh_token`, then `OAuth2RefreshToken` is generated. * `id_token`, then `OidcIdToken` is generated. -Furthermore, the format of the generated `OAuth2AccessToken` varies, depending on the `TokenSettings.getAccessTokenFormat()` configured for the <>. +Furthermore, the format of the generated `OAuth2AccessToken` varies, depending on the `TokenSettings.getAccessTokenFormat()` configured for the xref:core-model-components.adoc#registered-client[RegisteredClient]. If the format is `OAuth2TokenFormat.SELF_CONTAINED` (the default), then a `Jwt` is generated. If the format is `OAuth2TokenFormat.REFERENCE`, then an "opaque" token is generated. -Finally, if the generated `OAuth2Token` has a set of claims and implements `ClaimAccessor`, the claims are made accessible from <>. +Finally, if the generated `OAuth2Token` has a set of claims and implements `ClaimAccessor`, the claims are made accessible from xref:core-model-components.adoc#oauth2-authorization[OAuth2Authorization.Token.getClaims()]. The `OAuth2TokenGenerator` is primarily used by components that implement authorization grant processing – for example, `authorization_code`, `client_credentials`, and `refresh_token`. @@ -419,8 +419,8 @@ The `OAuth2AuthorizationServerConfigurer` is useful when applying multiple confi [[oauth2-token-customizer]] == OAuth2TokenCustomizer -An `OAuth2TokenCustomizer` provides the ability to customize the attributes of an `OAuth2Token`, which are accessible in the provided <>. -It is used by an <> to let it customize the attributes of the `OAuth2Token` before it is generated. +An `OAuth2TokenCustomizer` provides the ability to customize the attributes of an `OAuth2Token`, which are accessible in the provided xref:core-model-components.adoc#oauth2-token-context[OAuth2TokenContext]. +It is used by an xref:core-model-components.adoc#oauth2-token-generator[OAuth2TokenGenerator] to let it customize the attributes of the `OAuth2Token` before it is generated. An `OAuth2TokenCustomizer` declared with a generic type of `OAuth2TokenClaimsContext` (`implements OAuth2TokenContext`) provides the ability to customize the claims of an "opaque" `OAuth2AccessToken`. `OAuth2TokenClaimsContext.getClaims()` provides access to the `OAuth2TokenClaimsSet.Builder`, allowing the ability to add, replace, and remove claims. @@ -492,7 +492,7 @@ public OAuth2TokenCustomizer jwtCustomizer() { If the `OAuth2TokenGenerator` is not provided as a `@Bean` or is not configured through the `OAuth2AuthorizationServerConfigurer`, an `OAuth2TokenCustomizer` `@Bean` will automatically be configured with a `JwtGenerator`. [TIP] -For an example showing how you can xref:guides/how-to-userinfo.adoc#customize-id-token[customize the ID token], see the guide xref:guides/how-to-userinfo.adoc#how-to-userinfo[How-to: Customize the OpenID Connect 1.0 UserInfo response]. +For an example showing how you can xref:guides/how-to-userinfo.adoc#customize-id-token[customize the ID token], see the guide xref:guides/how-to-userinfo.adoc[How-to: Customize the OpenID Connect 1.0 UserInfo response]. [[session-registry]] == SessionRegistry diff --git a/docs/modules/ROOT/pages/getting-started.adoc b/docs/modules/ROOT/pages/getting-started.adoc index e9ed718f9..b36a08d88 100644 --- a/docs/modules/ROOT/pages/getting-started.adoc +++ b/docs/modules/ROOT/pages/getting-started.adoc @@ -69,7 +69,7 @@ To get started, you need the minimum required components defined as a `@Bean`. W include::{docs-java}/sample/gettingStarted/application.yml[] ---- -TIP: Beyond the Getting Started experience, most users will want to customize the default configuration. The <> demonstrates providing all of the necessary beans yourself. +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. [[defining-required-components]] == Defining Required Components diff --git a/docs/modules/ROOT/pages/guides/how-to-ext-grant-type.adoc b/docs/modules/ROOT/pages/guides/how-to-ext-grant-type.adoc index d1957db3a..01a1beadc 100644 --- a/docs/modules/ROOT/pages/guides/how-to-ext-grant-type.adoc +++ b/docs/modules/ROOT/pages/guides/how-to-ext-grant-type.adoc @@ -4,16 +4,16 @@ :index-link: ../how-to.html :docs-dir: .. -This guide shows how to extend xref:{docs-dir}/index.adoc#top[Spring Authorization Server] with an https://datatracker.ietf.org/doc/html/rfc6749#section-4.5[extension authorization grant type]. -The purpose of this guide is to demonstrate how to implement an extension authorization grant type and configure it at the xref:{docs-dir}/protocol-endpoints.adoc#oauth2-token-endpoint[OAuth2 Token endpoint]. +This guide shows how to extend xref:index.adoc[Spring Authorization Server] with an https://datatracker.ietf.org/doc/html/rfc6749#section-4.5[extension authorization grant type]. +The purpose of this guide is to demonstrate how to implement an extension authorization grant type and configure it at the xref:protocol-endpoints.adoc#oauth2-token-endpoint[OAuth2 Token endpoint]. -Extending Spring Authorization Server with a new authorization grant type requires implementing an `AuthenticationConverter` and `AuthenticationProvider`, and configuring both components at the xref:{docs-dir}/protocol-endpoints.adoc#oauth2-token-endpoint[OAuth2 Token endpoint]. +Extending Spring Authorization Server with a new authorization grant type requires implementing an `AuthenticationConverter` and `AuthenticationProvider`, and configuring both components at the xref:protocol-endpoints.adoc#oauth2-token-endpoint[OAuth2 Token endpoint]. In addition to the component implementations, a unique absolute URI needs to be assigned for use with the `grant_type` parameter. -* <> -* <> -* <> -* <> +* xref:guides/how-to-ext-grant-type.adoc#implement-authentication-converter[Implement AuthenticationConverter] +* xref:guides/how-to-ext-grant-type.adoc#implement-authentication-provider[Implement AuthenticationProvider] +* xref:guides/how-to-ext-grant-type.adoc#configure-token-endpoint[Configure OAuth2 Token Endpoint] +* xref:guides/how-to-ext-grant-type.adoc#request-access-token[Request the Access Token] [[implement-authentication-converter]] == Implement AuthenticationConverter @@ -30,7 +30,7 @@ TIP: Click on the "Expand folded text" icon in the code sample above to display <1> If the `grant_type` parameter is *not* `urn:ietf:params:oauth:grant-type:custom_code`, then return `null`, allowing another `AuthenticationConverter` to process the token request. <2> The `code` parameter contains the authorization grant. -<3> Return an instance of `CustomCodeGrantAuthenticationToken`, which is processed by <>. +<3> Return an instance of `CustomCodeGrantAuthenticationToken`, which is processed by xref:guides/how-to-ext-grant-type.adoc#implement-authentication-provider[`CustomCodeGrantAuthenticationProvider`]. [[implement-authentication-provider]] == Implement AuthenticationProvider @@ -45,12 +45,12 @@ The following example shows a sample implementation of the `AuthenticationProvid include::{examples-dir}/src/main/java/sample/extgrant/CustomCodeGrantAuthenticationProvider.java[] ---- -NOTE: `CustomCodeGrantAuthenticationProvider` processes `CustomCodeGrantAuthenticationToken`, which is created by <>. +NOTE: `CustomCodeGrantAuthenticationProvider` processes `CustomCodeGrantAuthenticationToken`, which is created by xref:guides/how-to-ext-grant-type.adoc#implement-authentication-converter[`CustomCodeGrantAuthenticationConverter`]. [[configure-token-endpoint]] == Configure OAuth2 Token Endpoint -The following example shows how to configure the xref:{docs-dir}/protocol-endpoints.adoc#oauth2-token-endpoint[OAuth2 Token endpoint] with the `AuthenticationConverter` and `AuthenticationProvider`: +The following example shows how to configure the xref:protocol-endpoints.adoc#oauth2-token-endpoint[OAuth2 Token endpoint] with the `AuthenticationConverter` and `AuthenticationProvider`: .SecurityConfig [source,java] diff --git a/docs/modules/ROOT/pages/guides/how-to-jpa.adoc b/docs/modules/ROOT/pages/guides/how-to-jpa.adoc index 276ec79a8..4deda07ec 100644 --- a/docs/modules/ROOT/pages/guides/how-to-jpa.adoc +++ b/docs/modules/ROOT/pages/guides/how-to-jpa.adoc @@ -4,33 +4,33 @@ :index-link: ../how-to.html :docs-dir: .. -This guide shows how to implement the xref:{docs-dir}/core-model-components.adoc#core-model-components[core services] of xref:{docs-dir}/index.adoc#top[Spring Authorization Server] with JPA. +This guide shows how to implement the xref:core-model-components.adoc[core services] of xref:index.adoc[Spring Authorization Server] with JPA. The purpose of this guide is to provide a starting point for implementing these services yourself, with the intention that you can make modifications to suit your needs. -* <> -* <> -* <> -* <> +* xref:guides/how-to-jpa.adoc#define-data-model[Define the data model] +* xref:guides/how-to-jpa.adoc#create-jpa-entities[Create JPA entities] +* xref:guides/how-to-jpa.adoc#create-spring-data-repositories[Create Spring Data repositories] +* xref:guides/how-to-jpa.adoc#implement-core-services[Implement core services] [[define-data-model]] == Define the data model This guide provides a starting point for the data model and uses the simplest possible structure and data types. -To come up with the initial schema, we begin by reviewing the xref:{docs-dir}/core-model-components.adoc#core-model-components[domain objects] used by the core services. +To come up with the initial schema, we begin by reviewing the xref:core-model-components.adoc[domain objects] used by the core services. [NOTE] Except for token, state, metadata, settings, and claims values, we use the JPA default column length of 255 for all columns. In reality, the length and even type of columns you use may need to be customized. You are encouraged to experiment and test before deploying to production. -* <> -* <> -* <> +* xref:guides/how-to-jpa.adoc#client-schema[Client Schema] +* xref:guides/how-to-jpa.adoc#authorization-schema[Authorization Schema] +* xref:guides/how-to-jpa.adoc#authorization-consent-schema[Authorization Consent Schema] [[client-schema]] === Client Schema -The xref:{docs-dir}/core-model-components.adoc#registered-client[`RegisteredClient`] domain object contains a few multi-valued fields and some settings fields that require storing arbitrary key/value data. +The xref:core-model-components.adoc#registered-client[`RegisteredClient`] domain object contains a few multi-valued fields and some settings fields that require storing arbitrary key/value data. The following listing shows the `client` schema. .Client Schema @@ -57,7 +57,7 @@ CREATE TABLE client ( [[authorization-schema]] === Authorization Schema -The xref:{docs-dir}/core-model-components.adoc#oauth2-authorization[`OAuth2Authorization`] domain object is more complex and contains several multi-valued fields as well as numerous arbitrarily long token values, metadata, settings and claims values. +The xref:core-model-components.adoc#oauth2-authorization[`OAuth2Authorization`] domain object is more complex and contains several multi-valued fields as well as numerous arbitrarily long token values, metadata, settings and claims values. The built-in JDBC implementation utilizes a flattened structure that prefers performance over normalization, which we adopt here as well. [CAUTION] @@ -111,7 +111,7 @@ CREATE TABLE authorization ( [[authorization-consent-schema]] === Authorization Consent Schema -The xref:{docs-dir}/core-model-components.adoc#oauth2-authorization-consent[`OAuth2AuthorizationConsent`] domain object is the simplest to model and contains only a single multi-valued field in addition to a composite key. +The xref:core-model-components.adoc#oauth2-authorization-consent[`OAuth2AuthorizationConsent`] domain object is the simplest to model and contains only a single multi-valued field in addition to a composite key. The following listing shows the `authorizationConsent` schema. .Authorization Consent Schema @@ -134,14 +134,14 @@ The preceding schema examples provide a reference for the structure of the entit The following entities are minimally annotated and are just examples. They allow the schema to be created dynamically and therefore do not require the above sql scripts to be executed manually. -* <> -* <> -* <> +* xref:guides/how-to-jpa.adoc#client-entity[Client Entity] +* xref:guides/how-to-jpa.adoc#authorization-entity[Authorization Entity] +* xref:guides/how-to-jpa.adoc#authorization-consent-entity[Authorization Consent Entity] [[client-entity]] === Client Entity -The following listing shows the `Client` entity, which is used to persist information mapped from the xref:{docs-dir}/core-model-components.adoc#registered-client[`RegisteredClient`] domain object. +The following listing shows the `Client` entity, which is used to persist information mapped from the xref:core-model-components.adoc#registered-client[`RegisteredClient`] domain object. [[sample.jpa.entity.client]] .Client Entity @@ -153,7 +153,7 @@ include::{examples-dir}/src/main/java/sample/jpa/entity/client/Client.java[] [[authorization-entity]] === Authorization Entity -The following listing shows the `Authorization` entity, which is used to persist information mapped from the xref:{docs-dir}/core-model-components.adoc#oauth2-authorization[`OAuth2Authorization`] domain object. +The following listing shows the `Authorization` entity, which is used to persist information mapped from the xref:core-model-components.adoc#oauth2-authorization[`OAuth2Authorization`] domain object. [[sample.jpa.entity.authorization]] .Authorization Entity @@ -165,7 +165,7 @@ include::{examples-dir}/src/main/java/sample/jpa/entity/authorization/Authorizat [[authorization-consent-entity]] === Authorization Consent Entity -The following listing shows the `AuthorizationConsent` entity, which is used to persist information mapped from the xref:{docs-dir}/core-model-components.adoc#oauth2-authorization-consent[`OAuth2AuthorizationConsent`] domain object. +The following listing shows the `AuthorizationConsent` entity, which is used to persist information mapped from the xref:core-model-components.adoc#oauth2-authorization-consent[`OAuth2AuthorizationConsent`] domain object. [[sample.jpa.entity.authorizationConsent]] .Authorization Consent Entity @@ -179,14 +179,14 @@ include::{examples-dir}/src/main/java/sample/jpa/entity/authorizationConsent/Aut By closely examining the interfaces of each core service and reviewing the `Jdbc` implementations, we can derive a minimal set of queries needed for supporting a JPA version of each interface. -* <> -* <> -* <> +* xref:guides/how-to-jpa.adoc#client-repository[Client Repository] +* xref:guides/how-to-jpa.adoc#authorization-repository[Authorization Repository] +* xref:guides/how-to-jpa.adoc#authorization-consent-repository[Authorization Consent Repository] [[client-repository]] === Client Repository -The following listing shows the `ClientRepository`, which is able to find a <> by the `id` and `clientId` fields. +The following listing shows the `ClientRepository`, which is able to find a xref:guides/how-to-jpa.adoc#client-entity[`Client`] by the `id` and `clientId` fields. [[sample.jpa.repository.client]] .Client Repository @@ -198,7 +198,7 @@ include::{examples-dir}/src/main/java/sample/jpa/repository/client/ClientReposit [[authorization-repository]] === Authorization Repository -The following listing shows the `AuthorizationRepository`, which is able to find an <> by the `id` field as well as the `state`, `authorizationCodeValue`, `accessTokenValue`, `refreshTokenValue`, `userCodeValue` and `deviceCodeValue` token fields. +The following listing shows the `AuthorizationRepository`, which is able to find an xref:guides/how-to-jpa.adoc#authorization-entity[`Authorization`] by the `id` field as well as the `state`, `authorizationCodeValue`, `accessTokenValue`, `refreshTokenValue`, `userCodeValue` and `deviceCodeValue` token fields. It also allows querying a combination of token fields. [[sample.jpa.repository.authorization]] @@ -211,7 +211,7 @@ include::{examples-dir}/src/main/java/sample/jpa/repository/authorization/Author [[authorization-consent-repository]] === Authorization Consent Repository -The following listing shows the `AuthorizationConsentRepository`, which is able to find and delete an <> by the `registeredClientId` and `principalName` fields that form a composite primary key. +The following listing shows the `AuthorizationConsentRepository`, which is able to find and delete an xref:guides/how-to-jpa.adoc#authorization-consent-entity[`AuthorizationConsent`] by the `registeredClientId` and `principalName` fields that form a composite primary key. [[sample.jpa.repository.authorizationConsent]] .Authorization Consent Repository @@ -223,7 +223,7 @@ include::{examples-dir}/src/main/java/sample/jpa/repository/authorizationConsent [[implement-core-services]] == Implement core services -With the above <> and <>, we can begin implementing the core services. +With the above xref:guides/how-to-jpa.adoc#create-jpa-entities[entities] and xref:guides/how-to-jpa.adoc#create-spring-data-repositories[repositories], we can begin implementing the core services. By reviewing the `Jdbc` implementations, we can derive a minimal set of internal utilities for converting to and from string values for enumerations and reading and writing JSON data for attributes, settings, metadata and claims fields. [CAUTION] @@ -231,13 +231,13 @@ Keep in mind that writing JSON data to text columns with a fixed length has prov While these examples continue to do so, you may need to split these fields out into a separate table or data store that supports arbitrarily long data values. * <> -* <> -* <> +* xref:guides/how-to-jpa.adoc#authorization-service[Authorization Service] +* xref:guides/how-to-jpa.adoc#authorization-consent-service[Authorization Consent Service] [[registered-client-repository]] === Registered Client Repository -The following listing shows the `JpaRegisteredClientRepository`, which uses a <> for persisting a <> and maps to and from the xref:{docs-dir}/core-model-components.adoc#registered-client[`RegisteredClient`] domain object. +The following listing shows the `JpaRegisteredClientRepository`, which uses a xref:guides/how-to-jpa.adoc#client-repository[`ClientRepository`] for persisting a xref:guides/how-to-jpa.adoc#client-entity[`Client`] and maps to and from the xref:core-model-components.adoc#registered-client[`RegisteredClient`] domain object. [[sample.jpa.service.client]] .`RegisteredClientRepository` Implementation @@ -249,7 +249,7 @@ include::{examples-dir}/src/main/java/sample/jpa/service/client/JpaRegisteredCli [[authorization-service]] === Authorization Service -The following listing shows the `JpaOAuth2AuthorizationService`, which uses an <> for persisting an <> and maps to and from the xref:{docs-dir}/core-model-components.adoc#oauth2-authorization[`OAuth2Authorization`] domain object. +The following listing shows the `JpaOAuth2AuthorizationService`, which uses an xref:guides/how-to-jpa.adoc#authorization-repository[`AuthorizationRepository`] for persisting an xref:guides/how-to-jpa.adoc#authorization-entity[`Authorization`] and maps to and from the xref:core-model-components.adoc#oauth2-authorization[`OAuth2Authorization`] domain object. [[sample.jpa.service.authorization]] .`OAuth2AuthorizationService` Implementation @@ -261,7 +261,7 @@ include::{examples-dir}/src/main/java/sample/jpa/service/authorization/JpaOAuth2 [[authorization-consent-service]] === Authorization Consent Service -The following listing shows the `JpaOAuth2AuthorizationConsentService`, which uses an <> for persisting an <> and maps to and from the xref:{docs-dir}/core-model-components.adoc#oauth2-authorization-consent[`OAuth2AuthorizationConsent`] domain object. +The following listing shows the `JpaOAuth2AuthorizationConsentService`, which uses an xref:guides/how-to-jpa.adoc#authorization-consent-repository[`AuthorizationConsentRepository`] for persisting an xref:guides/how-to-jpa.adoc#authorization-consent-entity[`AuthorizationConsent`] and maps to and from the xref:core-model-components.adoc#oauth2-authorization-consent[`OAuth2AuthorizationConsent`] domain object. [[sample.jpa.service.authorizationConsent]] .`OAuth2AuthorizationConsentService` Implementation diff --git a/docs/modules/ROOT/pages/guides/how-to-pkce.adoc b/docs/modules/ROOT/pages/guides/how-to-pkce.adoc index 8bf800214..2aefbac77 100644 --- a/docs/modules/ROOT/pages/guides/how-to-pkce.adoc +++ b/docs/modules/ROOT/pages/guides/how-to-pkce.adoc @@ -4,14 +4,14 @@ :index-link: ../how-to.html :docs-dir: .. -This guide shows how to configure xref:{docs-dir}/index.adoc#top[Spring Authorization Server] to support a Single Page Application (SPA) with Proof Key for Code Exchange (PKCE). +This guide shows how to configure xref:index.adoc[Spring Authorization Server] to support a Single Page Application (SPA) with Proof Key for Code Exchange (PKCE). The purpose of this guide is to demonstrate how to support a public client and require PKCE for client authentication. NOTE: Spring Authorization Server will not issue refresh tokens for a public client. We recommend the backend for frontend (BFF) pattern as an alternative to exposing a public client. See https://github.com/spring-projects/spring-authorization-server/issues/297#issue-896744390[gh-297] for more information. -* <> -* <> -* <> +* xref:guides/how-to-pkce.adoc#enable-cors[Enable CORS] +* xref:guides/how-to-pkce.adoc#configure-public-client[Configure a Public Client] +* xref:guides/how-to-pkce.adoc#authenticate-with-client[Authenticate with the Client] [[enable-cors]] == Enable CORS @@ -38,7 +38,7 @@ TIP: Click on the "Expand folded text" icon in the code sample above to display A SPA cannot securely store credentials and therefore must be treated as a https://datatracker.ietf.org/doc/html/rfc6749#section-2.1[public client^]. Public clients should be required to use https://datatracker.ietf.org/doc/html/rfc7636#section-4[Proof Key for Code Exchange] (PKCE). -Continuing the <> example, you can configure Spring Authorization Server to support a public client using the Client Authentication Method `none` and require PKCE as in the following example: +Continuing the xref:guides/how-to-pkce.adoc#enable-cors-configuration[earlier] example, you can configure Spring Authorization Server to support a public client using the Client Authentication Method `none` and require PKCE as in the following example: [[configure-public-client-example]] .Yaml @@ -53,7 +53,7 @@ include::{examples-dir}/src/main/java/sample/pkce/application.yml[] include::{examples-dir}/src/main/java/sample/pkce/ClientConfig.java[tag=client,indent=0] ---- -NOTE: The `requireProofKey` setting is helpful in situations where you forget to include the `code_challenge` and `code_challenge_method` query parameters because you will receive an error indicating PKCE is required during the xref:{docs-dir}/protocol-endpoints.adoc#oauth2-authorization-endpoint[Authorization Request] instead of a general client authentication error during the xref:{docs-dir}/protocol-endpoints.adoc#oauth2-token-endpoint[Token Request]. +NOTE: The `requireProofKey` setting is helpful in situations where you forget to include the `code_challenge` and `code_challenge_method` query parameters because you will receive an error indicating PKCE is required during the xref:protocol-endpoints.adoc#oauth2-authorization-endpoint[Authorization Request] instead of a general client authentication error during the xref:protocol-endpoints.adoc#oauth2-token-endpoint[Token Request]. [[authenticate-with-client]] == Authenticate with the Client @@ -66,11 +66,11 @@ NOTE: A SPA is a browser-based application and therefore uses the same redirecti A more detailed answer requires an understanding of the flow(s) involved in OAuth2 and OpenID Connect, in this case the Authorization Code flow. The steps of the Authorization Code flow are as follows: -1. The client initiates an OAuth2 request via a redirect to the xref:{docs-dir}/protocol-endpoints.adoc#oauth2-authorization-endpoint[Authorization Endpoint]. For a public client, this step includes generating the `code_verifier` and calculating the `code_challenge`, which is then sent as a query parameter. +1. The client initiates an OAuth2 request via a redirect to the xref:protocol-endpoints.adoc#oauth2-authorization-endpoint[Authorization Endpoint]. For a public client, this step includes generating the `code_verifier` and calculating the `code_challenge`, which is then sent as a query parameter. 2. If the user is not authenticated, the authorization server will redirect to the login page. After authentication, the user is redirected back to the Authorization Endpoint again. 3. If the user has not consented to the requested scope(s) and consent is required, the consent page is displayed. 4. Once the user has consented, the authorization server generates an `authorization_code` and redirects back to the client via the `redirect_uri`. -5. The client obtains the `authorization_code` via a query parameter and performs a request to the xref:{docs-dir}/protocol-endpoints.adoc#oauth2-token-endpoint[Token Endpoint]. For a public client, this step includes sending the `code_verifier` parameter instead of credentials for authentication. +5. The client obtains the `authorization_code` via a query parameter and performs a request to the xref:protocol-endpoints.adoc#oauth2-token-endpoint[Token Endpoint]. For a public client, this step includes sending the `code_verifier` parameter instead of credentials for authentication. As you can see, the flow is fairly involved and this overview only scratches the surface. diff --git a/docs/modules/ROOT/pages/guides/how-to-social-login.adoc b/docs/modules/ROOT/pages/guides/how-to-social-login.adoc index 47a054224..3c7942fcf 100644 --- a/docs/modules/ROOT/pages/guides/how-to-social-login.adoc +++ b/docs/modules/ROOT/pages/guides/how-to-social-login.adoc @@ -6,14 +6,14 @@ :github-ref: main :github-base-url: https://github.com/spring-projects/spring-authorization-server/blob/{github-ref} -This guide shows how to configure xref:{docs-dir}/index.adoc#top[Spring Authorization Server] with a social login provider (such as Google, GitHub, etc.) for {spring-security-reference-base-url}/servlet/authentication/index.html[authentication]. +This guide shows how to configure xref:index.adoc[Spring Authorization Server] with a social login provider (such as Google, GitHub, etc.) for {spring-security-reference-base-url}/servlet/authentication/index.html[authentication]. The purpose of this guide is to demonstrate how to replace {spring-security-reference-base-url}/servlet/authentication/passwords/form.html[Form Login] with {spring-security-reference-base-url}/servlet/oauth2/login/index.html[OAuth 2.0 Login]. NOTE: Spring Authorization Server is built on {spring-security-reference-base-url}/index.html[Spring Security] and we will be using Spring Security concepts throughout this guide. -* <> -* <> -* <> +* xref:guides/how-to-social-login.adoc#register-social-login-provider[Register with Social Login Provider] +* xref:guides/how-to-social-login.adoc#configure-oauth2-login[Configure OAuth 2.0 Login] +* xref:guides/how-to-social-login.adoc#advanced-use-cases[Advanced Use Cases] [[register-social-login-provider]] == Register with Social Login Provider @@ -45,11 +45,11 @@ In addition, you will need to reference the provider's documentation and take no [[configure-oauth2-login]] == Configure OAuth 2.0 Login -Once you've <> with a social login provider, you can proceed to configuring Spring Security for {spring-security-reference-base-url}/servlet/oauth2/login/index.html[OAuth 2.0 Login]. +Once you've xref:guides/how-to-social-login.adoc#register-social-login-provider[registered] with a social login provider, you can proceed to configuring Spring Security for {spring-security-reference-base-url}/servlet/oauth2/login/index.html[OAuth 2.0 Login]. -* <> -* <> -* <> +* xref:guides/how-to-social-login.adoc#configure-oauth2-login-dependency[Add OAuth2 Client Dependency] +* xref:guides/how-to-social-login.adoc#configure-oauth2-login-client-registration[Register a Client] +* xref:guides/how-to-social-login.adoc#configure-oauth2-login-authentication[Configure Authentication] [[configure-oauth2-login-dependency]] === Add OAuth2 Client Dependency @@ -76,7 +76,7 @@ implementation "org.springframework.boot:spring-boot-starter-oauth2-client" [[configure-oauth2-login-client-registration]] === Register a Client -Next, configure the `ClientRegistration` with the values obtained <>. +Next, configure the `ClientRegistration` with the values obtained xref:guides/how-to-social-login.adoc#register-social-login-provider[earlier]. Using Okta as an example, configure the following properties: [[configure-oauth2-login-okta-example]] @@ -99,7 +99,7 @@ For more information about configuring the `ClientRegistration`, see {spring-sec Finally, to configure Spring Authorization Server to use a social login provider for authentication, you can use `oauth2Login()` instead of `formLogin()`. You can also automatically redirect an unauthenticated user to the provider by configuring `exceptionHandling()` with an `AuthenticationEntryPoint`. -Continuing our <>, configure Spring Security using a `@Configuration` as in the following example: +Continuing our xref:guides/how-to-social-login.adoc#configure-oauth2-login-okta-example[earlier example], configure Spring Security using a `@Configuration` as in the following example: .Configure OAuth 2.0 Login [source,java] @@ -112,7 +112,7 @@ include::{examples-dir}/src/main/java/sample/socialLogin/SecurityConfig.java[] <3> A Spring Security filter chain for https://docs.spring.io/spring-security/reference/servlet/authentication/index.html[authentication]. <4> Configure {spring-security-reference-base-url}/servlet/oauth2/login/index.html[OAuth 2.0 Login] for authentication. -If you configured a `UserDetailsService` when xref:{docs-dir}/getting-started.adoc#developing-your-first-application[getting started], you can remove it now. +If you configured a `UserDetailsService` when xref:getting-started.adoc#developing-your-first-application[getting started], you can remove it now. [[advanced-use-cases]] == Advanced Use Cases @@ -120,8 +120,8 @@ If you configured a `UserDetailsService` when xref:{docs-dir}/getting-started.ad The https://github.com/spring-projects/spring-authorization-server/tree/{github-ref}/samples#demo-sample[demo authorization server sample^] demonstrates advanced configuration options for federating identity providers. Select from the following use cases to see an example of each: -* I want to <> -* I want to <> +* I want to xref:guides/how-to-social-login.adoc#advanced-use-cases-capture-users[Capture Users in a Database] +* I want to xref:guides/how-to-social-login.adoc#advanced-use-cases-map-claims[Map Claims to an ID Token] [[advanced-use-cases-capture-users]] === Capture Users in a Database diff --git a/docs/modules/ROOT/pages/guides/how-to-userinfo.adoc b/docs/modules/ROOT/pages/guides/how-to-userinfo.adoc index e91e4fe84..0cb153cc4 100644 --- a/docs/modules/ROOT/pages/guides/how-to-userinfo.adoc +++ b/docs/modules/ROOT/pages/guides/how-to-userinfo.adoc @@ -4,16 +4,16 @@ :index-link: ../how-to.html :docs-dir: .. -This guide shows how to customize the xref:{docs-dir}/protocol-endpoints.adoc#oidc-user-info-endpoint[UserInfo endpoint] of the xref:{docs-dir}/index.adoc#top[Spring Authorization Server]. +This guide shows how to customize the xref:protocol-endpoints.adoc#oidc-user-info-endpoint[UserInfo endpoint] of the xref:index.adoc[Spring Authorization Server]. The purpose of this guide is to demonstrate how to enable the endpoint and use the available customization options to produce a custom response. -* <> -* <> +* xref:guides/how-to-userinfo.adoc#enable-user-info[Enable the User Info Endpoint] +* xref:guides/how-to-userinfo.adoc#customize-user-info[Customize the User Info response] [[enable-user-info]] == Enable the User Info Endpoint -The xref:{docs-dir}/protocol-endpoints.adoc#oidc-user-info-endpoint[OpenID Connect 1.0 UserInfo endpoint] is an OAuth2 protected resource, which *REQUIRES* an access token to be sent as a bearer token in the https://openid.net/specs/openid-connect-core-1_0.html#UserInfoRequest[UserInfo request]. +The xref:protocol-endpoints.adoc#oidc-user-info-endpoint[OpenID Connect 1.0 UserInfo endpoint] is an OAuth2 protected resource, which *REQUIRES* an access token to be sent as a bearer token in the https://openid.net/specs/openid-connect-core-1_0.html#UserInfoRequest[UserInfo request]. > The Access Token obtained from an OpenID Connect Authentication Request MUST be sent as a Bearer Token, per Section 2 of https://openid.net/specs/openid-connect-core-1_0.html#RFC6750[OAuth 2.0 Bearer Token Usage] [RFC6750]. @@ -39,13 +39,13 @@ This configuration provides the following: The following sections describe some options for customizing the user info response. -* <> -* <> +* xref:guides/how-to-userinfo.adoc#customize-id-token[Customize the ID Token] +* xref:guides/how-to-userinfo.adoc#customize-user-info-mapper[Customize the User Info Mapper] [[customize-id-token]] === Customize the ID Token -By default, the user info response is generated by using claims from the `id_token` that are returned with the xref:{docs-dir}/protocol-endpoints.adoc#oauth2-token-endpoint[token response]. +By default, the user info response is generated by using claims from the `id_token` that are returned with the xref:protocol-endpoints.adoc#oauth2-token-endpoint[token response]. Using the default strategy, https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims[standard claims] are returned only with the user info response based on the https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims[requested scopes] during authorization. The preferred way to customize the user info response is to add standard claims to the `id_token`. @@ -59,7 +59,7 @@ include::{examples-dir}/src/main/java/sample/userinfo/idtoken/IdTokenCustomizerC This configuration provides the following: -<1> An instance of xref:{docs-dir}/core-model-components.adoc#oauth2-token-customizer[`OAuth2TokenCustomizer`] for customizing the `id_token`. +<1> An instance of xref:core-model-components.adoc#oauth2-token-customizer[`OAuth2TokenCustomizer`] for customizing the `id_token`. <2> A custom service used to obtain user info in a domain-specific way. The following listing shows a custom service for looking up user info in a domain-specific way: @@ -73,7 +73,7 @@ include::{examples-dir}/src/main/java/sample/userinfo/idtoken/OidcUserInfoServic === Customize the User Info Mapper To fully customize the user info response, you can provide a custom user info mapper capable of generating the object used to render the response, which is an instance of the `OidcUserInfo` class from Spring Security. -The mapper implementation receives an instance of `OidcUserInfoAuthenticationContext` with information about the current request, including the xref:{docs-dir}/core-model-components.adoc#oauth2-authorization[`OAuth2Authorization`]. +The mapper implementation receives an instance of `OidcUserInfoAuthenticationContext` with information about the current request, including the xref:core-model-components.adoc#oauth2-authorization[`OAuth2Authorization`]. The following listing shows how to use the customization option that is available while working directly with the `OAuth2AuthorizationServerConfigurer`. @@ -83,7 +83,7 @@ The following listing shows how to use the customization option that is availabl include::{examples-dir}/src/main/java/sample/userinfo/jwt/JwtUserInfoMapperSecurityConfig.java[] ---- -This configuration maps claims from the access token (which is a JWT when using the xref:{docs-dir}/getting-started.adoc#sample.gettingStarted[Getting Started config]) to populate the user info response and provides the following: +This configuration maps claims from the access token (which is a JWT when using the xref:getting-started.adoc#sample.gettingStarted[Getting Started config]) to populate the user info response and provides the following: <1> A Spring Security filter chain for the xref:{docs-dir}/protocol-endpoints.adoc[Protocol Endpoints]. <2> A user info mapper that maps claims in a domain-specific way. @@ -92,7 +92,7 @@ This configuration maps claims from the access token (which is a JWT when using <5> An example showing how to apply the `OAuth2AuthorizationServerConfigurer` to the Spring Security configuration. The user info mapper is not limited to mapping claims from a JWT, but this is a simple example that demonstrates the customization option. -Similar to the <> where we customize claims of the ID token, you can customize claims of the access token itself ahead of time, as in the following example: +Similar to the xref:guides/how-to-userinfo.adoc#customize-id-token[example shown earlier] where we customize claims of the ID token, you can customize claims of the access token itself ahead of time, as in the following example: [source,java] ---- diff --git a/docs/modules/ROOT/pages/protocol-endpoints.adoc b/docs/modules/ROOT/pages/protocol-endpoints.adoc index 1c30209f1..94a55f9a7 100644 --- a/docs/modules/ROOT/pages/protocol-endpoints.adoc +++ b/docs/modules/ROOT/pages/protocol-endpoints.adoc @@ -572,7 +572,7 @@ public JwtDecoder jwtDecoder(JWKSource jwkSource) { A `JwtDecoder` `@Bean` is *REQUIRED* for the OpenID Connect 1.0 UserInfo endpoint. [TIP] -The guide xref:guides/how-to-userinfo.adoc#how-to-userinfo[How-to: Customize the OpenID Connect 1.0 UserInfo response] contains examples of customizing the UserInfo endpoint. +The guide xref:guides/how-to-userinfo.adoc[How-to: Customize the OpenID Connect 1.0 UserInfo response] contains examples of customizing the UserInfo endpoint. [[oidc-client-registration-endpoint]] == OpenID Connect 1.0 Client Registration Endpoint From 492af54b016769def1239173355738267ab18bbb Mon Sep 17 00:00:00 2001 From: Rob Winch Date: Mon, 3 Jul 2023 13:36:26 -0500 Subject: [PATCH 06/12] Enable Section Summary TOC for small pages --- docs/modules/ROOT/pages/getting-help.adoc | 1 + docs/modules/ROOT/pages/how-to.adoc | 1 + docs/modules/ROOT/pages/index.adoc | 1 + 3 files changed, 3 insertions(+) diff --git a/docs/modules/ROOT/pages/getting-help.adoc b/docs/modules/ROOT/pages/getting-help.adoc index c95e9575b..d51f583ca 100644 --- a/docs/modules/ROOT/pages/getting-help.adoc +++ b/docs/modules/ROOT/pages/getting-help.adoc @@ -1,5 +1,6 @@ [[getting-help]] = Getting Help +:page-section-summary-toc: 1 [[community]] == Community diff --git a/docs/modules/ROOT/pages/how-to.adoc b/docs/modules/ROOT/pages/how-to.adoc index 5a67c36c3..cee5e4621 100644 --- a/docs/modules/ROOT/pages/how-to.adoc +++ b/docs/modules/ROOT/pages/how-to.adoc @@ -1,6 +1,7 @@ [[how-to]] = How-to Guides +:page-section-summary-toc: 1 [[how-to-overview]] == List of Guides diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc index e9f8360f8..1aec0a189 100644 --- a/docs/modules/ROOT/pages/index.adoc +++ b/docs/modules/ROOT/pages/index.adoc @@ -1,5 +1,6 @@ [[top]] = Spring Authorization Server Reference +:page-section-summary-toc: 1 Joe Grandja, Steve Riesenberg v{spring-authorization-server-version} :docinfo: private-footer From 8b1ee4aef51c82a0419c680d86c4a84aacef2b86 Mon Sep 17 00:00:00 2001 From: Rob Winch Date: Mon, 3 Jul 2023 14:52:10 -0500 Subject: [PATCH 07/12] Fix includes --- docs/antora-playbook.yml | 12 +- docs/antora.yml | 23 +- docs/framework-docs.gradle | 218 ------------------ docs/modules/ROOT/examples/docs-src | 1 + docs/modules/ROOT/examples/samples | 1 + docs/modules/ROOT/nav.adoc | 1 - docs/modules/ROOT/pages/attributes.adoc | 3 - .../pages/guides/how-to-ext-grant-type.adoc | 6 +- .../modules/ROOT/pages/guides/how-to-jpa.adoc | 18 +- .../ROOT/pages/guides/how-to-pkce.adoc | 6 +- .../pages/guides/how-to-social-login.adoc | 4 +- .../ROOT/pages/guides/how-to-userinfo.adoc | 10 +- docs/spring-authorization-server-docs.gradle | 84 ++++++- ...-authorization-server-docs-examples.gradle | 33 --- ...ustomCodeGrantAuthenticationConverter.java | 0 ...CustomCodeGrantAuthenticationProvider.java | 0 .../CustomCodeGrantAuthenticationToken.java | 0 .../java/sample/extgrant/SecurityConfig.java | 0 .../sample/gettingStarted/SecurityConfig.java | 0 .../sample/gettingStarted/application.yml | 0 .../entity/authorization/Authorization.java | 0 .../AuthorizationConsent.java | 0 .../java/sample/jpa/entity/client/Client.java | 0 .../AuthorizationRepository.java | 0 .../AuthorizationConsentRepository.java | 0 .../repository/client/ClientRepository.java | 0 .../JpaOAuth2AuthorizationService.java | 0 .../JpaOAuth2AuthorizationConsentService.java | 0 .../client/JpaRegisteredClientRepository.java | 0 .../main/java/sample/pkce/ClientConfig.java | 0 .../main/java/sample/pkce/SecurityConfig.java | 0 .../main/java/sample/pkce/application.yml | 0 .../sample/socialLogin/SecurityConfig.java | 0 .../java/sample/socialLogin/application.yml | 0 .../EnableUserInfoSecurityConfig.java | 0 .../idtoken/IdTokenCustomizerConfig.java | 0 .../userinfo/idtoken/OidcUserInfoService.java | 0 .../jwt/JwtTokenCustomizerConfig.java | 0 .../jwt/JwtUserInfoMapperSecurityConfig.java | 0 .../src => }/main/resources/application.yml | 0 .../sample/AuthorizationCodeGrantFlow.java | 0 .../sample/DeviceAuthorizationGrantFlow.java | 0 .../sample/extgrant/CustomCodeGrantTests.java | 0 .../gettingStarted/SecurityConfigTests.java | 0 .../test/java/sample/jose/TestJwks.java | 0 .../test/java/sample/jose/TestKeys.java | 0 .../test/java/sample/jpa/JpaTests.java | 0 .../java/sample/pkce/PublicClientTests.java | 0 .../java/sample/test/SpringTestContext.java | 0 .../test/SpringTestContextExtension.java | 0 .../EnableUserInfoSecurityConfigTests.java | 0 .../java/sample/util/RegisteredClients.java | 0 52 files changed, 111 insertions(+), 309 deletions(-) delete mode 100644 docs/framework-docs.gradle create mode 120000 docs/modules/ROOT/examples/docs-src create mode 120000 docs/modules/ROOT/examples/samples delete mode 100644 docs/modules/ROOT/pages/attributes.adoc rename docs/src/{docs/asciidoc/examples/src => }/main/java/sample/extgrant/CustomCodeGrantAuthenticationConverter.java (100%) rename docs/src/{docs/asciidoc/examples/src => }/main/java/sample/extgrant/CustomCodeGrantAuthenticationProvider.java (100%) rename docs/src/{docs/asciidoc/examples/src => }/main/java/sample/extgrant/CustomCodeGrantAuthenticationToken.java (100%) rename docs/src/{docs/asciidoc/examples/src => }/main/java/sample/extgrant/SecurityConfig.java (100%) rename docs/src/{docs/asciidoc/examples/src => }/main/java/sample/gettingStarted/SecurityConfig.java (100%) rename docs/src/{docs/asciidoc/examples/src => }/main/java/sample/gettingStarted/application.yml (100%) rename docs/src/{docs/asciidoc/examples/src => }/main/java/sample/jpa/entity/authorization/Authorization.java (100%) rename docs/src/{docs/asciidoc/examples/src => }/main/java/sample/jpa/entity/authorizationConsent/AuthorizationConsent.java (100%) rename docs/src/{docs/asciidoc/examples/src => }/main/java/sample/jpa/entity/client/Client.java (100%) rename docs/src/{docs/asciidoc/examples/src => }/main/java/sample/jpa/repository/authorization/AuthorizationRepository.java (100%) rename docs/src/{docs/asciidoc/examples/src => }/main/java/sample/jpa/repository/authorizationConsent/AuthorizationConsentRepository.java (100%) rename docs/src/{docs/asciidoc/examples/src => }/main/java/sample/jpa/repository/client/ClientRepository.java (100%) rename docs/src/{docs/asciidoc/examples/src => }/main/java/sample/jpa/service/authorization/JpaOAuth2AuthorizationService.java (100%) rename docs/src/{docs/asciidoc/examples/src => }/main/java/sample/jpa/service/authorizationConsent/JpaOAuth2AuthorizationConsentService.java (100%) rename docs/src/{docs/asciidoc/examples/src => }/main/java/sample/jpa/service/client/JpaRegisteredClientRepository.java (100%) rename docs/src/{docs/asciidoc/examples/src => }/main/java/sample/pkce/ClientConfig.java (100%) rename docs/src/{docs/asciidoc/examples/src => }/main/java/sample/pkce/SecurityConfig.java (100%) rename docs/src/{docs/asciidoc/examples/src => }/main/java/sample/pkce/application.yml (100%) rename docs/src/{docs/asciidoc/examples/src => }/main/java/sample/socialLogin/SecurityConfig.java (100%) rename docs/src/{docs/asciidoc/examples/src => }/main/java/sample/socialLogin/application.yml (100%) rename docs/src/{docs/asciidoc/examples/src => }/main/java/sample/userinfo/EnableUserInfoSecurityConfig.java (100%) rename docs/src/{docs/asciidoc/examples/src => }/main/java/sample/userinfo/idtoken/IdTokenCustomizerConfig.java (100%) rename docs/src/{docs/asciidoc/examples/src => }/main/java/sample/userinfo/idtoken/OidcUserInfoService.java (100%) rename docs/src/{docs/asciidoc/examples/src => }/main/java/sample/userinfo/jwt/JwtTokenCustomizerConfig.java (100%) rename docs/src/{docs/asciidoc/examples/src => }/main/java/sample/userinfo/jwt/JwtUserInfoMapperSecurityConfig.java (100%) rename docs/src/{docs/asciidoc/examples/src => }/main/resources/application.yml (100%) rename docs/src/{docs/asciidoc/examples/src => }/test/java/sample/AuthorizationCodeGrantFlow.java (100%) rename docs/src/{docs/asciidoc/examples/src => }/test/java/sample/DeviceAuthorizationGrantFlow.java (100%) rename docs/src/{docs/asciidoc/examples/src => }/test/java/sample/extgrant/CustomCodeGrantTests.java (100%) rename docs/src/{docs/asciidoc/examples/src => }/test/java/sample/gettingStarted/SecurityConfigTests.java (100%) rename docs/src/{docs/asciidoc/examples/src => }/test/java/sample/jose/TestJwks.java (100%) rename docs/src/{docs/asciidoc/examples/src => }/test/java/sample/jose/TestKeys.java (100%) rename docs/src/{docs/asciidoc/examples/src => }/test/java/sample/jpa/JpaTests.java (100%) rename docs/src/{docs/asciidoc/examples/src => }/test/java/sample/pkce/PublicClientTests.java (100%) rename docs/src/{docs/asciidoc/examples/src => }/test/java/sample/test/SpringTestContext.java (100%) rename docs/src/{docs/asciidoc/examples/src => }/test/java/sample/test/SpringTestContextExtension.java (100%) rename docs/src/{docs/asciidoc/examples/src => }/test/java/sample/userinfo/EnableUserInfoSecurityConfigTests.java (100%) rename docs/src/{docs/asciidoc/examples/src => }/test/java/sample/util/RegisteredClients.java (100%) diff --git a/docs/antora-playbook.yml b/docs/antora-playbook.yml index ffae717c2..9b6c2b3b6 100644 --- a/docs/antora-playbook.yml +++ b/docs/antora-playbook.yml @@ -7,13 +7,13 @@ antora: - require: '@springio/antora-extensions/tabs-migration-extension' unwrap_example_block: always site: - title: Spring Framework Reference - url: https://https://rwinch.github.io/spring-framework/ + title: Spring Authorization Server + url: https://https://rwinch.github.io/spring-authorization-server/ content: sources: - - url: https://github.com/rwinch/spring-framework - branches: ./.. - start_path: framework-docs + - url: .. + branches: antora + start_path: docs worktrees: true asciidoc: attributes: @@ -33,4 +33,4 @@ runtime: ui: bundle: url: https://github.com/spring-io/antora-ui-spring/releases/download/latest/ui-bundle.zip - snapshot: true \ No newline at end of file + snapshot: true diff --git a/docs/antora.yml b/docs/antora.yml index cc7d6eb16..6a162ce66 100644 --- a/docs/antora.yml +++ b/docs/antora.yml @@ -6,7 +6,7 @@ nav: ext: collector: run: - command: gradlew -q -PbuildSrc.skipTests=true "-Dorg.gradle.jvmargs=-Xmx3g -XX:+HeapDumpOnOutOfMemoryError" :spring-boot-project:spring-boot-docs:generateAntoraResources + command: gradlew -q -PbuildSrc.skipTests=true "-Dorg.gradle.jvmargs=-Xmx3g -XX:+HeapDumpOnOutOfMemoryError" :spring-authorization-server-docs:generateAntoraYml local: true scan: dir: ./build/generated-antora-resources @@ -14,19 +14,10 @@ ext: asciidoc: attributes: attribute-missing: 'warn' - # FIXME: the copyright is not removed - # FIXME: The package is not renamed chomp: 'all' - import-java: 'example$docs-src/main/java/org/springframework/docs' - spring-framework-main-code: 'https://github.com/spring-projects/spring-framework/tree/main' - docs-site: 'https://docs.spring.io' - docs-spring: "{docs-site}/spring-framework/docs/{spring-version}" - docs-spring-framework: '{docs_site}/spring-framework/docs/{spring-version}' - api-spring-framework: '{docs-spring-framework}/javadoc-api/org/springframework' - docs-graalvm: 'https://www.graalvm.org/22.3/reference-manual' - docs-spring-boot: '{docs-site}/spring-boot/docs/current/reference' - docs-spring-gemfire: '{docs_site}/spring-gemfire/docs/current/reference' - docs-spring-security: '{docs_site}/spring-security/reference' - gh-rsocket: 'https://github.com/rsocket' - gh-rsocket-extensions: '{gh-rsocket}/rsocket/blob/master/Extensions' - gh-rsocket-java: '{gh-rsocket}/rsocket-java{gh-rsocket}/rsocket-java' \ No newline at end of file + spring-security-reference-base-url: "https://docs.spring.io/spring-security/reference" + spring-security-api-base-url: "https://docs.spring.io/spring-security/site/docs/current/api" + spring-boot-reference-base-url: "https://docs.spring.io/spring-boot/docs/current/reference/html" + examples-dir: example$docs-src + samples-dir: example$samples + docs-java: '{examples-dir}/main/java' diff --git a/docs/framework-docs.gradle b/docs/framework-docs.gradle deleted file mode 100644 index 5c26a91b4..000000000 --- a/docs/framework-docs.gradle +++ /dev/null @@ -1,218 +0,0 @@ -plugins { - id 'kotlin' - id 'io.spring.antora.generate-antora-yml' version '0.0.1' - id 'org.antora' version '1.0.0' -} - -description = "Spring Framework Docs" - -apply from: "${rootDir}/gradle/publications.gradle" - - -antora { - version = '3.2.0-alpha.2' - playbook = 'antora-playbook.yml' -// playbookProvider { -// repository = 'rwinch/spring-framework' -// branch = 'docs-build' -// path = 'lib/antora/templates/per-branch-antora-playbook.yml' -// checkLocalBranch = true -// } - options = ['--clean', '--stacktrace'] - environment = [ - 'ALGOLIA_API_KEY': '82c7ead946afbac3cf98c32446154691', - 'ALGOLIA_APP_ID': '244V8V9FGG', - 'ALGOLIA_INDEX_NAME': 'framework-docs' - ] - dependencies = [ - '@antora/atlas-extension': '1.0.0-alpha.1', - '@antora/collector-extension': '1.0.0-alpha.3', - '@asciidoctor/tabs': '1.0.0-beta.3', - '@opendevise/antora-release-line-extension': '1.0.0-alpha.2', - '@springio/antora-extensions': '1.1.0', - '@springio/asciidoctor-extensions': '1.0.0-alpha.9' - ] -} - - -tasks.named("generateAntoraYml") { - dependsOn dependencyVersions - asciidocAttributes = project.provider( { - return ["spring-version": project.version ] - } ) -} - - -jar { - enabled = false -} - -javadoc { - enabled = false -} - -repositories { - maven { - url "https://repo.spring.io/release" - } -} - -/** - * Produce Javadoc for all Spring Framework modules in "build/docs/javadoc" - */ -task api(type: Javadoc) { - group = "Documentation" - description = "Generates aggregated Javadoc API documentation." - title = "${rootProject.description} ${version} API" - - dependsOn { - moduleProjects.collect { - it.tasks.getByName("jar") - } - } - doFirst { - classpath = files( - // ensure the javadoc process can resolve types compiled from .aj sources - project(":spring-aspects").sourceSets.main.output - ) - classpath += files(moduleProjects.collect { it.sourceSets.main.compileClasspath }) - } - - options { - encoding = "UTF-8" - memberLevel = JavadocMemberLevel.PROTECTED - author = true - header = rootProject.description - use = true - overview = "framework-docs/src/docs/api/overview.html" - splitIndex = true - links(project.ext.javadocLinks) - addBooleanOption('Xdoclint:syntax', true) // only check syntax with doclint - addBooleanOption('Werror', true) // fail build on Javadoc warnings - } - source moduleProjects.collect { project -> - project.sourceSets.main.allJava - } - maxMemory = "1024m" - destinationDir = file("$buildDir/docs/javadoc") -} - -/** - * Produce KDoc for all Spring Framework modules in "build/docs/kdoc" - */ -rootProject.tasks.dokkaHtmlMultiModule.configure { - dependsOn { - tasks.getByName("api") - } - moduleName.set("spring-framework") - outputDirectory.set(project.file("$buildDir/docs/kdoc")) -} - -/** - * Zip all docs (API and reference) into a single archive - */ -task docsZip(type: Zip, dependsOn: ['api', 'antora', rootProject.tasks.dokkaHtmlMultiModule]) { - group = "Distribution" - description = "Builds -${archiveClassifier} archive containing api and reference " + - "for deployment at https://docs.spring.io/spring-framework/docs/." - - archiveBaseName.set("spring-framework") - archiveClassifier.set("docs") - from("src/dist") { - include "changelog.txt" - } - from (api) { - into "javadoc-api" - } - from ("build/site") { - into "reference/html" - } - from (rootProject.tasks.dokkaHtmlMultiModule.outputDirectory) { - into "kdoc-api" - } -} - -/** - * Zip all Spring Framework schemas into a single archive - */ -task schemaZip(type: Zip) { - group = "Distribution" - archiveBaseName.set("spring-framework") - archiveClassifier.set("schema") - description = "Builds -${archiveClassifier} archive containing all " + - "XSDs for deployment at https://springframework.org/schema." - duplicatesStrategy DuplicatesStrategy.EXCLUDE - moduleProjects.each { module -> - def Properties schemas = new Properties(); - - module.sourceSets.main.resources.find { - (it.path.endsWith("META-INF/spring.schemas") || it.path.endsWith("META-INF\\spring.schemas")) - }?.withInputStream { schemas.load(it) } - - for (def key : schemas.keySet()) { - def shortName = key.replaceAll(/http.*schema.(.*).spring-.*/, '$1') - assert shortName != key - File xsdFile = module.sourceSets.main.resources.find { - (it.path.endsWith(schemas.get(key)) || it.path.endsWith(schemas.get(key).replaceAll('\\/','\\\\'))) - } - assert xsdFile != null - into (shortName) { - from xsdFile.path - } - } - } -} - -/** - * Create a distribution zip with everything: - * docs, schemas, jars, source jars, javadoc jars - */ -task distZip(type: Zip, dependsOn: [docsZip, schemaZip]) { - group = "Distribution" - archiveBaseName.set("spring-framework") - archiveClassifier.set("dist") - description = "Builds -${archiveClassifier} archive, containing all jars and docs, " + - "suitable for community download page." - - ext.baseDir = "spring-framework-${project.version}"; - - from("src/docs/dist") { - include "readme.txt" - include "license.txt" - include "notice.txt" - into "${baseDir}" - expand(copyright: new Date().format("yyyy"), version: project.version) - } - - from(zipTree(docsZip.archiveFile)) { - into "${baseDir}/docs" - } - - from(zipTree(schemaZip.archiveFile)) { - into "${baseDir}/schema" - } - - moduleProjects.each { module -> - into ("${baseDir}/libs") { - from module.jar - if (module.tasks.findByPath("sourcesJar")) { - from module.sourcesJar - } - if (module.tasks.findByPath("javadocJar")) { - from module.javadocJar - } - } - } -} - -distZip.mustRunAfter moduleProjects.check - -publishing { - publications { - mavenJava(MavenPublication) { - artifact docsZip - artifact schemaZip - artifact distZip - } - } -} \ No newline at end of file diff --git a/docs/modules/ROOT/examples/docs-src b/docs/modules/ROOT/examples/docs-src new file mode 120000 index 000000000..dabb0e15a --- /dev/null +++ b/docs/modules/ROOT/examples/docs-src @@ -0,0 +1 @@ +../../../src \ No newline at end of file diff --git a/docs/modules/ROOT/examples/samples b/docs/modules/ROOT/examples/samples new file mode 120000 index 000000000..63a8114bd --- /dev/null +++ b/docs/modules/ROOT/examples/samples @@ -0,0 +1 @@ +../../../../samples \ No newline at end of file diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc index fc67e965b..a95b2d0c1 100644 --- a/docs/modules/ROOT/nav.adoc +++ b/docs/modules/ROOT/nav.adoc @@ -2,7 +2,6 @@ * xref:overview.adoc[] * xref:getting-help.adoc[] * xref:getting-started.adoc[] -* xref:attributes.adoc[] * xref:configuration-model.adoc[] * xref:core-model-components.adoc[] * xref:protocol-endpoints.adoc[] diff --git a/docs/modules/ROOT/pages/attributes.adoc b/docs/modules/ROOT/pages/attributes.adoc deleted file mode 100644 index 0b2744c60..000000000 --- a/docs/modules/ROOT/pages/attributes.adoc +++ /dev/null @@ -1,3 +0,0 @@ -:examples-dir: examples -:samples-dir: ../../../../samples -:docs-java: {docdir}/examples/src/main/java diff --git a/docs/modules/ROOT/pages/guides/how-to-ext-grant-type.adoc b/docs/modules/ROOT/pages/guides/how-to-ext-grant-type.adoc index 01a1beadc..9fc199cc6 100644 --- a/docs/modules/ROOT/pages/guides/how-to-ext-grant-type.adoc +++ b/docs/modules/ROOT/pages/guides/how-to-ext-grant-type.adoc @@ -23,7 +23,7 @@ Assuming the absolute URI for the `grant_type` parameter is `urn:ietf:params:oau .AuthenticationConverter [source,java] ---- -include::{examples-dir}/src/main/java/sample/extgrant/CustomCodeGrantAuthenticationConverter.java[] +include::{examples-dir}/main/java/sample/extgrant/CustomCodeGrantAuthenticationConverter.java[] ---- TIP: Click on the "Expand folded text" icon in the code sample above to display the full example. @@ -42,7 +42,7 @@ The following example shows a sample implementation of the `AuthenticationProvid .AuthenticationProvider [source,java] ---- -include::{examples-dir}/src/main/java/sample/extgrant/CustomCodeGrantAuthenticationProvider.java[] +include::{examples-dir}/main/java/sample/extgrant/CustomCodeGrantAuthenticationProvider.java[] ---- NOTE: `CustomCodeGrantAuthenticationProvider` processes `CustomCodeGrantAuthenticationToken`, which is created by xref:guides/how-to-ext-grant-type.adoc#implement-authentication-converter[`CustomCodeGrantAuthenticationConverter`]. @@ -55,7 +55,7 @@ The following example shows how to configure the xref:protocol-endpoints.adoc#oa .SecurityConfig [source,java] ---- -include::{examples-dir}/src/main/java/sample/extgrant/SecurityConfig.java[] +include::{examples-dir}/main/java/sample/extgrant/SecurityConfig.java[] ---- <1> Add the `AuthenticationConverter` to the OAuth2 Token endpoint configuration. diff --git a/docs/modules/ROOT/pages/guides/how-to-jpa.adoc b/docs/modules/ROOT/pages/guides/how-to-jpa.adoc index 4deda07ec..876cf4419 100644 --- a/docs/modules/ROOT/pages/guides/how-to-jpa.adoc +++ b/docs/modules/ROOT/pages/guides/how-to-jpa.adoc @@ -147,7 +147,7 @@ The following listing shows the `Client` entity, which is used to persist inform .Client Entity [source,java] ---- -include::{examples-dir}/src/main/java/sample/jpa/entity/client/Client.java[] +include::{examples-dir}/main/java/sample/jpa/entity/client/Client.java[] ---- [[authorization-entity]] @@ -159,7 +159,7 @@ The following listing shows the `Authorization` entity, which is used to persist .Authorization Entity [source,java] ---- -include::{examples-dir}/src/main/java/sample/jpa/entity/authorization/Authorization.java[] +include::{examples-dir}/main/java/sample/jpa/entity/authorization/Authorization.java[] ---- [[authorization-consent-entity]] @@ -171,7 +171,7 @@ The following listing shows the `AuthorizationConsent` entity, which is used to .Authorization Consent Entity [source,java] ---- -include::{examples-dir}/src/main/java/sample/jpa/entity/authorizationConsent/AuthorizationConsent.java[] +include::{examples-dir}/main/java/sample/jpa/entity/authorizationConsent/AuthorizationConsent.java[] ---- [[create-spring-data-repositories]] @@ -192,7 +192,7 @@ The following listing shows the `ClientRepository`, which is able to find a xref .Client Repository [source,java] ---- -include::{examples-dir}/src/main/java/sample/jpa/repository/client/ClientRepository.java[] +include::{examples-dir}/main/java/sample/jpa/repository/client/ClientRepository.java[] ---- [[authorization-repository]] @@ -205,7 +205,7 @@ It also allows querying a combination of token fields. .Authorization Repository [source,java] ---- -include::{examples-dir}/src/main/java/sample/jpa/repository/authorization/AuthorizationRepository.java[] +include::{examples-dir}/main/java/sample/jpa/repository/authorization/AuthorizationRepository.java[] ---- [[authorization-consent-repository]] @@ -217,7 +217,7 @@ The following listing shows the `AuthorizationConsentRepository`, which is able .Authorization Consent Repository [source,java] ---- -include::{examples-dir}/src/main/java/sample/jpa/repository/authorizationConsent/AuthorizationConsentRepository.java[] +include::{examples-dir}/main/java/sample/jpa/repository/authorizationConsent/AuthorizationConsentRepository.java[] ---- [[implement-core-services]] @@ -243,7 +243,7 @@ The following listing shows the `JpaRegisteredClientRepository`, which uses a xr .`RegisteredClientRepository` Implementation [source,java] ---- -include::{examples-dir}/src/main/java/sample/jpa/service/client/JpaRegisteredClientRepository.java[] +include::{examples-dir}/main/java/sample/jpa/service/client/JpaRegisteredClientRepository.java[] ---- [[authorization-service]] @@ -255,7 +255,7 @@ The following listing shows the `JpaOAuth2AuthorizationService`, which uses an x .`OAuth2AuthorizationService` Implementation [source,java] ---- -include::{examples-dir}/src/main/java/sample/jpa/service/authorization/JpaOAuth2AuthorizationService.java[] +include::{examples-dir}/main/java/sample/jpa/service/authorization/JpaOAuth2AuthorizationService.java[] ---- [[authorization-consent-service]] @@ -267,5 +267,5 @@ The following listing shows the `JpaOAuth2AuthorizationConsentService`, which us .`OAuth2AuthorizationConsentService` Implementation [source,java] ---- -include::{examples-dir}/src/main/java/sample/jpa/service/authorizationConsent/JpaOAuth2AuthorizationConsentService.java[] +include::{examples-dir}/main/java/sample/jpa/service/authorizationConsent/JpaOAuth2AuthorizationConsentService.java[] ---- diff --git a/docs/modules/ROOT/pages/guides/how-to-pkce.adoc b/docs/modules/ROOT/pages/guides/how-to-pkce.adoc index 2aefbac77..84abf82ab 100644 --- a/docs/modules/ROOT/pages/guides/how-to-pkce.adoc +++ b/docs/modules/ROOT/pages/guides/how-to-pkce.adoc @@ -27,7 +27,7 @@ For example, if you have an Angular dev server running locally on port `4200`, y .Enable CORS [source,java] ---- -include::{examples-dir}/src/main/java/sample/pkce/SecurityConfig.java[] +include::{examples-dir}/main/java/sample/pkce/SecurityConfig.java[] ---- TIP: Click on the "Expand folded text" icon in the code sample above to display the full example. @@ -44,13 +44,13 @@ Continuing the xref:guides/how-to-pkce.adoc#enable-cors-configuration[earlier] e .Yaml [source,yaml,role="primary"] ---- -include::{examples-dir}/src/main/java/sample/pkce/application.yml[] +include::{examples-dir}/main/java/sample/pkce/application.yml[] ---- .Java [source,java,role="secondary"] ---- -include::{examples-dir}/src/main/java/sample/pkce/ClientConfig.java[tag=client,indent=0] +include::{examples-dir}/main/java/sample/pkce/ClientConfig.java[tag=client,indent=0] ---- NOTE: The `requireProofKey` setting is helpful in situations where you forget to include the `code_challenge` and `code_challenge_method` query parameters because you will receive an error indicating PKCE is required during the xref:protocol-endpoints.adoc#oauth2-authorization-endpoint[Authorization Request] instead of a general client authentication error during the xref:protocol-endpoints.adoc#oauth2-token-endpoint[Token Request]. diff --git a/docs/modules/ROOT/pages/guides/how-to-social-login.adoc b/docs/modules/ROOT/pages/guides/how-to-social-login.adoc index 3c7942fcf..933a13bb2 100644 --- a/docs/modules/ROOT/pages/guides/how-to-social-login.adoc +++ b/docs/modules/ROOT/pages/guides/how-to-social-login.adoc @@ -83,7 +83,7 @@ Using Okta as an example, configure the following properties: .application.yml [source,yaml] ---- -include::{examples-dir}/src/main/java/sample/socialLogin/application.yml[] +include::{examples-dir}/main/java/sample/socialLogin/application.yml[] ---- NOTE: The `registrationId` in the above example is `my-client`. @@ -104,7 +104,7 @@ Continuing our xref:guides/how-to-social-login.adoc#configure-oauth2-login-okta- .Configure OAuth 2.0 Login [source,java] ---- -include::{examples-dir}/src/main/java/sample/socialLogin/SecurityConfig.java[] +include::{examples-dir}/main/java/sample/socialLogin/SecurityConfig.java[] ---- <1> A Spring Security filter chain for the xref:{docs-dir}/protocol-endpoints.adoc[Protocol Endpoints]. diff --git a/docs/modules/ROOT/pages/guides/how-to-userinfo.adoc b/docs/modules/ROOT/pages/guides/how-to-userinfo.adoc index 0cb153cc4..21166d5af 100644 --- a/docs/modules/ROOT/pages/guides/how-to-userinfo.adoc +++ b/docs/modules/ROOT/pages/guides/how-to-userinfo.adoc @@ -23,7 +23,7 @@ The following listing shows how to enable the {spring-security-reference-base-ur [[sample.userinfo]] [source,java] ---- -include::{examples-dir}/src/main/java/sample/userinfo/EnableUserInfoSecurityConfig.java[] +include::{examples-dir}/main/java/sample/userinfo/EnableUserInfoSecurityConfig.java[] ---- TIP: Click on the "Expand folded text" icon in the code sample above to display the full example. @@ -54,7 +54,7 @@ The following listing shows how to add claims to the `id_token`. [[sample.userinfo.idtoken]] [source,java] ---- -include::{examples-dir}/src/main/java/sample/userinfo/idtoken/IdTokenCustomizerConfig.java[] +include::{examples-dir}/main/java/sample/userinfo/idtoken/IdTokenCustomizerConfig.java[] ---- This configuration provides the following: @@ -66,7 +66,7 @@ The following listing shows a custom service for looking up user info in a domai [source,java] ---- -include::{examples-dir}/src/main/java/sample/userinfo/idtoken/OidcUserInfoService.java[] +include::{examples-dir}/main/java/sample/userinfo/idtoken/OidcUserInfoService.java[] ---- [[customize-user-info-mapper]] @@ -80,7 +80,7 @@ The following listing shows how to use the customization option that is availabl [[sample.userinfo.jwt]] [source,java] ---- -include::{examples-dir}/src/main/java/sample/userinfo/jwt/JwtUserInfoMapperSecurityConfig.java[] +include::{examples-dir}/main/java/sample/userinfo/jwt/JwtUserInfoMapperSecurityConfig.java[] ---- This configuration maps claims from the access token (which is a JWT when using the xref:getting-started.adoc#sample.gettingStarted[Getting Started config]) to populate the user info response and provides the following: @@ -96,7 +96,7 @@ Similar to the xref:guides/how-to-userinfo.adoc#customize-id-token[example shown [source,java] ---- -include::{examples-dir}/src/main/java/sample/userinfo/jwt/JwtTokenCustomizerConfig.java[] +include::{examples-dir}/main/java/sample/userinfo/jwt/JwtTokenCustomizerConfig.java[] ---- Whether you customize the user info response directly or use this example and customize the access token, you can look up information in a database, perform an LDAP query, make a request to another service, or use any other means of obtaining the information you want to be presented in the user info response. diff --git a/docs/spring-authorization-server-docs.gradle b/docs/spring-authorization-server-docs.gradle index b87651844..335d0951d 100644 --- a/docs/spring-authorization-server-docs.gradle +++ b/docs/spring-authorization-server-docs.gradle @@ -1,17 +1,55 @@ plugins { id "io.spring.convention.docs" + id 'io.spring.antora.generate-antora-yml' version '0.0.1' + id 'org.antora' version '1.0.0' + id "java" } -asciidoctor { - attributes([ - "spring-authorization-server-version": project.version, - "spring-security-reference-base-url": "https://docs.spring.io/spring-security/reference", - "spring-security-api-base-url": "https://docs.spring.io/spring-security/site/docs/current/api", - "spring-boot-reference-base-url": "https://docs.spring.io/spring-boot/docs/current/reference/html", - "chomp": "default headers packages", - "toc": "left", - "toclevels": "4" - ]) +group = project.rootProject.group +version = project.rootProject.version +sourceCompatibility = "17" + +antora { +// playbook = 'cached-antora-playbook.yml' +// playbookProvider { +// repository = 'spring-projects/spring-security' +// branch = 'docs-build' +// path = 'lib/antora/templates/per-branch-antora-playbook.yml' +// checkLocalBranch = true +// } + options = [clean: true, fetch: !project.gradle.startParameter.offline, stacktrace: true] + + version = '3.2.0-alpha.2' + playbook = 'antora-playbook.yml' +// playbookProvider { +// repository = 'rwinch/spring-framework' +// branch = 'docs-build' +// path = 'lib/antora/templates/per-branch-antora-playbook.yml' +// checkLocalBranch = true +// } + environment = [ + 'ALGOLIA_API_KEY': '9d489079e5ec46dbb238909fee5c9c29', + 'ALGOLIA_APP_ID': 'WB1FQYI187', + 'ALGOLIA_INDEX_NAME': 'springsecurity', + ] + dependencies = [ + '@antora/atlas-extension': '1.0.0-alpha.1', + '@antora/collector-extension': '1.0.0-alpha.3', + '@asciidoctor/tabs': '1.0.0-beta.3', + '@springio/antora-extensions': '1.4.2', + '@springio/asciidoctor-extensions': '1.0.0-alpha.8', + ] +} + +tasks.named("generateAntoraYml") { + asciidocAttributes = project.provider( { generateAttributes() } ) +} + + +def generateAttributes() { + return [ + "spring-authorization-server-version": project.version + ] } docsZip { @@ -22,3 +60,29 @@ docsZip { into "reference/html" } } + +repositories { + mavenCentral() + maven { url "https://repo.spring.io/milestone" } +} + +dependencies { + implementation(platform("org.springframework.boot:spring-boot-dependencies:3.1.0")) { + exclude group: "org.springframework.security", module: "spring-security-oauth2-authorization-server" + } + implementation platform("org.springframework.security:spring-security-bom:6.1.0") + implementation "org.springframework.boot:spring-boot-starter-web" + implementation "org.springframework.boot:spring-boot-starter-thymeleaf" + implementation "org.springframework.boot:spring-boot-starter-security" + implementation "org.springframework.boot:spring-boot-starter-oauth2-client" + implementation "org.springframework.boot:spring-boot-starter-oauth2-resource-server" + implementation "org.springframework.boot:spring-boot-starter-data-jpa" + implementation project(":spring-security-oauth2-authorization-server") + runtimeOnly "com.h2database:h2" + testImplementation "org.springframework.boot:spring-boot-starter-test" + testImplementation "org.springframework.security:spring-security-test" +} + +tasks.named("test") { + useJUnitPlatform() +} diff --git a/docs/src/docs/asciidoc/examples/spring-authorization-server-docs-examples.gradle b/docs/src/docs/asciidoc/examples/spring-authorization-server-docs-examples.gradle index ba258775c..e69de29bb 100644 --- a/docs/src/docs/asciidoc/examples/spring-authorization-server-docs-examples.gradle +++ b/docs/src/docs/asciidoc/examples/spring-authorization-server-docs-examples.gradle @@ -1,33 +0,0 @@ -plugins { - id "java" -} - -group = project.rootProject.group -version = project.rootProject.version -sourceCompatibility = "17" - -repositories { - mavenCentral() - maven { url "https://repo.spring.io/milestone" } -} - -dependencies { - implementation(platform("org.springframework.boot:spring-boot-dependencies:3.1.0")) { - exclude group: "org.springframework.security", module: "spring-security-oauth2-authorization-server" - } - implementation platform("org.springframework.security:spring-security-bom:6.1.0") - implementation "org.springframework.boot:spring-boot-starter-web" - implementation "org.springframework.boot:spring-boot-starter-thymeleaf" - implementation "org.springframework.boot:spring-boot-starter-security" - implementation "org.springframework.boot:spring-boot-starter-oauth2-client" - implementation "org.springframework.boot:spring-boot-starter-oauth2-resource-server" - implementation "org.springframework.boot:spring-boot-starter-data-jpa" - implementation project(":spring-security-oauth2-authorization-server") - runtimeOnly "com.h2database:h2" - testImplementation "org.springframework.boot:spring-boot-starter-test" - testImplementation "org.springframework.security:spring-security-test" -} - -tasks.named("test") { - useJUnitPlatform() -} diff --git a/docs/src/docs/asciidoc/examples/src/main/java/sample/extgrant/CustomCodeGrantAuthenticationConverter.java b/docs/src/main/java/sample/extgrant/CustomCodeGrantAuthenticationConverter.java similarity index 100% rename from docs/src/docs/asciidoc/examples/src/main/java/sample/extgrant/CustomCodeGrantAuthenticationConverter.java rename to docs/src/main/java/sample/extgrant/CustomCodeGrantAuthenticationConverter.java diff --git a/docs/src/docs/asciidoc/examples/src/main/java/sample/extgrant/CustomCodeGrantAuthenticationProvider.java b/docs/src/main/java/sample/extgrant/CustomCodeGrantAuthenticationProvider.java similarity index 100% rename from docs/src/docs/asciidoc/examples/src/main/java/sample/extgrant/CustomCodeGrantAuthenticationProvider.java rename to docs/src/main/java/sample/extgrant/CustomCodeGrantAuthenticationProvider.java diff --git a/docs/src/docs/asciidoc/examples/src/main/java/sample/extgrant/CustomCodeGrantAuthenticationToken.java b/docs/src/main/java/sample/extgrant/CustomCodeGrantAuthenticationToken.java similarity index 100% rename from docs/src/docs/asciidoc/examples/src/main/java/sample/extgrant/CustomCodeGrantAuthenticationToken.java rename to docs/src/main/java/sample/extgrant/CustomCodeGrantAuthenticationToken.java diff --git a/docs/src/docs/asciidoc/examples/src/main/java/sample/extgrant/SecurityConfig.java b/docs/src/main/java/sample/extgrant/SecurityConfig.java similarity index 100% rename from docs/src/docs/asciidoc/examples/src/main/java/sample/extgrant/SecurityConfig.java rename to docs/src/main/java/sample/extgrant/SecurityConfig.java diff --git a/docs/src/docs/asciidoc/examples/src/main/java/sample/gettingStarted/SecurityConfig.java b/docs/src/main/java/sample/gettingStarted/SecurityConfig.java similarity index 100% rename from docs/src/docs/asciidoc/examples/src/main/java/sample/gettingStarted/SecurityConfig.java rename to docs/src/main/java/sample/gettingStarted/SecurityConfig.java diff --git a/docs/src/docs/asciidoc/examples/src/main/java/sample/gettingStarted/application.yml b/docs/src/main/java/sample/gettingStarted/application.yml similarity index 100% rename from docs/src/docs/asciidoc/examples/src/main/java/sample/gettingStarted/application.yml rename to docs/src/main/java/sample/gettingStarted/application.yml diff --git a/docs/src/docs/asciidoc/examples/src/main/java/sample/jpa/entity/authorization/Authorization.java b/docs/src/main/java/sample/jpa/entity/authorization/Authorization.java similarity index 100% rename from docs/src/docs/asciidoc/examples/src/main/java/sample/jpa/entity/authorization/Authorization.java rename to docs/src/main/java/sample/jpa/entity/authorization/Authorization.java diff --git a/docs/src/docs/asciidoc/examples/src/main/java/sample/jpa/entity/authorizationConsent/AuthorizationConsent.java b/docs/src/main/java/sample/jpa/entity/authorizationConsent/AuthorizationConsent.java similarity index 100% rename from docs/src/docs/asciidoc/examples/src/main/java/sample/jpa/entity/authorizationConsent/AuthorizationConsent.java rename to docs/src/main/java/sample/jpa/entity/authorizationConsent/AuthorizationConsent.java diff --git a/docs/src/docs/asciidoc/examples/src/main/java/sample/jpa/entity/client/Client.java b/docs/src/main/java/sample/jpa/entity/client/Client.java similarity index 100% rename from docs/src/docs/asciidoc/examples/src/main/java/sample/jpa/entity/client/Client.java rename to docs/src/main/java/sample/jpa/entity/client/Client.java diff --git a/docs/src/docs/asciidoc/examples/src/main/java/sample/jpa/repository/authorization/AuthorizationRepository.java b/docs/src/main/java/sample/jpa/repository/authorization/AuthorizationRepository.java similarity index 100% rename from docs/src/docs/asciidoc/examples/src/main/java/sample/jpa/repository/authorization/AuthorizationRepository.java rename to docs/src/main/java/sample/jpa/repository/authorization/AuthorizationRepository.java diff --git a/docs/src/docs/asciidoc/examples/src/main/java/sample/jpa/repository/authorizationConsent/AuthorizationConsentRepository.java b/docs/src/main/java/sample/jpa/repository/authorizationConsent/AuthorizationConsentRepository.java similarity index 100% rename from docs/src/docs/asciidoc/examples/src/main/java/sample/jpa/repository/authorizationConsent/AuthorizationConsentRepository.java rename to docs/src/main/java/sample/jpa/repository/authorizationConsent/AuthorizationConsentRepository.java diff --git a/docs/src/docs/asciidoc/examples/src/main/java/sample/jpa/repository/client/ClientRepository.java b/docs/src/main/java/sample/jpa/repository/client/ClientRepository.java similarity index 100% rename from docs/src/docs/asciidoc/examples/src/main/java/sample/jpa/repository/client/ClientRepository.java rename to docs/src/main/java/sample/jpa/repository/client/ClientRepository.java diff --git a/docs/src/docs/asciidoc/examples/src/main/java/sample/jpa/service/authorization/JpaOAuth2AuthorizationService.java b/docs/src/main/java/sample/jpa/service/authorization/JpaOAuth2AuthorizationService.java similarity index 100% rename from docs/src/docs/asciidoc/examples/src/main/java/sample/jpa/service/authorization/JpaOAuth2AuthorizationService.java rename to docs/src/main/java/sample/jpa/service/authorization/JpaOAuth2AuthorizationService.java diff --git a/docs/src/docs/asciidoc/examples/src/main/java/sample/jpa/service/authorizationConsent/JpaOAuth2AuthorizationConsentService.java b/docs/src/main/java/sample/jpa/service/authorizationConsent/JpaOAuth2AuthorizationConsentService.java similarity index 100% rename from docs/src/docs/asciidoc/examples/src/main/java/sample/jpa/service/authorizationConsent/JpaOAuth2AuthorizationConsentService.java rename to docs/src/main/java/sample/jpa/service/authorizationConsent/JpaOAuth2AuthorizationConsentService.java diff --git a/docs/src/docs/asciidoc/examples/src/main/java/sample/jpa/service/client/JpaRegisteredClientRepository.java b/docs/src/main/java/sample/jpa/service/client/JpaRegisteredClientRepository.java similarity index 100% rename from docs/src/docs/asciidoc/examples/src/main/java/sample/jpa/service/client/JpaRegisteredClientRepository.java rename to docs/src/main/java/sample/jpa/service/client/JpaRegisteredClientRepository.java diff --git a/docs/src/docs/asciidoc/examples/src/main/java/sample/pkce/ClientConfig.java b/docs/src/main/java/sample/pkce/ClientConfig.java similarity index 100% rename from docs/src/docs/asciidoc/examples/src/main/java/sample/pkce/ClientConfig.java rename to docs/src/main/java/sample/pkce/ClientConfig.java diff --git a/docs/src/docs/asciidoc/examples/src/main/java/sample/pkce/SecurityConfig.java b/docs/src/main/java/sample/pkce/SecurityConfig.java similarity index 100% rename from docs/src/docs/asciidoc/examples/src/main/java/sample/pkce/SecurityConfig.java rename to docs/src/main/java/sample/pkce/SecurityConfig.java diff --git a/docs/src/docs/asciidoc/examples/src/main/java/sample/pkce/application.yml b/docs/src/main/java/sample/pkce/application.yml similarity index 100% rename from docs/src/docs/asciidoc/examples/src/main/java/sample/pkce/application.yml rename to docs/src/main/java/sample/pkce/application.yml diff --git a/docs/src/docs/asciidoc/examples/src/main/java/sample/socialLogin/SecurityConfig.java b/docs/src/main/java/sample/socialLogin/SecurityConfig.java similarity index 100% rename from docs/src/docs/asciidoc/examples/src/main/java/sample/socialLogin/SecurityConfig.java rename to docs/src/main/java/sample/socialLogin/SecurityConfig.java diff --git a/docs/src/docs/asciidoc/examples/src/main/java/sample/socialLogin/application.yml b/docs/src/main/java/sample/socialLogin/application.yml similarity index 100% rename from docs/src/docs/asciidoc/examples/src/main/java/sample/socialLogin/application.yml rename to docs/src/main/java/sample/socialLogin/application.yml diff --git a/docs/src/docs/asciidoc/examples/src/main/java/sample/userinfo/EnableUserInfoSecurityConfig.java b/docs/src/main/java/sample/userinfo/EnableUserInfoSecurityConfig.java similarity index 100% rename from docs/src/docs/asciidoc/examples/src/main/java/sample/userinfo/EnableUserInfoSecurityConfig.java rename to docs/src/main/java/sample/userinfo/EnableUserInfoSecurityConfig.java diff --git a/docs/src/docs/asciidoc/examples/src/main/java/sample/userinfo/idtoken/IdTokenCustomizerConfig.java b/docs/src/main/java/sample/userinfo/idtoken/IdTokenCustomizerConfig.java similarity index 100% rename from docs/src/docs/asciidoc/examples/src/main/java/sample/userinfo/idtoken/IdTokenCustomizerConfig.java rename to docs/src/main/java/sample/userinfo/idtoken/IdTokenCustomizerConfig.java diff --git a/docs/src/docs/asciidoc/examples/src/main/java/sample/userinfo/idtoken/OidcUserInfoService.java b/docs/src/main/java/sample/userinfo/idtoken/OidcUserInfoService.java similarity index 100% rename from docs/src/docs/asciidoc/examples/src/main/java/sample/userinfo/idtoken/OidcUserInfoService.java rename to docs/src/main/java/sample/userinfo/idtoken/OidcUserInfoService.java diff --git a/docs/src/docs/asciidoc/examples/src/main/java/sample/userinfo/jwt/JwtTokenCustomizerConfig.java b/docs/src/main/java/sample/userinfo/jwt/JwtTokenCustomizerConfig.java similarity index 100% rename from docs/src/docs/asciidoc/examples/src/main/java/sample/userinfo/jwt/JwtTokenCustomizerConfig.java rename to docs/src/main/java/sample/userinfo/jwt/JwtTokenCustomizerConfig.java diff --git a/docs/src/docs/asciidoc/examples/src/main/java/sample/userinfo/jwt/JwtUserInfoMapperSecurityConfig.java b/docs/src/main/java/sample/userinfo/jwt/JwtUserInfoMapperSecurityConfig.java similarity index 100% rename from docs/src/docs/asciidoc/examples/src/main/java/sample/userinfo/jwt/JwtUserInfoMapperSecurityConfig.java rename to docs/src/main/java/sample/userinfo/jwt/JwtUserInfoMapperSecurityConfig.java diff --git a/docs/src/docs/asciidoc/examples/src/main/resources/application.yml b/docs/src/main/resources/application.yml similarity index 100% rename from docs/src/docs/asciidoc/examples/src/main/resources/application.yml rename to docs/src/main/resources/application.yml diff --git a/docs/src/docs/asciidoc/examples/src/test/java/sample/AuthorizationCodeGrantFlow.java b/docs/src/test/java/sample/AuthorizationCodeGrantFlow.java similarity index 100% rename from docs/src/docs/asciidoc/examples/src/test/java/sample/AuthorizationCodeGrantFlow.java rename to docs/src/test/java/sample/AuthorizationCodeGrantFlow.java diff --git a/docs/src/docs/asciidoc/examples/src/test/java/sample/DeviceAuthorizationGrantFlow.java b/docs/src/test/java/sample/DeviceAuthorizationGrantFlow.java similarity index 100% rename from docs/src/docs/asciidoc/examples/src/test/java/sample/DeviceAuthorizationGrantFlow.java rename to docs/src/test/java/sample/DeviceAuthorizationGrantFlow.java diff --git a/docs/src/docs/asciidoc/examples/src/test/java/sample/extgrant/CustomCodeGrantTests.java b/docs/src/test/java/sample/extgrant/CustomCodeGrantTests.java similarity index 100% rename from docs/src/docs/asciidoc/examples/src/test/java/sample/extgrant/CustomCodeGrantTests.java rename to docs/src/test/java/sample/extgrant/CustomCodeGrantTests.java diff --git a/docs/src/docs/asciidoc/examples/src/test/java/sample/gettingStarted/SecurityConfigTests.java b/docs/src/test/java/sample/gettingStarted/SecurityConfigTests.java similarity index 100% rename from docs/src/docs/asciidoc/examples/src/test/java/sample/gettingStarted/SecurityConfigTests.java rename to docs/src/test/java/sample/gettingStarted/SecurityConfigTests.java diff --git a/docs/src/docs/asciidoc/examples/src/test/java/sample/jose/TestJwks.java b/docs/src/test/java/sample/jose/TestJwks.java similarity index 100% rename from docs/src/docs/asciidoc/examples/src/test/java/sample/jose/TestJwks.java rename to docs/src/test/java/sample/jose/TestJwks.java diff --git a/docs/src/docs/asciidoc/examples/src/test/java/sample/jose/TestKeys.java b/docs/src/test/java/sample/jose/TestKeys.java similarity index 100% rename from docs/src/docs/asciidoc/examples/src/test/java/sample/jose/TestKeys.java rename to docs/src/test/java/sample/jose/TestKeys.java diff --git a/docs/src/docs/asciidoc/examples/src/test/java/sample/jpa/JpaTests.java b/docs/src/test/java/sample/jpa/JpaTests.java similarity index 100% rename from docs/src/docs/asciidoc/examples/src/test/java/sample/jpa/JpaTests.java rename to docs/src/test/java/sample/jpa/JpaTests.java diff --git a/docs/src/docs/asciidoc/examples/src/test/java/sample/pkce/PublicClientTests.java b/docs/src/test/java/sample/pkce/PublicClientTests.java similarity index 100% rename from docs/src/docs/asciidoc/examples/src/test/java/sample/pkce/PublicClientTests.java rename to docs/src/test/java/sample/pkce/PublicClientTests.java diff --git a/docs/src/docs/asciidoc/examples/src/test/java/sample/test/SpringTestContext.java b/docs/src/test/java/sample/test/SpringTestContext.java similarity index 100% rename from docs/src/docs/asciidoc/examples/src/test/java/sample/test/SpringTestContext.java rename to docs/src/test/java/sample/test/SpringTestContext.java diff --git a/docs/src/docs/asciidoc/examples/src/test/java/sample/test/SpringTestContextExtension.java b/docs/src/test/java/sample/test/SpringTestContextExtension.java similarity index 100% rename from docs/src/docs/asciidoc/examples/src/test/java/sample/test/SpringTestContextExtension.java rename to docs/src/test/java/sample/test/SpringTestContextExtension.java diff --git a/docs/src/docs/asciidoc/examples/src/test/java/sample/userinfo/EnableUserInfoSecurityConfigTests.java b/docs/src/test/java/sample/userinfo/EnableUserInfoSecurityConfigTests.java similarity index 100% rename from docs/src/docs/asciidoc/examples/src/test/java/sample/userinfo/EnableUserInfoSecurityConfigTests.java rename to docs/src/test/java/sample/userinfo/EnableUserInfoSecurityConfigTests.java diff --git a/docs/src/docs/asciidoc/examples/src/test/java/sample/util/RegisteredClients.java b/docs/src/test/java/sample/util/RegisteredClients.java similarity index 100% rename from docs/src/docs/asciidoc/examples/src/test/java/sample/util/RegisteredClients.java rename to docs/src/test/java/sample/util/RegisteredClients.java From c1f6652a5d05146b78f1b27d70c89e8c9e8234ff Mon Sep 17 00:00:00 2001 From: Rob Winch Date: Mon, 3 Jul 2023 17:06:20 -0500 Subject: [PATCH 08/12] Antora component name framework -> authorization-server --- docs/antora-playbook.yml | 3 +++ docs/antora.yml | 4 ++-- 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/antora-playbook.yml b/docs/antora-playbook.yml index 9b6c2b3b6..c04d9db43 100644 --- a/docs/antora-playbook.yml +++ b/docs/antora-playbook.yml @@ -6,6 +6,9 @@ antora: - '@antora/collector-extension' - require: '@springio/antora-extensions/tabs-migration-extension' unwrap_example_block: always + - require: '@springio/antora-extensions/root-component-extension' + root_component_name: 'authorization-server' + - '@antora/atlas-extension' site: title: Spring Authorization Server url: https://https://rwinch.github.io/spring-authorization-server/ diff --git a/docs/antora.yml b/docs/antora.yml index 6a162ce66..f1d1424ba 100644 --- a/docs/antora.yml +++ b/docs/antora.yml @@ -1,6 +1,6 @@ -name: framework +name: authorization-server version: true -title: Spring Framework Documentation +title: Spring Authorization Server nav: - modules/ROOT/nav.adoc ext: From 3507b3502ce18e55bc8633427165af2c657c681f Mon Sep 17 00:00:00 2001 From: Rob Winch Date: Mon, 3 Jul 2023 17:06:48 -0500 Subject: [PATCH 09/12] Restructure Overview --- docs/modules/ROOT/nav.adoc | 2 - .../modules/ROOT/pages/guides/attributes.adoc | 3 - docs/modules/ROOT/pages/index.adoc | 97 ++++++++++++++++++- docs/modules/ROOT/pages/overview.adoc | 94 ------------------ docs/spring-authorization-server-docs.gradle | 35 ++----- 5 files changed, 102 insertions(+), 129 deletions(-) delete mode 100644 docs/modules/ROOT/pages/guides/attributes.adoc delete mode 100644 docs/modules/ROOT/pages/overview.adoc diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc index a95b2d0c1..7847ced05 100644 --- a/docs/modules/ROOT/nav.adoc +++ b/docs/modules/ROOT/nav.adoc @@ -1,12 +1,10 @@ * xref:index.adoc[] -* xref:overview.adoc[] * xref:getting-help.adoc[] * xref:getting-started.adoc[] * xref:configuration-model.adoc[] * xref:core-model-components.adoc[] * xref:protocol-endpoints.adoc[] * xref:how-to.adoc[] -** xref:guides/attributes.adoc[] ** xref:guides/how-to-ext-grant-type.adoc[] ** xref:guides/how-to-jpa.adoc[] ** xref:guides/how-to-pkce.adoc[] diff --git a/docs/modules/ROOT/pages/guides/attributes.adoc b/docs/modules/ROOT/pages/guides/attributes.adoc deleted file mode 100644 index 4f8e9c7e7..000000000 --- a/docs/modules/ROOT/pages/guides/attributes.adoc +++ /dev/null @@ -1,3 +0,0 @@ -:examples-dir: ../examples -:samples-dir: ../../../../../samples -:docs-java: {docdir}/examples/src/main/java diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc index 1aec0a189..dba5ab854 100644 --- a/docs/modules/ROOT/pages/index.adoc +++ b/docs/modules/ROOT/pages/index.adoc @@ -1,16 +1,109 @@ [[top]] -= Spring Authorization Server Reference += Overview :page-section-summary-toc: 1 Joe Grandja, Steve Riesenberg v{spring-authorization-server-version} :docinfo: private-footer :nofooter: +This site contains reference documentation and how-to guides for Spring Authorization Server. + [horizontal] -xref:overview.adoc[Overview] :: Introduction and feature list +xref:index.adoc#introducing-spring-authorization-server[Introduction] :: Introduction and feature list xref:getting-help.adoc[Getting Help] :: Links to samples, questions and issues xref:getting-started.adoc[Getting Started] :: System requirements, dependencies and developing your first application xref:configuration-model.adoc[Configuration Model] :: Default configuration and customizing the configuration xref:core-model-components.adoc[Core Model / Components] :: Core domain model and component interfaces xref:protocol-endpoints.adoc[Protocol Endpoints] :: OAuth2 and OpenID Connect 1.0 protocol endpoint implementations xref:how-to.adoc[How-to Guides] :: Guides to get the most from Spring Authorization Server + + +[[introducing-spring-authorization-server]] +== Introducing Spring Authorization Server + +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. +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. + +[[feature-list]] +== Feature List + +Spring Authorization Server supports the following features: + +[cols="2a,4a,6a"] +|=== +|Category |Feature |Related specifications + +|xref:protocol-endpoints.adoc#oauth2-token-endpoint[Authorization Grant] +| +* Authorization Code +** xref:protocol-endpoints.adoc#oauth2-authorization-endpoint[User Consent] +* Client Credentials +* Refresh Token +* Device Code +** xref:protocol-endpoints.adoc#oauth2-device-verification-endpoint[User Consent] +| +* The OAuth 2.1 Authorization Framework (https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-07[draft]) +** https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-07#section-4.1[Authorization Code Grant] +** https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-07#section-4.2[Client Credentials Grant] +** https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-07#section-4.3[Refresh Token Grant] +* OpenID Connect Core 1.0 (https://openid.net/specs/openid-connect-core-1_0.html[spec]) +** https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth[Authorization Code Flow] +* OAuth 2.0 Device Authorization Grant +(https://tools.ietf.org/html/rfc8628[spec]) +** https://tools.ietf.org/html/rfc8628#section-3[Device Flow] + +|xref:core-model-components.adoc#oauth2-token-generator[Token Formats] +| +* Self-contained (JWT) +* Reference (Opaque) +| +* JSON Web Token (JWT) (https://tools.ietf.org/html/rfc7519[RFC 7519]) +* JSON Web Signature (JWS) (https://tools.ietf.org/html/rfc7515[RFC 7515]) + +|xref:configuration-model.adoc#configuring-client-authentication[Client Authentication] +| +* `client_secret_basic` +* `client_secret_post` +* `client_secret_jwt` +* `private_key_jwt` +* `none` (public clients) +| +* The OAuth 2.1 Authorization Framework (https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-07#section-2.4[Client Authentication]) +* JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication (https://tools.ietf.org/html/rfc7523[RFC 7523]) +* Proof Key for Code Exchange by OAuth Public Clients (PKCE) (https://tools.ietf.org/html/rfc7636[RFC 7636]) + +|xref:protocol-endpoints.adoc[Protocol Endpoints] +| +* xref:protocol-endpoints.adoc#oauth2-authorization-endpoint[OAuth2 Authorization Endpoint] +* xref:protocol-endpoints.adoc#oauth2-device-authorization-endpoint[OAuth2 Device Authorization Endpoint] +* xref:protocol-endpoints.adoc#oauth2-device-verification-endpoint[OAuth2 Device Verification Endpoint] +* xref:protocol-endpoints.adoc#oauth2-token-endpoint[OAuth2 Token Endpoint] +* xref:protocol-endpoints.adoc#oauth2-token-introspection-endpoint[OAuth2 Token Introspection Endpoint] +* xref:protocol-endpoints.adoc#oauth2-token-revocation-endpoint[OAuth2 Token Revocation Endpoint] +* xref:protocol-endpoints.adoc#oauth2-authorization-server-metadata-endpoint[OAuth2 Authorization Server Metadata Endpoint] +* xref:protocol-endpoints.adoc#jwk-set-endpoint[JWK Set Endpoint] +* xref:protocol-endpoints.adoc#oidc-provider-configuration-endpoint[OpenID Connect 1.0 Provider Configuration Endpoint] +* xref:protocol-endpoints.adoc#oidc-logout-endpoint[OpenID Connect 1.0 Logout Endpoint] +* xref:protocol-endpoints.adoc#oidc-user-info-endpoint[OpenID Connect 1.0 UserInfo Endpoint] +* xref:protocol-endpoints.adoc#oidc-client-registration-endpoint[OpenID Connect 1.0 Client Registration Endpoint] +| +* The OAuth 2.1 Authorization Framework (https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-07[draft]) +** https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-07#section-3.1[Authorization Endpoint] +** https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-07#section-3.2[Token Endpoint] +* OAuth 2.0 Device Authorization Grant (https://tools.ietf.org/html/rfc8628[RFC 8628]) +** https://tools.ietf.org/html/rfc8628#section-3.1[Device Authorization Endpoint] +** https://tools.ietf.org/html/rfc8628#section-3.3[Device Verification Endpoint] +* OAuth 2.0 Token Introspection (https://tools.ietf.org/html/rfc7662[RFC 7662]) +* OAuth 2.0 Token Revocation (https://tools.ietf.org/html/rfc7009[RFC 7009]) +* OAuth 2.0 Authorization Server Metadata (https://tools.ietf.org/html/rfc8414[RFC 8414]) +* JSON Web Key (JWK) (https://tools.ietf.org/html/rfc7517[RFC 7517]) +* OpenID Connect Discovery 1.0 (https://openid.net/specs/openid-connect-discovery-1_0.html[spec]) +** https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfig[Provider Configuration Endpoint] +* OpenID Connect RP-Initiated Logout 1.0 (https://openid.net/specs/openid-connect-rpinitiated-1_0.html[spec]) +** https://openid.net/specs/openid-connect-rpinitiated-1_0.html#RPLogout[Logout Endpoint] +* OpenID Connect Core 1.0 (https://openid.net/specs/openid-connect-core-1_0.html[spec]) +** https://openid.net/specs/openid-connect-core-1_0.html#UserInfo[UserInfo Endpoint] +* OpenID Connect Dynamic Client Registration 1.0 (https://openid.net/specs/openid-connect-registration-1_0.html[spec]) +** https://openid.net/specs/openid-connect-registration-1_0.html#ClientRegistration[Client Registration Endpoint] +** https://openid.net/specs/openid-connect-registration-1_0.html#ClientConfigurationEndpoint[Client Configuration Endpoint] +|=== diff --git a/docs/modules/ROOT/pages/overview.adoc b/docs/modules/ROOT/pages/overview.adoc deleted file mode 100644 index 2853bb4a3..000000000 --- a/docs/modules/ROOT/pages/overview.adoc +++ /dev/null @@ -1,94 +0,0 @@ -[[overview]] -= Overview - -This site contains reference documentation and how-to guides for Spring Authorization Server. - -[[introducing-spring-authorization-server]] -== Introducing Spring Authorization Server - -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. -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. - -[[feature-list]] -== Feature List - -Spring Authorization Server supports the following features: - -[cols="2a,4a,6a"] -|=== -|Category |Feature |Related specifications - -|xref:protocol-endpoints.adoc#oauth2-token-endpoint[Authorization Grant] -| -* Authorization Code -** xref:protocol-endpoints.adoc#oauth2-authorization-endpoint[User Consent] -* Client Credentials -* Refresh Token -* Device Code -** xref:protocol-endpoints.adoc#oauth2-device-verification-endpoint[User Consent] -| -* The OAuth 2.1 Authorization Framework (https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-07[draft]) -** https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-07#section-4.1[Authorization Code Grant] -** https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-07#section-4.2[Client Credentials Grant] -** https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-07#section-4.3[Refresh Token Grant] -* OpenID Connect Core 1.0 (https://openid.net/specs/openid-connect-core-1_0.html[spec]) -** https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth[Authorization Code Flow] -* OAuth 2.0 Device Authorization Grant -(https://tools.ietf.org/html/rfc8628[spec]) -** https://tools.ietf.org/html/rfc8628#section-3[Device Flow] - -|xref:core-model-components.adoc#oauth2-token-generator[Token Formats] -| -* Self-contained (JWT) -* Reference (Opaque) -| -* JSON Web Token (JWT) (https://tools.ietf.org/html/rfc7519[RFC 7519]) -* JSON Web Signature (JWS) (https://tools.ietf.org/html/rfc7515[RFC 7515]) - -|xref:configuration-model.adoc#configuring-client-authentication[Client Authentication] -| -* `client_secret_basic` -* `client_secret_post` -* `client_secret_jwt` -* `private_key_jwt` -* `none` (public clients) -| -* The OAuth 2.1 Authorization Framework (https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-07#section-2.4[Client Authentication]) -* JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication (https://tools.ietf.org/html/rfc7523[RFC 7523]) -* Proof Key for Code Exchange by OAuth Public Clients (PKCE) (https://tools.ietf.org/html/rfc7636[RFC 7636]) - -|xref:protocol-endpoints.adoc[Protocol Endpoints] -| -* xref:protocol-endpoints.adoc#oauth2-authorization-endpoint[OAuth2 Authorization Endpoint] -* xref:protocol-endpoints.adoc#oauth2-device-authorization-endpoint[OAuth2 Device Authorization Endpoint] -* xref:protocol-endpoints.adoc#oauth2-device-verification-endpoint[OAuth2 Device Verification Endpoint] -* xref:protocol-endpoints.adoc#oauth2-token-endpoint[OAuth2 Token Endpoint] -* xref:protocol-endpoints.adoc#oauth2-token-introspection-endpoint[OAuth2 Token Introspection Endpoint] -* xref:protocol-endpoints.adoc#oauth2-token-revocation-endpoint[OAuth2 Token Revocation Endpoint] -* xref:protocol-endpoints.adoc#oauth2-authorization-server-metadata-endpoint[OAuth2 Authorization Server Metadata Endpoint] -* xref:protocol-endpoints.adoc#jwk-set-endpoint[JWK Set Endpoint] -* xref:protocol-endpoints.adoc#oidc-provider-configuration-endpoint[OpenID Connect 1.0 Provider Configuration Endpoint] -* xref:protocol-endpoints.adoc#oidc-logout-endpoint[OpenID Connect 1.0 Logout Endpoint] -* xref:protocol-endpoints.adoc#oidc-user-info-endpoint[OpenID Connect 1.0 UserInfo Endpoint] -* xref:protocol-endpoints.adoc#oidc-client-registration-endpoint[OpenID Connect 1.0 Client Registration Endpoint] -| -* The OAuth 2.1 Authorization Framework (https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-07[draft]) -** https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-07#section-3.1[Authorization Endpoint] -** https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-07#section-3.2[Token Endpoint] -* OAuth 2.0 Device Authorization Grant (https://tools.ietf.org/html/rfc8628[RFC 8628]) -** https://tools.ietf.org/html/rfc8628#section-3.1[Device Authorization Endpoint] -** https://tools.ietf.org/html/rfc8628#section-3.3[Device Verification Endpoint] -* OAuth 2.0 Token Introspection (https://tools.ietf.org/html/rfc7662[RFC 7662]) -* OAuth 2.0 Token Revocation (https://tools.ietf.org/html/rfc7009[RFC 7009]) -* OAuth 2.0 Authorization Server Metadata (https://tools.ietf.org/html/rfc8414[RFC 8414]) -* JSON Web Key (JWK) (https://tools.ietf.org/html/rfc7517[RFC 7517]) -* OpenID Connect Discovery 1.0 (https://openid.net/specs/openid-connect-discovery-1_0.html[spec]) -** https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfig[Provider Configuration Endpoint] -* OpenID Connect RP-Initiated Logout 1.0 (https://openid.net/specs/openid-connect-rpinitiated-1_0.html[spec]) -** https://openid.net/specs/openid-connect-rpinitiated-1_0.html#RPLogout[Logout Endpoint] -* OpenID Connect Core 1.0 (https://openid.net/specs/openid-connect-core-1_0.html[spec]) -** https://openid.net/specs/openid-connect-core-1_0.html#UserInfo[UserInfo Endpoint] -* OpenID Connect Dynamic Client Registration 1.0 (https://openid.net/specs/openid-connect-registration-1_0.html[spec]) -** https://openid.net/specs/openid-connect-registration-1_0.html#ClientRegistration[Client Registration Endpoint] -** https://openid.net/specs/openid-connect-registration-1_0.html#ClientConfigurationEndpoint[Client Configuration Endpoint] -|=== diff --git a/docs/spring-authorization-server-docs.gradle b/docs/spring-authorization-server-docs.gradle index 335d0951d..76c4969c0 100644 --- a/docs/spring-authorization-server-docs.gradle +++ b/docs/spring-authorization-server-docs.gradle @@ -10,35 +10,14 @@ version = project.rootProject.version sourceCompatibility = "17" antora { -// playbook = 'cached-antora-playbook.yml' -// playbookProvider { -// repository = 'spring-projects/spring-security' -// branch = 'docs-build' -// path = 'lib/antora/templates/per-branch-antora-playbook.yml' -// checkLocalBranch = true -// } + playbook = 'cached-antora-playbook.yml' + playbookProvider { + repository = 'rwinch/spring-authorization-server' + branch = 'docs-build' + path = 'lib/antora/templates/per-branch-antora-playbook.yml' + checkLocalBranch = true + } options = [clean: true, fetch: !project.gradle.startParameter.offline, stacktrace: true] - - version = '3.2.0-alpha.2' - playbook = 'antora-playbook.yml' -// playbookProvider { -// repository = 'rwinch/spring-framework' -// branch = 'docs-build' -// path = 'lib/antora/templates/per-branch-antora-playbook.yml' -// checkLocalBranch = true -// } - environment = [ - 'ALGOLIA_API_KEY': '9d489079e5ec46dbb238909fee5c9c29', - 'ALGOLIA_APP_ID': 'WB1FQYI187', - 'ALGOLIA_INDEX_NAME': 'springsecurity', - ] - dependencies = [ - '@antora/atlas-extension': '1.0.0-alpha.1', - '@antora/collector-extension': '1.0.0-alpha.3', - '@asciidoctor/tabs': '1.0.0-beta.3', - '@springio/antora-extensions': '1.4.2', - '@springio/asciidoctor-extensions': '1.0.0-alpha.8', - ] } tasks.named("generateAntoraYml") { From fe5f7c9e431d9226aa05ec1d285977c9cff976eb Mon Sep 17 00:00:00 2001 From: Rob Winch Date: Mon, 3 Jul 2023 17:34:08 -0500 Subject: [PATCH 10/12] Migrate tabs --- docs/modules/ROOT/pages/getting-started.adoc | 18 ++++++++++++++---- .../modules/ROOT/pages/guides/how-to-pkce.adoc | 9 +++++++-- .../ROOT/pages/guides/how-to-social-login.adoc | 9 +++++++-- 3 files changed, 28 insertions(+), 8 deletions(-) diff --git a/docs/modules/ROOT/pages/getting-started.adoc b/docs/modules/ROOT/pages/getting-started.adoc index b36a08d88..d3bc464fa 100644 --- a/docs/modules/ROOT/pages/getting-started.adoc +++ b/docs/modules/ROOT/pages/getting-started.adoc @@ -18,8 +18,11 @@ The easiest way to begin using Spring Authorization Server is by creating a http 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. Then add Spring Boot's starter for Spring Authorization Server as a dependency: +[tabs] +====== +Maven:: ++ [[spring-boot-maven-dependency]] -.Maven [source,xml,role="primary",subs="attributes,verbatim"] ---- @@ -28,19 +31,24 @@ Then add Spring Boot's starter for Spring Authorization Server as a dependency: ---- +Gradle:: ++ [[spring-boot-gradle-dependency]] -.Gradle [source,gradle,role="secondary",subs="attributes,verbatim"] ---- implementation "org.springframework.boot:spring-boot-starter-oauth2-authorization-server" ---- +====== 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. Alternatively, you can add Spring Authorization Server without Spring Boot using the following example: +[tabs] +====== +Maven:: ++ [[maven-dependency]] -.Maven [source,xml,role="primary",subs="attributes,verbatim"] ---- @@ -50,12 +58,14 @@ Alternatively, you can add Spring Authorization Server without Spring Boot using ---- +Gradle:: ++ [[gradle-dependency]] -.Gradle [source,gradle,role="secondary",subs="attributes,verbatim"] ---- implementation "org.springframework.security:spring-security-oauth2-authorization-server:{spring-authorization-server-version}" ---- +====== [[developing-your-first-application]] == Developing Your First Application diff --git a/docs/modules/ROOT/pages/guides/how-to-pkce.adoc b/docs/modules/ROOT/pages/guides/how-to-pkce.adoc index 84abf82ab..520c7ad20 100644 --- a/docs/modules/ROOT/pages/guides/how-to-pkce.adoc +++ b/docs/modules/ROOT/pages/guides/how-to-pkce.adoc @@ -40,18 +40,23 @@ Public clients should be required to use https://datatracker.ietf.org/doc/html/r Continuing the xref:guides/how-to-pkce.adoc#enable-cors-configuration[earlier] example, you can configure Spring Authorization Server to support a public client using the Client Authentication Method `none` and require PKCE as in the following example: +[tabs] +====== +Yaml:: ++ [[configure-public-client-example]] -.Yaml [source,yaml,role="primary"] ---- include::{examples-dir}/main/java/sample/pkce/application.yml[] ---- -.Java +Java:: ++ [source,java,role="secondary"] ---- include::{examples-dir}/main/java/sample/pkce/ClientConfig.java[tag=client,indent=0] ---- +====== NOTE: The `requireProofKey` setting is helpful in situations where you forget to include the `code_challenge` and `code_challenge_method` query parameters because you will receive an error indicating PKCE is required during the xref:protocol-endpoints.adoc#oauth2-authorization-endpoint[Authorization Request] instead of a general client authentication error during the xref:protocol-endpoints.adoc#oauth2-token-endpoint[Token Request]. diff --git a/docs/modules/ROOT/pages/guides/how-to-social-login.adoc b/docs/modules/ROOT/pages/guides/how-to-social-login.adoc index 933a13bb2..247b15987 100644 --- a/docs/modules/ROOT/pages/guides/how-to-social-login.adoc +++ b/docs/modules/ROOT/pages/guides/how-to-social-login.adoc @@ -56,8 +56,11 @@ Once you've xref:guides/how-to-social-login.adoc#register-social-login-provider[ First, add the following dependency: +[tabs] +====== +Maven:: ++ [[configure-oauth2-login-maven-dependency]] -.Maven [source,xml,role="primary",subs="attributes,verbatim"] ---- @@ -66,12 +69,14 @@ First, add the following dependency: ---- +Gradle:: ++ [[configure-oauth2-login-gradle-dependency]] -.Gradle [source,gradle,role="secondary",subs="attributes,verbatim"] ---- implementation "org.springframework.boot:spring-boot-starter-oauth2-client" ---- +====== [[configure-oauth2-login-client-registration]] === Register a Client From ebaba6f2d9d57adfbfdd979199b19bd86171dffc Mon Sep 17 00:00:00 2001 From: Rob Winch Date: Mon, 10 Jul 2023 12:00:13 -0500 Subject: [PATCH 11/12] Use package naming conventions of lowercase This ensures the samples work with the code chomp extension --- docs/modules/ROOT/pages/getting-started.adoc | 4 ++-- docs/modules/ROOT/pages/guides/how-to-social-login.adoc | 4 ++-- .../{gettingStarted => gettingstarted}/SecurityConfig.java | 2 +- .../sample/{gettingStarted => gettingstarted}/application.yml | 0 .../sample/{socialLogin => sociallogin}/SecurityConfig.java | 2 +- .../java/sample/{socialLogin => sociallogin}/application.yml | 0 .../SecurityConfigTests.java | 2 +- 7 files changed, 7 insertions(+), 7 deletions(-) rename docs/src/main/java/sample/{gettingStarted => gettingstarted}/SecurityConfig.java (99%) rename docs/src/main/java/sample/{gettingStarted => gettingstarted}/application.yml (100%) rename docs/src/main/java/sample/{socialLogin => sociallogin}/SecurityConfig.java (99%) rename docs/src/main/java/sample/{socialLogin => sociallogin}/application.yml (100%) rename docs/src/test/java/sample/{gettingStarted => gettingstarted}/SecurityConfigTests.java (99%) diff --git a/docs/modules/ROOT/pages/getting-started.adoc b/docs/modules/ROOT/pages/getting-started.adoc index d3bc464fa..75ec6bc4e 100644 --- a/docs/modules/ROOT/pages/getting-started.adoc +++ b/docs/modules/ROOT/pages/getting-started.adoc @@ -76,7 +76,7 @@ To get started, you need the minimum required components defined as a `@Bean`. W .application.yml [source,yaml] ---- -include::{docs-java}/sample/gettingStarted/application.yml[] +include::{docs-java}/sample/gettingstarted/application.yml[] ---- 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. @@ -92,7 +92,7 @@ These components can be defined as follows: .SecurityConfig.java [source,java] ---- -include::{docs-java}/sample/gettingStarted/SecurityConfig.java[] +include::{docs-java}/sample/gettingstarted/SecurityConfig.java[] ---- This is a minimal configuration for getting started quickly. To understand what each component is used for, see the following descriptions: diff --git a/docs/modules/ROOT/pages/guides/how-to-social-login.adoc b/docs/modules/ROOT/pages/guides/how-to-social-login.adoc index 247b15987..d66bb16a7 100644 --- a/docs/modules/ROOT/pages/guides/how-to-social-login.adoc +++ b/docs/modules/ROOT/pages/guides/how-to-social-login.adoc @@ -88,7 +88,7 @@ Using Okta as an example, configure the following properties: .application.yml [source,yaml] ---- -include::{examples-dir}/main/java/sample/socialLogin/application.yml[] +include::{examples-dir}/main/java/sample/sociallogin/application.yml[] ---- NOTE: The `registrationId` in the above example is `my-client`. @@ -109,7 +109,7 @@ Continuing our xref:guides/how-to-social-login.adoc#configure-oauth2-login-okta- .Configure OAuth 2.0 Login [source,java] ---- -include::{examples-dir}/main/java/sample/socialLogin/SecurityConfig.java[] +include::{examples-dir}/main/java/sample/sociallogin/SecurityConfig.java[] ---- <1> A Spring Security filter chain for the xref:{docs-dir}/protocol-endpoints.adoc[Protocol Endpoints]. diff --git a/docs/src/main/java/sample/gettingStarted/SecurityConfig.java b/docs/src/main/java/sample/gettingstarted/SecurityConfig.java similarity index 99% rename from docs/src/main/java/sample/gettingStarted/SecurityConfig.java rename to docs/src/main/java/sample/gettingstarted/SecurityConfig.java index 0b7b65caf..c1d08b9ad 100644 --- a/docs/src/main/java/sample/gettingStarted/SecurityConfig.java +++ b/docs/src/main/java/sample/gettingstarted/SecurityConfig.java @@ -13,7 +13,7 @@ * See the License for the specific language governing permissions and * limitations under the License. */ -package sample.gettingStarted; +package sample.gettingstarted; import java.security.KeyPair; import java.security.KeyPairGenerator; diff --git a/docs/src/main/java/sample/gettingStarted/application.yml b/docs/src/main/java/sample/gettingstarted/application.yml similarity index 100% rename from docs/src/main/java/sample/gettingStarted/application.yml rename to docs/src/main/java/sample/gettingstarted/application.yml diff --git a/docs/src/main/java/sample/socialLogin/SecurityConfig.java b/docs/src/main/java/sample/sociallogin/SecurityConfig.java similarity index 99% rename from docs/src/main/java/sample/socialLogin/SecurityConfig.java rename to docs/src/main/java/sample/sociallogin/SecurityConfig.java index 7583ae0bb..3f466568c 100644 --- a/docs/src/main/java/sample/socialLogin/SecurityConfig.java +++ b/docs/src/main/java/sample/sociallogin/SecurityConfig.java @@ -13,7 +13,7 @@ * See the License for the specific language governing permissions and * limitations under the License. */ -package sample.socialLogin; +package sample.sociallogin; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; diff --git a/docs/src/main/java/sample/socialLogin/application.yml b/docs/src/main/java/sample/sociallogin/application.yml similarity index 100% rename from docs/src/main/java/sample/socialLogin/application.yml rename to docs/src/main/java/sample/sociallogin/application.yml diff --git a/docs/src/test/java/sample/gettingStarted/SecurityConfigTests.java b/docs/src/test/java/sample/gettingstarted/SecurityConfigTests.java similarity index 99% rename from docs/src/test/java/sample/gettingStarted/SecurityConfigTests.java rename to docs/src/test/java/sample/gettingstarted/SecurityConfigTests.java index cf827c3ad..86dc7c6aa 100644 --- a/docs/src/test/java/sample/gettingStarted/SecurityConfigTests.java +++ b/docs/src/test/java/sample/gettingstarted/SecurityConfigTests.java @@ -13,7 +13,7 @@ * See the License for the specific language governing permissions and * limitations under the License. */ -package sample.gettingStarted; +package sample.gettingstarted; import java.util.Map; From d952b1c95cc38d08a9d55e53452651724b627c8f Mon Sep 17 00:00:00 2001 From: Rob Winch Date: Mon, 10 Jul 2023 12:32:51 -0500 Subject: [PATCH 12/12] Ignore cached-antora-playbook.yml --- .gitignore | 1 + 1 file changed, 1 insertion(+) diff --git a/.gitignore b/.gitignore index 74d8a07a6..a452c6129 100644 --- a/.gitignore +++ b/.gitignore @@ -37,3 +37,4 @@ out/ ### Mac ### .DS_Store +cached-antora-playbook.yml