NOTE: this application and repository was created with the assistance of ChatGPT. The "context.sh" builds scripts you can run past ChatGPT 4o and build up a context to ask questions.
This project is a SAML authentication system integrating Keycloak, .NET 8 Web API (net8saml), and a React frontend (reactsaml). It provides Single Sign-On (SSO) using SAML 2.0 and supports session management, user authentication, and secure communication between components.
- Keycloak (Identity Provider - IdP): Manages authentication and issues SAML assertions.
- .NET 8 Web API (
net8saml): Handles SAML authentication callbacks, user sessions, and provides API endpoints. - React + Vite Frontend (
reactsaml): Acts as the UI for users, interacting with the backend for authentication and data display.
- The React frontend redirects users to Keycloak's SAML login page.
- Keycloak authenticates users and returns a SAML assertion to the .NET backend.
- The .NET API validates the assertion, creates a session, and provides authenticated API access.
- The React frontend communicates with the backend to retrieve user session data.
cd keycloak
bash build.shThis builds the Keycloak Docker image and pushes it to the container registry.
bash create.shThis starts a Keycloak container on port 8080.
bash configure.shThis script:
- Creates a new realm (
mycompany). - Registers a SAML client (
net8saml). - Configures SAML authentication settings.
- Creates a test user (
shawnz) and group (net8saml_admins).
Install .NET 8:
cd net8saml
dotnet restore
dotnet buildThis compiles the .NET Web API.
Ensure the SAML settings are correctly configured in appsettings.json:
"SAML": {
"IdpSsoUrl": "http://localhost:8080/realms/mycompany/protocol/saml",
"EntityId": "net8saml",
"AssertionConsumerServiceUrl": "http://localhost:5000/api/auth/callback",
"PrivateKeyPath": "../private-key-pkcs8.pem"
}cd keycloak
bash certs.shThis script:
- Extracts the SAML signing certificate and private key from Keycloak.
- Saves them as
private-key.pemandpublic-cert.pem. - Converts the private key to PKCS8 format (
private-key-pkcs8.pem).
Ensure the backend API references these files in appsettings.json.
cd reactsaml
npm installEdit .env:
echo "VITE_API_BASE_URL=http://localhost:5000" > reactsaml/.envnpm run buildThis generates the production build in reactsaml/dist, which is served by the .NET Web API.
cd reactsaml
npm run devThis runs the React app at http://localhost:5000, pointing to the backend API at http://localhost:5000.
cd net8saml
dotnet runThis starts the API at http://localhost:5000.
- Keycloak Admin Console: http://localhost:8080 (Username:
admin, Password:admin) - React Frontend: http://localhost:500 (Username:
shawnz, Password:Shawn123) - Backend API: http://localhost:5000/swagger (Swagger UI)
| Endpoint | Method | Description |
|---|---|---|
/api/auth/login |
GET |
Redirects user to Keycloak SSO. |
/api/auth/callback |
POST |
Handles SAML authentication response. |
/api/debug |
GET |
Returns session data for debugging. |
/api/user/hello |
GET |
Returns "Hello {user}" message. |
This project provides a secure and scalable authentication solution using SAML with Keycloak, .NET 8, and React. You can now deploy and extend it based on your authentication and authorization needs.
🚀 Happy Coding!