spring-security/samples/boot/oauth2/authcodegrant/README.adoc

= OAuth 2.0 Authorization Code Grant Sample

== GitHub Repositories

This guide provides instructions on setting up the sample application, which leverages the OAuth 2.0 Authorization Code Grant, and displays a list of public GitHub repositories that are accessible to the authenticated user.

This includes repositories owned by the authenticated user, repositories where the authenticated user is a collaborator, and repositories that the authenticated user has access to through an organization membership.

The following sections provide detailed steps for setting up the sample and covers the following topics:

* <<github-register-application,Register OAuth application>>
* <<github-application-config,Configure application.yml>>
* <<github-boot-application,Boot up the application>>

[[github-register-application]]
=== Register OAuth application

To use GitHub's OAuth 2.0 authorization system, you must https://github.com/settings/applications/new[Register a new OAuth application].

When registering the OAuth application, ensure the *Authorization callback URL* is set to `http://localhost:8080/github-repos`.

The Authorization callback URL (redirect URI) is the path in the application that the end-user's user-agent is redirected back to after they have authenticated with GitHub and have granted access to the OAuth application on the _Authorize application_ page.

[[github-application-config]]
=== Configure application.yml

Now that you have a new OAuth application with GitHub, you need to configure the sample to use the OAuth application for the _authorization code grant flow_.
To do so:

. Go to `application.yml` and set the following configuration:
+
[source,yaml]
----
spring:
  security:
    oauth2:
      client:
        registration:	<1>
          github:       <2>
            client-id: github-client-id
            client-secret: github-client-secret
            scope: public_repo
            redirect-uri-template: "{baseUrl}/github-repos"
            client-name: GitHub Repositories
----
+
.OAuth Client properties
====
<1> `spring.security.oauth2.client.registration` is the base property prefix for OAuth Client properties.
<2> Following the base property prefix is the ID for the `ClientRegistration`, which is github.
====

. Replace the values in the `client-id` and `client-secret` property with the OAuth 2.0 credentials you created earlier.

[[github-boot-application]]
=== Boot up the application

Launch the Spring Boot 2.0 sample and go to `http://localhost:8080`.
You are then redirected to the default _auto-generated_ form login page.
Log in using *'user'* (username) and *'password'* (password) and then you'll be redirected to GitHub for authentication.

After authenticating with your GitHub credentials, the next page presented to you is "Authorize application".
This page will ask you to *Authorize* the application you created in the previous step.
Click _Authorize application_ to allow the OAuth application to access and display your public repository information.