Documentation topics to address for >=0.2.2

[jackdpeterson]

This is a work-in-progress issue based on what I'm observing is non-obvious in my testing while implementing / upgrading the Spring Authorization server

Useful information for Resource Servers

• End-to-end documentation from Authorities / scopes to Spring Security hasRole or hasPermission filters
  Given an endpoint that supplies information about the authenticated principal, The authorities should be populated:

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
import java.security.Principal;

@RestController
public final class IdentityController {
    @GetMapping("/oauth/me")
    Principal me(final Principal user) {
        return user;
    }
}

• Discuss how to debug the OIDC Authorization Code flow using oidcdebugger.com
• Discuss how to handle invalid_grant 400 HTTP status code; specifically how to get a more detailed message about what's invalid about the grant.

Transitional knowledge

• Discuss the migration process from previous Spring OAuth project.

Not directly in-scope for this repo, but it's the next logical set of actions implementors could use as a reference

• How to create a Register page with validations
• Forgot + Reset Password flow w/ validations
• Login screen customization w/ validation on fields (e.g., enforce the same constraints as are in place on register page: valid username, minimum password length).

[jgrandja]

@jackdpeterson Thanks for your interest in the reference documentation. We started work on it and have put together a "draft" outline in gh-499.

Regarding your documentation requests:

End-to-end documentation from Authorities / scopes to Spring Security hasRole...

This will be covered in the “How-to Guides" - "Authorize an access token containing custom authorities, e.g. roles, groups, permissions, etc."

Discuss how to handle invalid_grant 400 HTTP status code...

This will be covered in the “How-to Guides" - "Handling errors and customizing the OAuth 2.0 Error Response"

Discuss how to debug the OIDC Authorization Code flow using oidcdebugger.com

This isn't something we would document. You would first need to become familiar with the flow as defined in 3.1. Authentication using the Authorization Code Flow. Then become familiar with the components in Spring Authorization Server that implement this flow.

Discuss the migration process from previous Spring OAuth project.

Spring Authorization Server is a complete re-write and there isn't a one-to-one mapping between the 2 projects. It will likely require some effort to document and I'm not sure how much bandwidth we have at the moment for that. Users typically look at the sample application and determine the differences between the 2 projects. What difficulties are you having in the migration process? I would recommend creating a new issue so we can discuss there.

Not directly in-scope for this repo...

Registration page, Forgot + Reset password and custom Login page are not Authorization Server specific features. These features are identity specific features and therefore would be delivered within the Identity product side. Spring Authorization Server is a framework for building an OAuth 2.0 / OpenID Connect 1.0 Provider product, however, it is not responsible for providing product-specific features. This is the responsibility of the application product that is leveraging Spring Authorization Server for the underlying protocol implementations. Therefore, we would not document any of these items either. I hope this makes sense?

I'm going to close this as we've captured your 2 documentation requests in gh-499.

[jackdpeterson]

Thanks @jgrandja!