Add reference documentation

[jgrandja]

This issue will serve to provide a content outline for the reference documentation.

Our goal is to avoid the "fluff" and only write content that will be valuable to our users and community. The only way to achieve this is too directly involve our users in driving out the content they want to see.

We'll be prioritizing the "How-to" Guides based on upvotes. Please log an issue for a new How-to Guide if it's not already listed.

We also encourage users to log an issue recommending new content that is not already listed in the proposed content outline.

[jgrandja]

Content Outline ("Draft")

1. Overview
   • Introducing Spring Authorization Server
   • Feature List
2. Getting Help
3. Getting Started
   • System Requirements
   • Installing Spring Authorization Server
   • Developing Your First Spring Authorization Server Application
4. Configuration Model
   • OAuth2AuthorizationServerConfigurer
   • OAuth2AuthorizationServerConfiguration
   • ProviderSettings / ProviderContext
5. Core Model / Components
   • RegisteredClientRepository / RegisteredClient
   • OAuth2AuthorizationService / OAuth2Authorization
   • OAuth2AuthorizationConsentService / OAuth2AuthorizationConsent
   • OAuth2TokenGenerator
   • OAuth2TokenCustomizer
6. Protocol Endpoints
   • OAuth 2.0 Authorization Endpoint
   • OAuth 2.0 Token Endpoint
   • OAuth 2.0 Token Introspection Endpoint
   • OAuth 2.0 Token Revocation Endpoint
   • OAuth 2.0 Authorization Server Metadata Endpoint
   • JWK Set Endpoint
   • OpenID Connect 1.0 Provider Configuration Endpoint
   • OpenID Connect 1.0 UserInfo Endpoint
   • OpenID Connect 1.0 Client Registration Endpoint
7. "How-to" Guides
   • Obtain an access token using a specific grant_type:
     • authorization_code
     • client_credentials
     • refresh_token
   • Customize form based login
   • Authenticate a user with two-factor authentication
   • Customize the user consent page
   • Authenticate using OpenID Connect 1.0 authorization_code flow
   • Customize the OpenID Connect 1.0 UserInfo response
   • Authenticate using social login, e.g. Google
   • Authenticate a user in a Single Page Application with PKCE
   • Customize client authentication for specific authentication methods
   • Handle errors and customize the OAuth 2.0 Error response
   • Authorize an access token containing custom authorities, e.g. roles, groups, permissions, etc.
     • Customize the headers / claims in a JWT
   • Deny access for a revoked JWT access token
     • Introspect / revoke an access token
   • Provide a JWK source backed by a key rotation strategy
   • Implement the core services with JPA:
     • RegisteredClientRepository
     • OAuth2AuthorizationService
     • OAuth2AuthorizationConsentService
8. Appendices

[NotFound403]

Architecture Pic

[mabujaber]

• Best practice section for web, mobile, server, and ..etc

[sjohnr]

Since I missed linking the commit, see 525eca6 (initial draft of How-to: Implement the core services with JPA)

[NotFound403]

Eventually, it will be hosted on docs.spring.io, but it might be a bit before we automate pushing documentation artifacts out there.

If you'd like to review progress, check out the docs directory. You can run npm install and then antora local-antora-playbook.yml to build the site, then launch docs/build/site/index.html in your browser.

Not sure we're quite ready for lots of documentation contributions to begin flowing in yet, as we're still sorting out how it's going to look and nothing has settled yet. The most useful contributions at this point will be:

• Suggestions for content and guides, and up-votes to help us prioritize the ones we work on
• Feedback on any drafted content so we know whether we're on the right track (for example, "This was helpful..." or "The guide seems to be missing this piece of information..." etc.)
• Quick/easy updates such as typo fixes, etc.

Hopefully it will settle quickly and we can begin to divide up work among contributors at a later time.

antora is need. Anyone can install it by npm install -g @antora/cli @antora/site-generator, and the local-antora-playbook.ymledited is that:

site:
  title: Spring Authorization Server
  url: https://docs.spring.io/spring-authorization-server
  start_page: reference::index.adoc
asciidoc:
  attributes:
    page-pagination: true
content:
  sources:
    - url: ../
      branches: [ref-doc]
      start_path: docs
ui:
  bundle:
    url: https://github.com/spring-io/antora-ui-spring/releases/download/latest/ui-bundle.zip
    snapshot: true

[dfcoffin]

@NotFound403 The docs link returns a 404.

[NotFound403]

@NotFound403 The docs link returns a 404.

The git branch has been moved to ref-doc, so u need to checkout ref-doc

[sjohnr]

Thanks @dfcoffin @NotFound403. I've updated the link in all comments.

[jgrandja]

The reference documentation is a "work-in-progress" and lives in the docs directory.