Skip to content

Commit c97d0b7

Browse files
alegaussalegauss
committed
Add Social Login docs and link from auth
Introduce a new Social Login (OAuth2) guide documenting Google, GitHub, and Microsoft provider setup, redirect URIs, user profile behavior, and troubleshooting. Update the main authentication page to list Social Login as a supported mode and add instructions/snippet for enabling providers. Add the new page to the Turing sidebar for discoverability.
1 parent 38344f6 commit c97d0b7

4 files changed

Lines changed: 297 additions & 2 deletions

File tree

‎docs-turing/security-authentication.md‎

Lines changed: 28 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,15 @@ description: Native authentication for Turing ES — session-based admin console
66

77
# Authentication
88

9-
Turing ES supports two authentication modes. **Native authentication** is the default and requires no external dependencies. **Keycloak OAuth2 / OpenID Connect** is the recommended mode for production SSO environments.
9+
Turing ES supports three authentication modes:
1010

11-
This page covers **native authentication** — the session-based admin console login and the API Key mechanism for REST API access. For the full Keycloak production setup, see [Security & Keycloak](./security-keycloak.md).
11+
| Mode | Best for | External dependency |
12+
|---|---|---|
13+
| **Native** (default) | Development, simple setups | None |
14+
| **Social Login (OAuth2)** | Small teams, GitHub/Google/Microsoft accounts | Provider OAuth App |
15+
| **Keycloak SSO** | Enterprise production with LDAP/AD, MFA, RBAC | Keycloak server |
16+
17+
This page covers **native authentication**. For social login with Google, GitHub, or Microsoft, see [Social Login (OAuth2)](./security-social-login.md). For the full Keycloak production setup, see [Security & Keycloak](./security-keycloak.md).
1218

1319
---
1420

@@ -41,6 +47,25 @@ API Token values are encrypted at rest in the database. The encryption key is se
4147

4248
---
4349

50+
## Switching to Social Login (OAuth2)
51+
52+
For teams using Google, GitHub, or Microsoft, you can enable social login buttons by adding the provider configuration in `application.yaml`:
53+
54+
```yaml
55+
spring:
56+
security:
57+
oauth2:
58+
client:
59+
registration:
60+
github:
61+
client-id: YOUR_CLIENT_ID
62+
client-secret: YOUR_CLIENT_SECRET
63+
```
64+
65+
The login page automatically shows buttons only for configured providers. See [Social Login (OAuth2)](./security-social-login.md) for complete setup instructions for each provider.
66+
67+
---
68+
4469
## Switching to Keycloak SSO
4570
4671
For production environments with SSO requirements, Turing ES can delegate authentication to Keycloak via OAuth2 / OpenID Connect. Enable it with:
@@ -57,6 +82,7 @@ See [Security & Keycloak](./security-keycloak.md) for the full 6-step production
5782

5883
| Page | Description |
5984
|---|---|
85+
| [Social Login (OAuth2)](./security-social-login.md) | Google, GitHub, and Microsoft social login |
6086
| [Security & Keycloak](./security-keycloak.md) | Full production setup with Keycloak OAuth2/OIDC |
6187
| [Administration Guide](./administration-guide.md) | Managing users, groups, roles, and API tokens |
6288
| [REST API](./rest-api.md) | Full REST API reference including authentication examples |

‎docs-turing/security-social-login.md‎

Lines changed: 210 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,210 @@
1+
---
2+
sidebar_position: 4
3+
title: Social Login (OAuth2)
4+
description: Configure Google, GitHub, and Microsoft social login for Turing ES using Spring Security OAuth2.
5+
---
6+
7+
# Social Login (OAuth2)
8+
9+
Turing ES supports **social login** via OAuth2 with Google, GitHub, and Microsoft. When configured, users can sign in with their existing accounts from these providers — no separate password required.
10+
11+
This is ideal for development environments, small teams, and scenarios where a full Keycloak deployment is not needed. For enterprise SSO with LDAP/AD federation, MFA, and centralized user management, see [Security & Keycloak](./security-keycloak.md).
12+
13+
---
14+
15+
## How It Works
16+
17+
```mermaid
18+
sequenceDiagram
19+
participant User
20+
participant Turing ES
21+
participant OAuth2 Provider
22+
23+
User->>Turing ES: Click "Sign in with Google"
24+
Turing ES->>OAuth2 Provider: Redirect to authorization
25+
OAuth2 Provider->>User: Show consent screen
26+
User->>OAuth2 Provider: Approve
27+
OAuth2 Provider->>Turing ES: Redirect with authorization code
28+
Turing ES->>OAuth2 Provider: Exchange code for token + user info
29+
Turing ES->>User: Create session, redirect to /admin
30+
```
31+
32+
When a user signs in via a social provider for the first time, Turing ES **automatically creates a local user** with the profile information from the provider (name, email, avatar). Subsequent logins update the profile data.
33+
34+
---
35+
36+
## Prerequisites
37+
38+
| Requirement | Details |
39+
|---|---|
40+
| `turing.authentication.thirdparty` | Must be `true` (default) |
41+
| Provider OAuth App | Create an OAuth App/Client in the provider's console |
42+
| Redirect URI | `http://<host>:<port>/login/oauth2/code/<provider>` |
43+
44+
---
45+
46+
## Configuration
47+
48+
Add the provider registration under `spring.security.oauth2.client` in your `application.yaml`:
49+
50+
### Google
51+
52+
1. Go to [Google Cloud Console](https://console.cloud.google.com/apis/credentials)
53+
2. Create an **OAuth 2.0 Client ID** (Web application)
54+
3. Add the authorized redirect URI: `http://localhost:2700/login/oauth2/code/google`
55+
56+
```yaml
57+
spring:
58+
security:
59+
oauth2:
60+
client:
61+
registration:
62+
google:
63+
client-id: YOUR_GOOGLE_CLIENT_ID
64+
client-secret: YOUR_GOOGLE_CLIENT_SECRET
65+
```
66+
67+
:::tip Scopes
68+
Spring Security auto-configures the Google provider with `openid`, `profile`, and `email` scopes — no need to set them manually.
69+
:::
70+
71+
### GitHub
72+
73+
1. Go to [GitHub Developer Settings > OAuth Apps](https://github.com/settings/developers)
74+
2. Click **New OAuth App**
75+
3. Set **Homepage URL** to `http://localhost:2700`
76+
4. Set **Authorization callback URL** to `http://localhost:2700/login/oauth2/code/github`
77+
78+
```yaml
79+
spring:
80+
security:
81+
oauth2:
82+
client:
83+
registration:
84+
github:
85+
client-id: YOUR_GITHUB_CLIENT_ID
86+
client-secret: YOUR_GITHUB_CLIENT_SECRET
87+
```
88+
89+
:::note GitHub specifics
90+
- GitHub does not provide a separate first/last name — Turing splits the `name` attribute automatically.
91+
- Email may be `null` if the user's GitHub email is private. The email field is hidden in the profile page when empty.
92+
- The username is the GitHub `login` handle.
93+
:::
94+
95+
### Microsoft (Entra ID / Azure AD)
96+
97+
1. Go to [Azure Portal > App registrations](https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps)
98+
2. Register a new application
99+
3. Under **Authentication**, add a **Web** redirect URI: `http://localhost:2700/login/oauth2/code/microsoft`
100+
4. Under **Certificates & secrets**, create a new client secret
101+
102+
```yaml
103+
spring:
104+
security:
105+
oauth2:
106+
client:
107+
registration:
108+
microsoft:
109+
client-id: YOUR_MICROSOFT_CLIENT_ID
110+
client-secret: YOUR_MICROSOFT_CLIENT_SECRET
111+
scope: openid,profile,email
112+
authorization-grant-type: authorization_code
113+
redirect-uri: "{baseUrl}/login/oauth2/code/{registrationId}"
114+
provider:
115+
microsoft:
116+
issuer-uri: https://login.microsoftonline.com/common/v2.0
117+
```
118+
119+
---
120+
121+
## Multiple Providers
122+
123+
You can configure any combination of providers simultaneously. The login page **automatically shows only the buttons for configured providers**:
124+
125+
```yaml
126+
spring:
127+
security:
128+
oauth2:
129+
client:
130+
registration:
131+
google:
132+
client-id: ...
133+
client-secret: ...
134+
github:
135+
client-id: ...
136+
client-secret: ...
137+
microsoft:
138+
client-id: ...
139+
client-secret: ...
140+
provider:
141+
microsoft:
142+
issuer-uri: https://login.microsoftonline.com/common/v2.0
143+
```
144+
145+
If only GitHub is configured, only the GitHub button appears. If none are configured, the social login section is hidden entirely.
146+
147+
---
148+
149+
## Redirect URIs Reference
150+
151+
| Provider | Redirect URI |
152+
|---|---|
153+
| Google | `http://<host>:<port>/login/oauth2/code/google` |
154+
| GitHub | `http://<host>:<port>/login/oauth2/code/github` |
155+
| Microsoft | `http://<host>:<port>/login/oauth2/code/microsoft` |
156+
157+
The pattern is always: `{baseUrl}/login/oauth2/code/{registrationId}`
158+
159+
For production with HTTPS: `https://turing.example.com/login/oauth2/code/google`
160+
161+
---
162+
163+
## User Profile Behavior
164+
165+
When logged in via a social provider:
166+
167+
- **Profile fields are read-only** — name, email, and username are managed by the provider
168+
- **Avatar can still be customized** in Turing
169+
- **Password section is hidden** — authentication is handled by the provider
170+
- **The provider name is displayed** on the profile page (e.g., "github", "google")
171+
172+
---
173+
174+
## Configuration Properties
175+
176+
| Property | Default | Description |
177+
|---|---|---|
178+
| `turing.authentication.thirdparty` | `true` | Enable third-party OAuth2 login buttons |
179+
| `spring.security.oauth2.client.registration.<provider>.client-id` | — | OAuth2 Client ID from the provider |
180+
| `spring.security.oauth2.client.registration.<provider>.client-secret` | — | OAuth2 Client Secret from the provider |
181+
182+
---
183+
184+
## Troubleshooting
185+
186+
### 404 on provider authorization page
187+
188+
The Client ID is likely incorrect. Double-check the value in `application.yaml` matches the one in the provider's console.
189+
190+
### User profile shows empty name
191+
192+
The provider attributes may use different field names. Turing handles Google (`given_name`, `family_name`), GitHub (`login`, `name`), and Microsoft (`given_name`, `family_name`) automatically. For other providers, the `name` attribute is split into first/last name.
193+
194+
### Email is empty (GitHub)
195+
196+
GitHub may not expose the user's email if it is set to private. This is by design — the email field is hidden in the profile page when empty.
197+
198+
### Login redirects to wrong page
199+
200+
The default success URL is `/admin`. If using a different frontend path, ensure the Spring Security configuration matches.
201+
202+
---
203+
204+
## Related Pages
205+
206+
| Page | Description |
207+
|---|---|
208+
| [Authentication](./security-authentication.md) | Native authentication and API Keys |
209+
| [Security & Keycloak](./security-keycloak.md) | Full Keycloak production setup with SSO |
210+
| [Configuration Reference](./configuration-reference.md) | All configuration properties |

‎package-lock.json‎

Lines changed: 58 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎sidebars-turing.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -88,6 +88,7 @@ const sidebars: SidebarsConfig = {
8888
label: "Security",
8989
items: [
9090
"security-authentication",
91+
"security-social-login",
9192
"security-keycloak",
9293
],
9394
},

0 commit comments

Comments
 (0)