Skip to content

SAML Implementation - Verification Checklist

Infrastructure Setup

  • [x] PostgreSQL running with keycloak_db created
  • [x] Keycloak running on port 8080
  • [x] Keycloak realm "bank-ussd" imported
  • [x] Keycloak SAML client configured
  • [x] Backend application ready
  • [x] nginx reverse proxy configured
  • [ ] Backend container running

Keycloak Configuration

  • [x] Realm: bank-ussd created
  • [x] SAML Client: bank-ussd-saml configured
  • [x] Valid Redirect URIs:
  • http://localhost:8000/api/v1/auth/saml/acs
  • http://localhost:8000/api/v1/auth/saml/sls
  • http://localhost:80/api/v1/auth/saml/acs
  • http://localhost:80/api/v1/auth/saml/sls
  • [x] Protocol Mappers configured:
  • email
  • firstName
  • lastName
  • branch
  • role
  • [x] Test users created (5 users in 4 branches)
  • [x] Realm roles created (admin, staff, customers, operators, agents)

Backend SAML Implementation

  • [x] SAML configuration model (models/auth.py)
  • [x] SAML controller functions (controller/auth.py):
  • _saml_config() - Load SAML settings
  • build_saml_auth() - Create SAML auth object
  • get_saml_config() - Fetch from database
  • upsert_saml_config() - Create/update config
  • [x] SAML endpoints (routers/auth.py):
  • GET/POST /saml/metadata - SAML metadata endpoint
  • POST /saml/login - Initiate SAML login
  • POST /saml/acs - Assertion Consumer Service
  • POST /saml/sls - Single Logout Service
  • [x] SAML authentication flow integration
  • [x] JIT user provisioning with SAML attributes
  • [x] Role and branch mapping from SAML
  • [x] Session creation and token generation

Database Setup

  • [x] SAML config table created with environment variables populated:
  • SP Entity ID: http://localhost/api/v1/auth/saml/metadata
  • ACS URL: http://localhost/api/v1/auth/saml/acs
  • SLS URL: http://localhost/api/v1/auth/saml/sls
  • IdP Entity ID: http://keycloak:8080/auth/realms/bank-ussd
  • IdP SSO URL: http://keycloak:8080/auth/realms/bank-ussd/protocol/saml
  • [x] init-keycloak.sql script creates keycloak_db
  • [ ] Test user records created via SAML JIT

Frontend Integration

  • [x] Login form updated for SAML flow
  • [x] Username validation step (detectsapproved method)
  • [x] SAML login button/option when SAML detected
  • [x] Geolocation capture for policy validation
  • [x] Redirect to Keycloak when SAML selected
  • [x] Handle SAML response and create session
  • [x] Store tokens and redirect to dashboard

Environment Configuration

  • [x] .env updated with SAML settings:
  • SAML_ENABLED=1
  • SAML_SP_ENTITY_ID=http://localhost/api/v1/auth/saml/metadata
  • SAML_ACS_URL=http://localhost/api/v1/auth/saml/acs
  • SAML_SLS_URL=http://localhost/api/v1/auth/saml/sls
  • SAML_IDP_ENTITY_ID=http://keycloak:8080/auth/realms/bank-ussd
  • SAML_IDP_SSO_URL=http://keycloak:8080/auth/realms/bank-ussd/protocol/saml
  • [x] docker-compose.yml includes Keycloak service
  • [x] Keycloak auto-imports realm config on startup

Documentation

  • [x] SAML implementation checklist
  • [x] SAML testing guide
  • [x] SAML setup summary
  • [x] SAML workflow documentation
  • [x] SAML API reference
  • [x] LDAP/SAML workflow guide

Testing Checklist

Pre-Test Verification

  • [ ] Start all services: docker-compose -f compose.dev.yml up -d
  • [ ] Wait for Keycloak to be ready (check logs)
  • [ ] Verify backend is accessible: curl http://localhost/api/v1/auth/saml/metadata
  • [ ] Check database SAML config: SELECT * FROM auth.saml_config;

Test 1: Metadata Endpoint

  • [ ] GET http://localhost/api/v1/auth/saml/metadata
  • [ ] Verify XML response contains EntityDescriptor
  • [ ] Verify ACS URL is correct
  • [ ] POST method also works

Test 2: Login Initiation

  • [ ] POST http://localhost/api/v1/auth/saml/login
  • [ ] Verify redirect URL to Keycloak is returned
  • [ ] Verify URL contains SAMLRequest parameter

Test 3: Keycloak Login

  • [ ] Navigate to Keycloak login URL
  • [ ] Login with john.smith / password123
  • [ ] Redirect back to ACS endpoint with SAML response

Test 4: ACS Processing

  • [ ] SAML response is processed
  • [ ] User is extracted from SAML attributes
  • [ ] JIT user creation (if first time)
  • [ ] Roles/branches assigned correctly
  • [ ] Session created
  • [ ] Token generated and returned

Test 5: Session Validation

  • [ ] Check user_sessions table has new session
  • [ ] Check user is linked to SAML IdP
  • [ ] Verify token contains correct permissions
  • [ ] Verify branch attribute is set

Test 6: Dashboard Access

  • [ ] User is redirected to dashboard
  • [ ] All user data is available
  • [ ] Permissions and actions are correct
  • [ ] Dashboard loads without errors

Test 7: Multiple Users

  • [ ] Test admin.keycloak (admin role)
  • [ ] Test sarah.jones (manchester branch)
  • [ ] Test bob.wilson (operator role)
  • [ ] Test emma.davis (agent role)

Test 8: Logout

  • [ ] User clicks logout
  • [ ] Session is terminated
  • [ ] Redirect to login page
  • [ ] Cannot access dashboard with old token

Known Limitations

  1. Certificate Management: Currently no certificate validation. For production:
  2. Fetch and validate Keycloak's X.509 certificate
  3. Implement certificate pinning

  4. Handle certificate rotation

  5. Metadata Caching:

  6. Metadata is generated on each request

  7. For large scale, implement caching

  8. Assertion Encryption:

  9. Currently SAML assertions are signed but not encrypted

  10. Enable encryption for production

  11. Attribute Mapping:

  12. Fixed attribute mapping from Keycloak
  13. Could be made configurable

Next Steps

  1. Run Integration Tests: python test_saml_workflow.py
  2. Manual Testing: Follow SAML_TESTING_GUIDE.md
  3. Production Deployment: Update certificate and encryption settings
  4. Monitor: Add logging for SAML events
  5. Performance: Load test SAML login flow

Support & Debugging

Enable Debug Logging: 

# In controller/auth.py
logging.basicConfig(level=logging.DEBUG)

SAML Debugging Tools: - Browser: SAML Tracer extension - Command line: OneLogin SAML tools - Logs: Check backend and Keycloak logs

Verification Commands: 

# Check keycloak_db exists
docker exec postgres psql -U bank_ussd -d db_6 -c "\l" | grep keycloak

# Check SAML config
docker exec postgres psql -U bank_ussd -d db_6 -c "SELECT * FROM auth.saml_config;"

# Check users created via SAML
docker exec postgres psql -U bank_ussd -d db_6 \
  -c "SELECT u.username, l.idp_provider FROM users.users u LEFT JOIN auth.ldap_saml_links l ON u.id = l.user_id;"

# Check Keycloak realm
docker exec keycloak curl -X GET http://localhost:8080/auth/realms/bank-ussd

Status Summary

✅ SAML implementation is COMPLETE and READY for testing

Component Status Notes
Keycloak Setup ✅ Complete Realm and users configured
Database ✅ Complete SAML config and keycloak_db ready
Backend API ✅ Complete All endpoints implemented
Frontend ✅ Complete SAML login flow integrated
Documentation ✅ Complete Comprehensive guides provided
Testing 🟡 In Progress Ready for manual/automated tests
Production Ready ⚠️ Pending Needs certificate/encryption setup

Last Updated: April 7, 2026 Status: Ready for Testing