spring-authorization-server/samples/README.adoc

= Samples

[[default-sample]]
== Default Sample

The default sample provides the minimal configuration to get started with Spring Authorization Server.

[[spa-sample]]
== SPA (Single Page Application) Sample

The SPA sample provides a reference implementation of the https://datatracker.ietf.org/doc/html/draft-ietf-oauth-browser-based-apps-19#name-backend-for-frontend-bff[Backend For Frontend (BFF)] application architecture pattern.
The *spa-client* is the _frontend_ SPA implemented with Angular and the *backend-for-spa-client* is the _backend_ application.
The *backend-for-spa-client* uses https://spring.io/projects/spring-cloud-gateway[Spring Cloud Gateway] to route `/userinfo` (UserInfo Endpoint) requests to *demo-authorizationserver* and `/messages` requests to *messages-resource*.
The *backend-for-spa-client* performs the authorization flows and stores the access tokens.
The *spa-client* is never exposed the access tokens and directly communicates with the *backend-for-spa-client* via an authenticated session cookie.

[[run-spa-sample]]
=== Run the Sample

* Run Authorization Server -> `./gradlew -b samples/demo-authorizationserver/samples-demo-authorizationserver.gradle bootRun`
* Run Resource Server -> `./gradlew -b samples/messages-resource/samples-messages-resource.gradle bootRun`
* Run Backend -> `./gradlew -b samples/backend-for-spa-client/samples-backend-for-spa-client.gradle bootRun`
* Run Frontend -> `ng serve` (from `samples/spa-client` directory)
** *NOTE:* Angular must be installed locally before running `ng serve`. See https://angular.dev/installation[installation instructions].
* Go to `http://127.0.0.1:4200`
** Login with credentials -> user1 \ password

[[demo-sample]]
== Demo Sample

The demo sample provides custom configuration for various features implemented by Spring Authorization Server.

[[run-demo-sample]]
=== Run the Sample

* Run Authorization Server -> `./gradlew -b samples/demo-authorizationserver/samples-demo-authorizationserver.gradle bootRun`
* Run Client -> `./gradlew -b samples/demo-client/samples-demo-client.gradle bootRun`
* Run Resource Server -> `./gradlew -b samples/messages-resource/samples-messages-resource.gradle bootRun`
* Go to `http://127.0.0.1:8080`
** Login with credentials -> user1 \ password

[[configuring-social-login]]
=== Configuring Social Login

The demo sample may be configured to provide social login capability.

[[google-login]]
==== Login with Google

This section shows how to configure Google as a social login provider.

[[google-initial-setup]]
===== Initial setup

To use Google's OAuth 2.0 authentication system for login, you must set up a project in the Google API Console to obtain OAuth 2.0 credentials.

NOTE: https://developers.google.com/identity/protocols/OpenIDConnect[Google's OAuth 2.0 implementation] for authentication conforms to the
https://openid.net/connect/[OpenID Connect 1.0] specification and is https://openid.net/certification/[OpenID Certified].

Follow the instructions on the https://developers.google.com/identity/protocols/OpenIDConnect[OpenID Connect] page, starting in the section, "Setting up OAuth 2.0".

After completing the "Obtain OAuth 2.0 credentials" instructions, you should have a new OAuth Client with credentials consisting of a Client ID and a Client Secret.

[[google-redirect-uri]]
===== Setting the redirect URI

The redirect URI is the path in the application that the end-user's user-agent is redirected back to after they have authenticated with Google
and have granted access to the OAuth Client _(created in the previous step)_ on the Consent page.

In the "Set a redirect URI" sub-section, ensure that the *Authorized redirect URIs* field is set to `http://localhost:9000/login/oauth2/code/google-idp`.

TIP: The default redirect URI template is `{baseUrl}/login/oauth2/code/{registrationId}`.
The *_registrationId_* is a unique identifier for the `ClientRegistration`.

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

Now that you have a new OAuth Client with Google, you need to configure the application to use the OAuth Client for the _authentication flow_. To do so:

. Go to `application.yml` and set the following configuration:
+
[source,yaml]
----
spring:
  security:
    oauth2:
      client:
        registration:	<1>
          google-idp:	<2>
            provider: google
            client-id: google-client-id
            client-secret: google-client-secret
----
+
.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`, such as google-idp.
====

. Replace the values in the `client-id` and `client-secret` property with the OAuth 2.0 credentials you created earlier.
Alternatively, you can set the following environment variables in the Spring Boot application:
    * `GOOGLE_CLIENT_ID`
    * `GOOGLE_CLIENT_SECRET`

[[github-login]]
==== Login with GitHub

This section shows how to configure GitHub as a social login provider.

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

To use GitHub's OAuth 2.0 authentication system for login, 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:9000/login/oauth2/code/github-idp`.

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.

TIP: The default redirect URI template is `{baseUrl}/login/oauth2/code/{registrationId}`.
The *_registrationId_* is a unique identifier for the `ClientRegistration`.

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

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

. Go to `application.yml` and set the following configuration:
+
[source,yaml]
----
spring:
  security:
    oauth2:
      client:
        registration:	<1>
          github-idp:	<2>
            provider: github
            client-id: github-client-id
            client-secret: github-client-secret
----
+
.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`, such as github-idp.
====

. Replace the values in the `client-id` and `client-secret` property with the OAuth 2.0 credentials you created earlier.
Alternatively, you can set the following environment variables in the Spring Boot application:
* `GITHUB_CLIENT_ID`
* `GITHUB_CLIENT_SECRET`