tut-spring-boot-oauth2: five sample apps for social login in Spring Boot

Five sample apps that build on each other

The spring-guides tutorial shows how to build a sample application doing various things with social login using OAuth 2.0 and Spring Boot. The stated arc is simple: it starts with a single provider single sign on, and works up to a client with a choice of authentication providers, GitHub or Google.

The samples live in their own directories at the top level of the repository, and their names describe the progression. `simple/` is the starting point. `click/` adds a button that triggers the flow. `logout/` handles signing out. `two-providers/` is the multi-provider version. `custom-error/` covers what happens when something goes wrong in the flow. Each is a self contained application with its own README, which is the format the guide is written in.

The architectural decision is that all of them are single page apps with Spring Boot and Spring Security on the back end, and the front end is plain jQuery. The guide is explicit that this is a choice rather than a requirement: the changes needed to convert to a different JavaScript framework or to use server side rendering would be minimal.

Every sample is implemented using the native OAuth 2.0 support in Spring Boot, so the code is a demonstration of the framework's own client support rather than a hand rolled implementation. That is the right default for a guide whose audience is people who would rather not write redirect handling themselves, but it also means the guide teaches you the framework's shape, not the underlying protocol.

The guide is assembled from asciidoc includes

The repository is a Spring guide project, and the README.adoc at the root is not the guide itself. It is the assembly point.

The front matter lists the guide's metadata, with the tags security, javascript, rest and oauth, and the related projects spring-security, spring-security-oauth and spring-boot. The document options that follow include a left hand table of contents, font icons, the prettify source highlighter, an image width of 500, a doctype of book, and marker characters for the emphasis levels. That is a documentation build system configured for a long form guide, not for a code project.

The body then pulls in the actual content with include directives. An `overview.adoc` file provides the introduction, and each sample directory contributes its own README.adoc with a level offset so the sections nest correctly under the guide. The document closes with an include of a footer file hosted in the spring-guides getting-started-macros repository, which is how every guide in this family shares the same footer.

That structure has a practical consequence. If you fork this repository to experiment, you are forking a documentation build with five embedded applications, and the guide text lives in files that are pulled in rather than in the README you can see at a glance. The top level also carries a Gemfile, a Guardfile and a .travis.yml, which belong to the documentation tooling and the build rather than to the Java code.

The Maven wrapper is there, the run commands are not

Here is the honest state of the instructions: the README does not document how to install or run the samples, so this article will not invent a command for you.

What the repository does provide is the standard scaffolding. There is a `mvnw` script and a `mvnw.cmd` for Windows, along with a `.mvn/` directory, which is the Maven wrapper, so a build does not need a system Maven install. A `pom.xml` at the root sits alongside the sample directories, and the top level also holds a `contributing.adoc` and a `.github/` directory.

The documentation to read is the published guide at spring.io/guides/tutorials/spring-boot-oauth2/, which is where the per-sample instructions live, and each sample's own README.adoc inside its directory. The README covers the guide's structure and its message, not the build steps, and the difference between a wrapper in the tree and a documented command is exactly the kind of gap that costs an afternoon.

One more piece of the build picture: the guide also carries a `LICENSE.code.txt` and a `LICENSE.writing.txt`, and the repository's licence field on GitHub is recorded as unknown. Two licence files in a guide repository is a deliberate pattern, one for the sample code and one for the written guide, and it is worth knowing which applies to what you copy.

Registering with GitHub and keeping credentials out of git

The closing advice in the guide is the part to take seriously, because it is the part that bites people who copy the samples.

The guidance is to register with GitHub, or a similar provider, and get client credentials for your own host addresses if you use the sample versions on your own servers. Each sample application needs a client id and a client secret from the provider, and the redirect URI registered with the provider has to match the address the application runs on. When you move the samples off localhost, that registration has to change with it.

The second instruction is to keep those credentials out of source control. It is stated plainly, and it is the kind of thing that a tutorial reader skips because the credentials in the tutorial are placeholders. They are not placeholders in your copy.

The two sample providers differ in protocol, and the guide links to Google's OpenID Connect documentation rather than to a plain OAuth 2.0 page for that provider. The title of the guide is Social Login with Spring Boot and OAuth 2.0, and the tag list includes oauth, but the provider links show that the Google path is OpenID Connect, which is a layer on top of OAuth 2.0. That distinction matters if you copy the configuration, because an OpenID Connect provider issues an identity token and a plain OAuth 2.0 provider does not.

The guide also frames the shared theme clearly: authentication using an external OAuth 2.0 provider, with the samples easily extended and reconfigured for more specific use cases, usually with nothing more than a configuration file change.

Where a jQuery front end and a 2020s provider landscape get in the way

There are two clear boundaries, and one is a general limitation of the OAuth 2.0 client approach that the guide does not resolve.

The first is the front end. Plain jQuery with a single page app is fine for demonstrating a redirect based flow, and the guide argues the change to another framework or to server side rendering would be minimal. Minimal is not the same as free, and anyone porting these samples to a modern component framework with a build step is doing work the guide does not show. The same applies to the styling and error display, which is where the `custom-error/` sample is the most transferable part and the least.

The second is that the guide is a demonstration of the happy path plus one error case. The README says nothing about session storage, token refresh, logout propagation back to the provider, or key rotation for the client secret. Those are the parts of a production social login system that take the most time, and none of them are the subject of a tutorial that starts with a single provider and ends with a choice of two.

A third limitation is about the framework layer rather than the guide. Because every sample uses the native OAuth 2.0 support in Spring Boot, the samples are tied to the version of Spring Boot and Spring Security in the pom.xml. Behaviour that changed between major versions of those libraries, particularly around session and redirect handling, will not be visible in an older tutorial. Checking which version the pom.xml pins is the first thing to do before copying any of it.

A guide with a date on it

On upkeep, the facts are limited but clear. The repository is not archived, and the last push was on 2026-07-01, which is a little under four months before this writing. There are no GitHub releases, so the guide has no versioned artefacts, no changelog and no upgrade path in the release sense. For a tutorial repository that is the expected shape, since the content is a set of examples rather than a distributed library.

The version that actually matters to you is the one in the pom.xml, and that is the file to read to know which Spring Boot and Spring Security the samples were built against. The guide's own framing, that the samples can be extended and reconfigured for more specific use cases with nothing more than a configuration file change, is optimistic in a way that holds only for the parts of the flow that are genuinely configuration: the client registration, the redirect URI and the provider choice.

The licence picture deserves a final note. The GitHub licence field is recorded as unknown, and the repository carries `LICENSE.code.txt` and `LICENSE.writing.txt` as separate files, which is the standard pattern in the Spring guides for separating the licence of the sample code from the licence of the written guide. If you lift code from these samples into your own application, the file to read is the code licence, and if you reuse the prose, it is the other one. Reading both is a two minute task, and it is the one piece of the guide that is unambiguously load bearing for anyone who copies from it.

Editorial conclusion

Adopt this tutorial if you need a working reference for wiring an OAuth 2.0 provider into a Spring Boot application, because the five samples build on each other in a way that makes the redirect and session handling visible. Do not adopt it as a starting point for a production login system, since the front end is plain jQuery, the samples register with GitHub and Google for local development, and the repository has not been pushed to since 2026-07-01. Before you copy from it, read LICENSE.code.txt and LICENSE.writing.txt separately, since the repository carries two different licences, one for the sample code and one for the prose.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. spring-guides/tut-spring-boot-oauth2 on GitHub