Skip to content

Commit 86eaa51

Browse files
vbelousovbelouso
committed
feat: add external IDP integration
1 parent b223b25 commit 86eaa51

File tree

9 files changed

+1196
-65
lines changed

9 files changed

+1196
-65
lines changed

‎docs/authentication.md‎

Lines changed: 279 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,279 @@
1+
# Authentication
2+
3+
This guide covers authentication configuration for ExploitIQ Client, including OpenShift OAuth, external identity providers, and development setups.
4+
5+
## Overview
6+
7+
ExploitIQ supports multiple authentication modes via Quarkus profiles:
8+
9+
| Profile | Use Case | Identity Provider |
10+
|---------|----------|-------------------|
11+
| `prod` | OpenShift | OpenShift OAuth |
12+
| `external-idp` | External identity providers | Keycloak, Google, Azure AD, Okta |
13+
| `dev` | Local development | Keycloak DevServices |
14+
15+
## OpenShift OAuth (Production)
16+
17+
The default production configuration uses OpenShift's built-in OAuth server.
18+
19+
### Prerequisites
20+
21+
Create an `OAuthClient` resource in your OpenShift cluster:
22+
23+
```yaml
24+
apiVersion: oauth.openshift.io/v1
25+
kind: OAuthClient
26+
metadata:
27+
name: exploit-iq-client
28+
grantMethod: prompt
29+
secret: <your-oauth-client-secret>
30+
redirectURIs:
31+
- "https://exploit-iq-client.<your-domain>"
32+
```
33+
34+
### Environment Variables
35+
36+
| Variable | Description | Example |
37+
|----------|-------------|---------|
38+
| `OPENSHIFT_DOMAIN` | OpenShift cluster domain | `example.openshift.com` |
39+
| `OAUTH_CLIENT_SECRET` | Secret from OAuthClient resource | `<your-secret>` |
40+
41+
### Deployment Configuration
42+
43+
```yaml
44+
spec:
45+
containers:
46+
- name: exploit-iq-client
47+
env:
48+
- name: OPENSHIFT_DOMAIN
49+
valueFrom:
50+
secretKeyRef:
51+
name: oauth-config
52+
key: domain
53+
- name: OAUTH_CLIENT_SECRET
54+
valueFrom:
55+
secretKeyRef:
56+
name: oauth-config
57+
key: secret
58+
```
59+
60+
## External Identity Providers
61+
62+
Use the `external-idp` profile to integrate with external OIDC providers.
63+
64+
### Keycloak
65+
66+
Keycloak can be used standalone or as an identity broker for GitHub, Google, and other providers.
67+
68+
#### Environment Variables
69+
70+
| Variable | Description | Example |
71+
|----------|-------------|---------|
72+
| `QUARKUS_PROFILE` | Must be `external-idp` | `external-idp` |
73+
| `QUARKUS_OIDC_AUTH_SERVER_URL` | Keycloak realm URL | `https://keycloak.example.com/realms/<your-realm>` |
74+
| `QUARKUS_OIDC_CREDENTIALS_SECRET` | OIDC client secret | `<your-client-secret>` |
75+
76+
**Note:** The testing script uses `quarkus` as the default realm name. Replace with your actual realm name in production.
77+
78+
#### Keycloak Client Configuration
79+
80+
Create an OIDC client in Keycloak with the following settings:
81+
82+
```json
83+
{
84+
"clientId": "exploit-iq-client",
85+
"enabled": true,
86+
"clientAuthenticatorType": "client-secret",
87+
"redirectUris": ["https://your-app-url/*"],
88+
"webOrigins": ["https://your-app-url"],
89+
"publicClient": false,
90+
"standardFlowEnabled": true
91+
}
92+
```
93+
94+
Required protocol mappers (add to client scope):
95+
96+
- `preferred_username`: Maps `username` to `preferred_username` claim
97+
- `email`: Maps `email` to `email` claim
98+
- `upn`: Maps `username` to `upn` claim (fallback)
99+
100+
### Direct Google OIDC
101+
102+
Connect directly to Google without Keycloak.
103+
104+
#### Prerequisites
105+
106+
1. Go to [Google Cloud Console](https://console.cloud.google.com/apis/credentials)
107+
2. Create OAuth 2.0 Client ID (Web application)
108+
3. Add authorized redirect URI: `https://your-app-url/`
109+
110+
#### Environment Variables
111+
112+
| Variable | Description |
113+
|----------|-------------|
114+
| `QUARKUS_PROFILE` | `external-idp` |
115+
| `QUARKUS_OIDC_PROVIDER` | `google` |
116+
| `QUARKUS_OIDC_CLIENT_ID` | Google Client ID |
117+
| `QUARKUS_OIDC_CREDENTIALS_SECRET` | Google Client Secret |
118+
119+
#### Deployment Example
120+
121+
```yaml
122+
env:
123+
- name: QUARKUS_PROFILE
124+
value: "external-idp"
125+
- name: QUARKUS_OIDC_PROVIDER
126+
value: "google"
127+
- name: QUARKUS_OIDC_CLIENT_ID
128+
valueFrom:
129+
secretKeyRef:
130+
name: google-oauth
131+
key: client-id
132+
- name: QUARKUS_OIDC_CREDENTIALS_SECRET
133+
valueFrom:
134+
secretKeyRef:
135+
name: google-oauth
136+
key: client-secret
137+
```
138+
139+
### Other OIDC Providers
140+
141+
The same approach works with any OIDC-compliant provider:
142+
143+
| Provider | Auth Server URL |
144+
|----------|-----------------|
145+
| Azure AD | `https://login.microsoftonline.com/{tenant}/v2.0` |
146+
| Okta | `https://dev-xxxxx.okta.com/oauth2/default` |
147+
| Auth0 | `https://your-domain.auth0.com` |
148+
| AWS Cognito | `https://cognito-idp.{region}.amazonaws.com/{userPoolId}` |
149+
150+
**Note:** GitHub does not support OIDC. Use Keycloak as an identity broker for GitHub authentication.
151+
152+
## Identity Brokering with Keycloak
153+
154+
Keycloak can act as an identity broker, allowing users to authenticate via external providers while maintaining centralized user management.
155+
156+
### Architecture
157+
158+
```
159+
User → Application → Keycloak (Broker) → External IdP (GitHub/Google)
160+
↓
161+
Token Issuance
162+
↓
163+
Application
164+
```
165+
166+
### GitHub Identity Broker
167+
168+
1. Create GitHub OAuth App at [GitHub Developer Settings](https://github.com/settings/applications/new)
169+
2. Set callback URL: `https://<your-keycloak>/realms/<your-realm>/broker/github/endpoint`
170+
3. Configure in Keycloak: Identity Providers → Add GitHub
171+
4. Add mappers:
172+
- `login` → `preferred_username`
173+
- `email` → `email`
174+
175+
### Google Identity Broker
176+
177+
1. Create Google OAuth Client at [Google Cloud Console](https://console.cloud.google.com/apis/credentials)
178+
2. Set redirect URI: `https://<your-keycloak>/realms/<your-realm>/broker/google/endpoint`
179+
3. Configure in Keycloak: Identity Providers → Add Google
180+
4. Add mappers:
181+
- `email` → `email`
182+
183+
## Local Development
184+
185+
### DevServices (Automatic)
186+
187+
Quarkus automatically starts Keycloak via DevServices:
188+
189+
```bash
190+
./mvnw quarkus:dev
191+
```
192+
193+
Test users are pre-configured in `application.properties`:
194+
195+
```properties
196+
%dev.quarkus.keycloak.devservices.users.bruce=wayne
197+
%dev.quarkus.keycloak.devservices.users.peter=parker
198+
```
199+
200+
### External Keycloak (Manual)
201+
202+
For testing with an external Keycloak instance:
203+
204+
```bash
205+
# Start Keycloak (use podman or docker)
206+
podman run -d --name keycloak \
207+
-p 8190:8080 \
208+
-e KEYCLOAK_ADMIN=admin \
209+
-e KEYCLOAK_ADMIN_PASSWORD=admin \
210+
quay.io/keycloak/keycloak:26.4 start-dev
211+
212+
# Start application (using 'quarkus' as example realm name)
213+
./mvnw quarkus:dev \
214+
-Dquarkus.profile=external-idp \
215+
-Dquarkus.oidc.auth-server-url=http://localhost:8190/realms/quarkus \
216+
-Dquarkus.oidc.credentials.secret=example-credentials \
217+
-Dquarkus.keycloak.devservices.enabled=false
218+
```
219+
220+
### Testing Script
221+
222+
An automated testing script is available for all authentication scenarios:
223+
224+
```bash
225+
./scripts/test-auth.sh --help
226+
```
227+
228+
The script supports:
229+
230+
1. DevServices Keycloak (local development)
231+
2. DevServices + GitHub Broker
232+
3. External Keycloak (standalone)
233+
4. External Keycloak + GitHub Broker
234+
5. External Keycloak + Google Broker
235+
6. Direct Google OIDC
236+
237+
## User Display
238+
239+
The application displays user information with this priority:
240+
241+
1. `email` claim (primary)
242+
2. `upn` claim (User Principal Name)
243+
3. `metadata.name` (OpenShift)
244+
4. `anonymous` (fallback)
245+
246+
Ensure your identity provider or Keycloak is configured to include the `email` claim in tokens.
247+
248+
## Troubleshooting
249+
250+
### User Shows as "anonymous"
251+
252+
**Cause:** Missing protocol mappers in Keycloak.
253+
254+
**Solution:** Add `email`, `preferred_username`, and `upn` mappers to the client scope.
255+
256+
### Redirect URI Mismatch
257+
258+
**Cause:** The redirect URI in the OAuth app doesn't match the application URL.
259+
260+
**Solution:**
261+
262+
- Ensure exact match including trailing slash: `https://your-app/`
263+
- Changes may take 5-15 minutes to propagate
264+
265+
### Enable Debug Logging
266+
267+
Add to `application.properties` or set as environment variable:
268+
269+
```properties
270+
quarkus.log.category."io.quarkus.oidc".level=DEBUG
271+
```
272+
273+
## Additional Resources
274+
275+
- [Quarkus OIDC Guide](https://quarkus.io/guides/security-openid-connect)
276+
- [Quarkus Configuring Well-Known OpenID Connect Providers](https://quarkus.io/guides/security-openid-connect-providers)
277+
- [Keycloak Documentation](https://www.keycloak.org/documentation)
278+
- [GitHub OAuth Apps](https://docs.github.com/en/developers/apps/building-oauth-apps)
279+
- [Google OAuth 2.0](https://developers.google.com/identity/protocols/oauth2)

‎docs/configuration.md‎

Lines changed: 2 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -2,34 +2,9 @@
22

33
## Authentication
44

5-
For development a Keycloak instance will be instantiated with the users defined in the configuration.
5+
For detailed authentication configuration including OpenShift OAuth, Keycloak, and external identity providers (Google, GitHub, Azure AD), see the [Authentication Guide](./authentication.md).
66

7-
```properties
8-
%dev.quarkus.keycloak.devservices.users.joe=pass123
9-
```
10-
11-
For production the OpenShift OAuth2 provider will be used so it is required to
12-
provide the following environment variables:
13-
14-
* `OPENSHIFT_DOMAIN`: e.g. `example.openshift.com`
15-
* `OAUTH_CLIENT_SECRET`: With the secret defined for the `agent-morpheus-client` in the OpenShift cluster.
16-
17-
In the cluster you have to create an `OAuthClient` with the right redirect URLs
18-
19-
```yaml
20-
apiVersion: oauth.openshift.io/v1
21-
kind: OAuthClient
22-
metadata:
23-
name: agent-morpheus-client
24-
grantMethod: prompt
25-
secret: some-long-secret-used-by-the-oauth-client
26-
redirectURIs:
27-
- "http://agent-morpheus-client:8080"
28-
- "https://agent-morpheus-client.example.openshift.com"
29-
- "http://agent-morpheus-client.example.openshift.com"
30-
```
31-
32-
## External services (GitHub / Morpheus)
7+
## External Services (GitHub / Morpheus)
338

349
Use the `rest-client` properties for updating the default the github and morpheus RestClient endpoints:
3510

‎docs/development.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,9 @@
22

33
## Configuration
44

5-
To see all the configuration options check the [configuration](./configuration.md) README.
5+
To see all the configuration options check the [configuration](./configuration.md) guide.
6+
7+
For authentication setup (Keycloak, external identity providers, testing), see the [authentication](./authentication.md) guide.
68

79
## Running the application in dev mode
810

0 commit comments

Comments
 (0)