Skip to content

Commit d95d526

Browse files
neSpeccneSpecc
committed
fix integration tests
1 parent 26b9d2f commit d95d526

File tree

5 files changed

+501
-4
lines changed

5 files changed

+501
-4
lines changed

‎docker-compose.test.yml‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ services:
1111
- ./:/usr/src/app
1212
- /usr/src/app/node_modules
1313
- ./test/integration/api.env:/usr/src/app/.env
14-
- ../keycloak:/keycloak:ro
14+
- ./test/integration/keycloak:/keycloak:ro
1515
depends_on:
1616
- mongodb
1717
- rabbitmq
@@ -47,7 +47,7 @@ services:
4747
volumes:
4848
- ./:/usr/src/app
4949
- /usr/src/app/node_modules
50-
- ../keycloak:/keycloak:ro
50+
- ./test/integration/keycloak:/keycloak:ro
5151

5252
rabbitmq:
5353
image: rabbitmq:3-management
@@ -80,7 +80,7 @@ services:
8080
- start-dev
8181
volumes:
8282
- keycloak-test-data:/opt/keycloak/data
83-
- ../keycloak:/opt/keycloak/config
83+
- ./test/integration/keycloak:/opt/keycloak/config
8484
healthcheck:
8585
test: ["CMD-SHELL", "exec 3<>/dev/tcp/127.0.0.1/8180;echo -e 'GET /health/ready HTTP/1.1\r\nhost: http://localhost\r\nConnection: close\r\n\r\n' >&3;if [ $? -eq 0 ]; then echo 'Healthcheck Successful';exit 0;else echo 'Healthcheck Failed';exit 1;fi;"]
8686
interval: 10s

‎docs/Keycloak.md‎

Lines changed: 212 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,212 @@
1+
# Keycloak for Hawk SSO Development
2+
3+
This guide explains how to use Keycloak for testing Hawk's SSO implementation.
4+
5+
## Quick Start
6+
7+
### 1. Start Keycloak
8+
9+
From the project root:
10+
11+
```bash
12+
docker-compose up keycloak
13+
```
14+
15+
Keycloak will be available at: **http://localhost:8180**
16+
17+
### 2. Run Setup Script
18+
19+
The setup script will configure Keycloak with a test realm, SAML client, and test users.
20+
21+
**Option 1: Run from your host machine** (recommended):
22+
23+
```bash
24+
cd api/test/integration/keycloak
25+
KEYCLOAK_URL=http://localhost:8180 ./setup.sh
26+
```
27+
28+
**Option 2: Run from API container** (if you don't have curl on host):
29+
30+
```bash
31+
docker-compose exec -e KEYCLOAK_URL=http://keycloak:8180 api /keycloak/setup.sh
32+
```
33+
34+
**Note:** The setup script requires `curl` and `bash` to interact with Keycloak API. The Keycloak container doesn't have these tools, so we either run from host or from another container (like `api`).
35+
36+
### 3. Access Keycloak Admin Console
37+
38+
- URL: http://localhost:8180
39+
- Username: `admin`
40+
- Password: `admin`
41+
42+
## Configuration
43+
44+
### Realm
45+
46+
- **Name**: `hawk`
47+
- **SAML Endpoint**: http://localhost:8180/realms/hawk/protocol/saml
48+
49+
### SAML Client
50+
51+
- **Client ID / Entity ID**: `urn:hawk:tracker:saml`
52+
- This must match `SSO_SP_ENTITY_ID` environment variable in Hawk API
53+
- **Protocol**: SAML 2.0
54+
- **ACS URL**: http://localhost:4000/auth/sso/saml/{workspaceId}/acs
55+
- **Name ID Format**: email
56+
57+
### Environment Variables
58+
59+
Hawk API requires the following environment variable:
60+
61+
- **SSO_SP_ENTITY_ID**: `urn:hawk:tracker:saml`
62+
- Set in `docker-compose.yml` or `.env` file
63+
- This is the Service Provider Entity ID used to identify Hawk in SAML requests
64+
65+
### Test Users
66+
67+
| Username | Email | Password | Department | Title |
68+
|----------|-------|----------|------------|-------|
69+
| testuser | testuser@hawk.local | password123 | Engineering | Software Engineer |
70+
| alice | alice@hawk.local | password123 | Product | Product Manager |
71+
| bob | bob@hawk.local | password123 | Engineering | Senior Developer |
72+
73+
## Hawk SSO Configuration
74+
75+
To configure SSO in Hawk workspace settings:
76+
77+
### Get Configuration Automatically
78+
79+
**Option 1: Use the helper script** (recommended):
80+
81+
```bash
82+
cd api/test/integration/keycloak
83+
./get-config.sh
84+
```
85+
86+
This will output all required values that you can copy-paste into Hawk SSO settings.
87+
88+
**Option 2: Get values manually**:
89+
90+
### Required Fields
91+
92+
1. **IdP Entity ID**:
93+
```
94+
http://localhost:8180/realms/hawk
95+
```
96+
97+
2. **SSO URL**:
98+
```
99+
http://localhost:8180/realms/hawk/protocol/saml
100+
```
101+
102+
3. **X.509 Certificate**:
103+
104+
**Via command line**:
105+
```bash
106+
curl -s "http://localhost:8180/realms/hawk/protocol/saml/descriptor" | grep -oP '(?<=<ds:X509Certificate>)[^<]+' | head -1
107+
```
108+
109+
**Via Keycloak Admin Console**:
110+
- Go to Realm Settings → Keys
111+
- Find RS256 algorithm row
112+
- Click "Certificate" button
113+
- Copy the certificate (without BEGIN/END lines)
114+
- Paste into Hawk SSO settings
115+
116+
### Attribute Mapping
117+
118+
Configure these mappings in Hawk:
119+
120+
- **Email**: `email`
121+
- **Name**: `name` (full name - combines firstName and lastName from Keycloak)
122+
- **Department** (optional): `department`
123+
- **Title** (optional): `title`
124+
125+
### Name ID Format
126+
127+
Select: **Email address (urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress)**
128+
129+
## Testing SSO Flow
130+
131+
### Manual Test
132+
133+
1. Configure SSO in Hawk workspace settings with the values above
134+
2. Enable SSO for the workspace
135+
3. Navigate to: http://localhost:4000/auth/sso/saml/{workspaceId}
136+
4. You'll be redirected to Keycloak login page
137+
5. Login with any test user (e.g., `testuser@hawk.local` / `password123`)
138+
6. After successful authentication, you'll be redirected back to Hawk with tokens
139+
140+
### Automated Test
141+
142+
Run integration tests:
143+
144+
```bash
145+
cd api
146+
yarn test:integration
147+
```
148+
149+
## Troubleshooting
150+
151+
### Keycloak not starting
152+
153+
Check Docker logs:
154+
```bash
155+
docker-compose logs keycloak
156+
```
157+
158+
### Realm already exists
159+
160+
If you need to reset:
161+
```bash
162+
docker-compose down -v
163+
docker-compose up keycloak
164+
```
165+
166+
### Certificate issues
167+
168+
If SAML validation fails:
169+
1. Verify the certificate is copied correctly (no extra spaces/newlines)
170+
2. Ensure you copied the certificate content without BEGIN/END markers
171+
3. Check Keycloak logs for signature errors
172+
173+
### Get SAML Metadata
174+
175+
You can view the full SAML metadata descriptor at:
176+
```
177+
http://localhost:8180/realms/hawk/protocol/saml/descriptor
178+
```
179+
180+
This contains all technical details about the IdP configuration.
181+
182+
## Files
183+
184+
Files are located in `api/test/integration/keycloak/`:
185+
186+
- `import/hawk-realm.json` - Keycloak realm configuration
187+
- `setup.sh` - Automated setup script
188+
189+
## Advanced Configuration
190+
191+
### Custom Workspace ID
192+
193+
To test with a different workspace ID, update the ACS URL in the Keycloak Admin Console:
194+
195+
1. Go to Clients → hawk-sp
196+
2. Update `saml_assertion_consumer_url_post` attribute
197+
3. Save changes
198+
199+
### Additional Users
200+
201+
You can add more users through:
202+
- Keycloak Admin Console → Users → Add User
203+
- Or update `api/test/integration/keycloak/import/hawk-realm.json` and re-import
204+
205+
### Different Port
206+
207+
If you need to run Keycloak on a different port:
208+
209+
1. Update `KC_HTTP_PORT` in `docker-compose.yml`
210+
2. Update port mapping in `docker-compose.yml`
211+
3. Update all URLs in this README
212+
4. Update `api/test/integration/keycloak/import/hawk-realm.json` with new URLs

‎test/integration/cases/sso.test.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -524,6 +524,6 @@ describe('SSO Integration Tests', () => {
524524
* browser automation (puppeteer/playwright) is needed
525525
*
526526
* Manual Testing:
527-
* - See keycloak/README.md for manual testing instructions
527+
* - See docs/Keycloak.md for manual testing instructions
528528
* - Use Keycloak admin console to view test users and SAML configuration
529529
*/

0 commit comments

Comments
 (0)