SAML Login Workflow - Testing Guide¶

Overview¶

This guide provides step-by-step instructions to test the complete SAML authentication workflow.

Prerequisites¶

✅ Keycloak running on http://keycloak:8080
✅ Bank USSD realm created with test users
✅ Backend API running on http://localhost/api/v1/auth
✅ Frontend running on http://localhost:5173 or http://localhost

Test Users in Keycloak¶

Username	Password	Role	Branch	Email
admin.keycloak	admin123	admin	london	admin@keycloak.local
john.smith	password123	staff	london	john.smith@bank.local
sarah.jones	password123	customers	manchester	sarah.jones@bank.local
bob.wilson	password123	operators	newcastle	bob.wilson@bank.local
emma.davis	password123	agents	birmingham	emma.davis@bank.local

Test 1: Verify SAML Configuration¶

1.1 Check SAML Configuration in Database¶

# Connect to PostgreSQL
docker exec bank_ussd-postgres-1 psql -U bank_ussd -d db_6 -c "SELECT * FROM auth.saml_config LIMIT 1;"

Expected Output:

 sp_entity_id | acs_url | slo_url | idp_entity_id | idp_sso_url | idp_x509cert | nameid_format

1.2 Verify Keycloak SAML Client¶

Navigate to: http://keycloak:8080/admin - Login: admin / admin123 - Navigate to: Realms → bank-ussd → Clients → bank-ussd-saml - Verify: - ✅ SAML Client is enabled - ✅ Valid Redirect URIs configured - ✅ Protocol Mappers set up (email, firstName, lastName, branch, role)

Test 2: Get SAML Metadata¶

2.1 Retrieve SP Metadata¶

curl -X GET http://localhost/api/v1/auth/saml/metadata \
  -H "Accept: application/xml"

Expected Response: - HTTP 200 with XML containing: - <EntityDescriptor> with SP details - <KeyDescriptor> for signing - <AssertionConsumerService> pointing to /api/v1/auth/saml/acs - <SingleLogoutService> pointing to /api/v1/auth/saml/sls

2.2 Test Metadata POST Method¶

curl -X POST http://localhost/api/v1/auth/saml/metadata \
  -H "Accept: application/xml"

3.1 Run the Test Suite¶

cd backend
python test_saml_workflow.py

This will verify: - ✅ Keycloak health - ✅ Realm configuration - ✅ SAML config in database - ✅ SAML settings generation - ✅ Metadata generation - ✅ Backend connectivity

Navigate to: http://localhost/ (or http://localhost:5173 for dev)
You should see the login form

4.2 Username Validation (Step 1)¶

Enter username: john.smith
Click "Next" or "Validate"
Expected:
✅ Geolocation permission requested (if policy requires it)
✅ Username validated
✅ Policy validation shows SAML as approved method
✅ Transition to password/SAML login

Click "SAML Login" or similar button
You will be redirected to Keycloak login: http://keycloak:8080/auth/realms/bank-ussd/protocol/saml
Login with:
Username: john.smith
Password: password123
Accept consent screen if prompted
You will be redirected back to: http://localhost/api/v1/auth/saml/acs
Keycloak will POST SAML response to ACS endpoint

4.4 User Provisioning (JIT)¶

Expected behavior after SAML response: - If user doesn't exist in database: Create user with SAML attributes - Extract from SAML assertion: - Username/Email - First Name, Last Name - Branch (from SAML attributes) - Roles (from SAML groups/roles) - Link to SAML IdP - Create database record

4.5 Session Creation¶

After ACS processing: - ✅ Session created in user_sessions table - ✅ Session history recorded in session_history table - ✅ Access token generated - ✅ Refresh token generated - ✅ User redirected to dashboard

Check browser console for user info

Verify in database:

docker exec bank_ussd-postgres-1 psql -U bank_ussd -d db_6 \
  -c "SELECT * FROM users.users WHERE username='john.smith';"

Check session:

docker exec bank_ussd-postgres-1 psql -U bank_ussd -d db_6 \
  -c "SELECT * FROM auth.user_sessions ORDER BY created_at DESC LIMIT 1;"

Test 5: Multiple User Tests¶

5.1 Test Admin User¶

Username: admin.keycloak
Password: admin123
Expected: Logged in with admin role

5.2 Test Different Branches¶

Test sarah.jones (manchester branch)
Test bob.wilson (newcastle/operators)
Test emma.davis (birmingham/agents)
Verify branch is correctly linked in database

5.3 Test New User Creation¶

Add new user in Keycloak directly (without prior database record)
Login with new credentials
Verify:
✅ User created in database
✅ Correct attributes extracted
✅ Roles assigned
✅ Branch linked

Test 6: Edge Cases¶

6.1 Invalid SAML Response¶

Tamper with SAML response and try ACS
Expected: HTTP 401 or 403 with error details

6.2 Disabled User¶

In Keycloak, disable the user
Try to login
Expected: HTTP 403 "User account is locked"

6.3 Logout¶

After successful login, navigate to /api/v1/auth/logout
Verify:
✅ Session ended
✅ Tokens invalidated
✅ Cookie cleared

Debugging Tips¶

Enable Debug Logging¶

# Add to backend/.env
LOGLEVEL=DEBUG
SAML_DEBUG=1

Check SAML Request/Response¶

Install SAML Tracer browser extension
Monitor SAML request and response
Verify signature and encryption

Keycloak Admin Console¶

Check user attributes: Realms → bank-ussd → Users
Verify assigned roles
Check token content

Database Queries¶

-- Check SAML config
SELECT * FROM auth.saml_config;

-- Check users created via SAML
SELECT * FROM users.users WHERE idp_provider = 'SAML';

-- Check IdP links
SELECT * FROM auth.ldap_saml_links WHERE idp_provider = 'SAML';

-- Check sessions
SELECT * FROM auth.user_sessions ORDER BY created_at DESC;

Expected Workflow Summary¶

1. User → Login Page
2. User enters username: john.smith
3. Frontend calls: POST /validate
   ↓
4. Backend validates username + checks policy
5. Policy says: SAML (based on user/geo/time)
   ↓
6. Frontend shows: SAML Login button
7. User clicks SAML Login
   ↓
8. Frontend calls: POST /saml/login
9. Backend generates SAML request
10. User redirected to Keycloak
    ↓
11. User authenticates in Keycloak
12. Keycloak generates SAML response
13. Browser POSTs response to /saml/acs
    ↓
14. Backend processes SAML response
15. Extract user attributes
16. Create or find user in database
17. Link SAML IdP
18. Create session
19. Generate tokens
    ↓
20. Return Token response
21. Frontend stores tokens
22. Redirect to dashboard
    ↓
23. User is authenticated!

Troubleshooting¶

SAML Config Not Found¶

Run: python setup_saml.py in backend
Or manually insert in database

Keycloak Not Accessible¶

Ensure Docker container is running: docker ps | grep keycloak
Check logs: docker logs keycloak
Verify network: docker network ls

Check backend logs for JIT provisioning errors
Verify SAML attributes are being extracted
Check if user already exists by email

SAML Response Errors¶

Verify certificate/signature
Check SAML response expiry
Ensure ACS URL matches Keycloak configuration

Success Criteria¶

✅ All test cases pass
✅ Users can login via SAML
✅ Users are created automatically (JIT)
✅ Roles and branches are correctly assigned
✅ Sessions are created and tracked
✅ Logout works correctly
✅ No errors in backend logs
✅ Database records are created properly