Commit changes before merging to main
This commit is contained in:
salirezav
199
docs/UGA_SSO_Integration_Guide.md
Normal file
199
docs/UGA_SSO_Integration_Guide.md
Normal file
@@ -0,0 +1,199 @@
|
||||
# UGA SSO Integration Guide
|
||||
|
||||
## Overview
|
||||
|
||||
The University of Georgia (UGA) uses **Central Authentication Service (CAS)** for Single Sign-On (SSO) authentication. This allows users to log in to multiple applications using their MyID and password, with optional two-factor authentication via ArchPass (powered by Duo).
|
||||
|
||||
## Current Authentication System
|
||||
|
||||
The dashboard currently uses **Supabase** for authentication with email/password login. The authentication is implemented in:
|
||||
- `management-dashboard-web-app/src/components/Login.tsx` - Login form component
|
||||
- `management-dashboard-web-app/src/lib/supabase.ts` - Supabase client and user management
|
||||
- `management-dashboard-web-app/src/App.tsx` - Authentication state management
|
||||
|
||||
## UGA SSO Integration Process
|
||||
|
||||
### Step 1: Submit SSO Integration Request
|
||||
|
||||
**Action Required:** Submit the official UGA SSO Integration Request form to UGA's Enterprise Information Technology Services (EITS).
|
||||
|
||||
**Resources:**
|
||||
- **SSO Integration Request Form:** https://eits.uga.edu/access_and_security/uga_sso/moving_to_uga_sso/sso_integration_request/
|
||||
- **UGA SSO Information Page:** https://eits.uga.edu/access_and_security/uga_sso/
|
||||
- **What is CAS?** https://eits.uga.edu/access_and_security/new_cas/what_is_cas/
|
||||
|
||||
The integration request form collects essential information about your application and initiates the security review process.
|
||||
|
||||
### Step 2: Security Review
|
||||
|
||||
After submitting the request, UGA's **Office of Information Security** will contact you to:
|
||||
- Arrange security testing of your application
|
||||
- Ensure your application meets UGA's security standards
|
||||
- Provide guidance on security requirements
|
||||
|
||||
**Note:** This is a mandatory step before your application can be integrated with UGA SSO.
|
||||
|
||||
### Step 3: Technical Support
|
||||
|
||||
For technical assistance during the integration process:
|
||||
- **Request UGA SSO Support:** Submit a request through EITS
|
||||
- **Community CAS Support:** Available on the UGA SSO page
|
||||
- **Developer Tools:** Additional resources available on the UGA SSO page
|
||||
|
||||
## Technical Considerations
|
||||
|
||||
### CAS Authentication Flow
|
||||
|
||||
CAS (Central Authentication Service) typically follows this flow:
|
||||
1. User attempts to access the application
|
||||
2. Application redirects to CAS login page
|
||||
3. User authenticates with MyID and password
|
||||
4. CAS validates credentials (may require ArchPass/2FA)
|
||||
5. CAS redirects back to application with a service ticket
|
||||
6. Application validates ticket with CAS server
|
||||
7. Application creates session for authenticated user
|
||||
|
||||
### Implementation Options
|
||||
|
||||
#### Option 1: Backend Proxy Approach (Recommended)
|
||||
- Implement CAS authentication on the backend (API server)
|
||||
- Frontend redirects to backend CAS endpoint
|
||||
- Backend handles CAS ticket validation
|
||||
- Backend creates Supabase session or JWT token
|
||||
- Frontend receives authentication token
|
||||
|
||||
**Pros:**
|
||||
- Keeps CAS credentials secure on backend
|
||||
- Can integrate with existing Supabase auth
|
||||
- Better security model
|
||||
|
||||
#### Option 2: Frontend CAS Client Library
|
||||
- Use a JavaScript CAS client library in the React app
|
||||
- Handle CAS redirect flow in the browser
|
||||
- Exchange ticket for user information
|
||||
|
||||
**Pros:**
|
||||
- Simpler initial implementation
|
||||
- Direct integration in frontend
|
||||
|
||||
**Cons:**
|
||||
- Requires exposing CAS service URL
|
||||
- May need backend validation anyway
|
||||
|
||||
### CAS Client Libraries
|
||||
|
||||
For JavaScript/TypeScript implementations, consider:
|
||||
- **cas-client** (npm) - CAS client for Node.js
|
||||
- **passport-cas** - Passport.js strategy for CAS
|
||||
- Custom implementation using CAS REST API
|
||||
|
||||
### Integration with Supabase
|
||||
|
||||
You have several options for integrating CAS with your existing Supabase setup:
|
||||
|
||||
1. **CAS → Supabase User Mapping:**
|
||||
- After CAS authentication, create/update Supabase user
|
||||
- Map CAS user attributes (email, MyID) to Supabase user
|
||||
- Use Supabase session for application access
|
||||
|
||||
2. **Hybrid Authentication:**
|
||||
- Support both CAS (UGA users) and email/password (external users)
|
||||
- Allow users to choose authentication method
|
||||
|
||||
3. **CAS-Only Authentication:**
|
||||
- Replace Supabase auth entirely with CAS
|
||||
- Use CAS session management
|
||||
- Store user data in Supabase but authenticate via CAS
|
||||
|
||||
## Key Information Needed from UGA
|
||||
|
||||
After submitting your integration request, you'll need to obtain:
|
||||
|
||||
1. **CAS Server URL** - The UGA CAS server endpoint
|
||||
2. **Service URL** - Your application's callback URL
|
||||
3. **CAS Protocol Version** - Which CAS protocol version UGA uses (CAS 2.0, CAS 3.0, etc.)
|
||||
4. **User Attributes** - What user information is returned (email, MyID, name, etc.)
|
||||
5. **Certificate/Validation Method** - How to validate CAS tickets
|
||||
6. **Two-Factor Authentication Requirements** - Whether ArchPass is required
|
||||
|
||||
## Two-Factor Authentication
|
||||
|
||||
UGA uses **ArchPass** (powered by Duo) for two-factor authentication. Depending on your application's security requirements:
|
||||
- Users may be required to complete 2FA during login
|
||||
- This is typically handled automatically by the CAS server
|
||||
- No additional implementation needed on your end
|
||||
|
||||
## Identity Federation
|
||||
|
||||
UGA supports **Identity Federation**, which allows:
|
||||
- Users from other organizations to access your application
|
||||
- Collaborative research projects across institutions
|
||||
- Single set of credentials for multiple applications
|
||||
|
||||
If you need federated identity support, mention this in your integration request.
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Immediate Actions:**
|
||||
- [ ] Submit the UGA SSO Integration Request form
|
||||
- [ ] Prepare application information (description, URL, security details)
|
||||
- [ ] Review current authentication implementation
|
||||
|
||||
2. **While Waiting for Approval:**
|
||||
- [ ] Research CAS client libraries for your tech stack
|
||||
- [ ] Design integration architecture (backend vs frontend)
|
||||
- [ ] Plan user data mapping (CAS attributes → Supabase users)
|
||||
- [ ] Consider hybrid authentication approach
|
||||
|
||||
3. **After Approval:**
|
||||
- [ ] Obtain CAS server details from UGA EITS
|
||||
- [ ] Implement CAS authentication flow
|
||||
- [ ] Test with UGA test accounts
|
||||
- [ ] Complete security review process
|
||||
- [ ] Deploy to production
|
||||
|
||||
## Resources
|
||||
|
||||
### UGA Official Resources
|
||||
- **UGA SSO Main Page:** https://eits.uga.edu/access_and_security/uga_sso/
|
||||
- **SSO Integration Request:** https://eits.uga.edu/access_and_security/uga_sso/moving_to_uga_sso/sso_integration_request/
|
||||
- **What is CAS?** https://eits.uga.edu/access_and_security/new_cas/what_is_cas/
|
||||
- **Request UGA SSO Support:** Available through EITS portal
|
||||
|
||||
### CAS Documentation
|
||||
- **Apereo CAS Documentation:** https://apereo.github.io/cas/
|
||||
- **CAS Protocol Specification:** https://apereo.github.io/cas/development/protocol/CAS-Protocol-Specification.html
|
||||
|
||||
### Technical References
|
||||
- **CAS REST API:** For programmatic CAS integration
|
||||
- **CAS Client Libraries:** Search npm for "cas-client" or "passport-cas"
|
||||
- **Supabase Auth Documentation:** For integrating external auth providers
|
||||
|
||||
## Questions to Ask UGA EITS
|
||||
|
||||
When you receive contact from UGA's Office of Information Security, consider asking:
|
||||
|
||||
1. What is the CAS server URL for production?
|
||||
2. What CAS protocol version should we use?
|
||||
3. What user attributes are available in the CAS response?
|
||||
4. Is ArchPass (2FA) required for our application?
|
||||
5. What is the expected service URL format?
|
||||
6. Are there any specific security requirements we should be aware of?
|
||||
7. Is there a test/staging CAS environment for development?
|
||||
8. What is the expected timeline for the integration process?
|
||||
|
||||
## Notes
|
||||
|
||||
- The integration process requires official approval from UGA EITS
|
||||
- Security review is mandatory and may take some time
|
||||
- You may need to modify your application's security configuration
|
||||
- Consider maintaining backward compatibility with existing users during transition
|
||||
- Document the integration process for future maintenance
|
||||
|
||||
---
|
||||
|
||||
**Last Updated:** Based on research conducted in 2024
|
||||
**Contact:** UGA EITS for official documentation and support
|
||||
|
||||
|
||||
|
||||
Reference in New Issue
Block a user