add saml support (tested with okta saml)

docs/configuration/providers/saml/index.md

@@ -67,7 +67,7 @@ openssl req -new -x509 -key saml.key -out saml.cert -days 365 \
 
 1. **Register Service Provider**: Add your agent as a Service Provider in your IdP
 2. **Configure Entity ID**: Use your chosen entity ID (e.g., `https://your-app.example.com/saml/metadata`)
-3. **Set Assertion Consumer Service**: Configure ACS URL (e.g., `https://your-app.example.com/saml/acs`)
+3. **Set Assertion Consumer Service**: Configure ACS URL (e.g., `https://your-app.example.com/api/v1/auth/callback/{provider-name}`), replacing `{provider-name}` with the key you use for this provider (e.g., `company-saml`)
 4. **Upload Certificate**: Upload your public certificate to the IdP
 
 ## Example Configurations

examples/providers/saml.example.yaml

@@ -11,7 +11,7 @@ providers:
       idp_metadata_url: "https://your-idp.example.com/saml/metadata"
 
       # Required: Entity ID for this service provider
-      entity_id: "https://your-app.example.com/saml/metadata"
+      entity_id: "https://your-app.example.com/saml/sp"
 
       # Required: Root URL of your application
       root_url: "https://your-app.example.com"

internal/config/providers.go

@@ -23,6 +23,7 @@ import (
 	_ "github.com/thand-io/agent/internal/providers/oauth2.google"
 	_ "github.com/thand-io/agent/internal/providers/okta"
 	_ "github.com/thand-io/agent/internal/providers/salesforce"
+	_ "github.com/thand-io/agent/internal/providers/saml"
 	_ "github.com/thand-io/agent/internal/providers/slack"
 	_ "github.com/thand-io/agent/internal/providers/terraform"
 	_ "github.com/thand-io/agent/internal/providers/thand"

internal/daemon/auth.go

@@ -15,6 +15,21 @@ import (
 	"github.com/thand-io/agent/internal/models"
 )
 
+// Authentication Callback Handlers
+//
+// This file implements two separate callback handlers:
+//
+// 1. getAuthCallback() - OAuth2 GET callbacks
+//    - Expects state and code in query parameters
+//    - Used by OAuth2 providers (GitHub, Google, etc.)
+//
+// 2. postAuthCallback() - SAML POST callbacks
+//    - Expects RelayState and SAMLResponse in form parameters
+//    - Supports SP-initiated (with RelayState) and IdP-initiated (no RelayState)
+//    - Used by SAML providers (Okta, Azure AD, etc.)
+//
+// Both handlers delegate to getAuthCallbackPage() for session creation.
+
 // getAuthRequest initiates the authentication flow
 //
 //	@Summary		Initiate authentication
@@ -42,9 +57,28 @@ func (s *Server) getAuthRequest(c *gin.Context) {
 
 	config := s.GetConfig()
 
-	if len(callback) > 0 && strings.Compare(callback, config.GetLoginServerUrl()) == 0 {
-		s.getErrorPage(c, http.StatusBadRequest, "Callback cannot be the login server")
-		return
+	// Validate callback URL to prevent infinite loops
+	// Only block callbacks that would loop back to the auth request endpoint
+	if len(callback) > 0 {
+		callbackURL, callbackErr := url.Parse(callback)
+		loginServerURL, loginServerErr := url.Parse(config.GetLoginServerUrl())
+
+		if callbackErr == nil && loginServerErr == nil {
+			// Block if it's the same host and the callback would loop back to auth endpoints
+			if callbackURL.Host == loginServerURL.Host &&
+				(strings.HasPrefix(callbackURL.Path, "/api/v1/auth/request") ||
+					strings.HasPrefix(callbackURL.Path, "/api/v1/auth/callback")) {
+				s.getErrorPage(c, http.StatusBadRequest, "Callback cannot be the auth request or callback endpoint - this would create an infinite loop")
+				return
+			}
+		} else {
+			// If we can't parse the URLs, log the error but allow the request to proceed
+			logrus.WithFields(logrus.Fields{
+				"callback":       callback,
+				"callbackErr":    callbackErr,
+				"loginServerErr": loginServerErr,
+			}).Warnln("Failed to parse callback or login server URL for validation")
+		}
 	}
 
 	logrus.WithFields(logrus.Fields{
@@ -63,22 +97,29 @@ func (s *Server) getAuthRequest(c *gin.Context) {
 
 	client := common.GetClientIdentifier()
 
+	encodedState := models.EncodingWrapper{
+		Type: models.ENCODED_AUTH,
+		Data: models.NewAuthWrapper(
+			callback,        // where are we returning to
+			client.String(), // server identifier
+			provider,        // provider name
+			code,            // the code sent by the client
+		),
+	}.EncodeAndEncrypt(
+		s.Config.GetServices().GetEncryption(),
+	)
+
+	logrus.WithFields(logrus.Fields{
+		"encodedState": encodedState,
+		"stateLength":  len(encodedState),
+	}).Debugln("Encoded state for auth request")
+
 	authResponse, err := providerConfig.GetClient().AuthorizeSession(
 		context.Background(),
 		// This creates the state payload for the auth request
 		&models.AuthorizeUser{
-			Scopes: []string{"email", "profile"},
-			State: models.EncodingWrapper{
-				Type: models.ENCODED_AUTH,
-				Data: models.NewAuthWrapper(
-					callback,        // where are we returning to
-					client.String(), // server identifier
-					provider,        // provider name
-					code,            // the code sent by the client
-				),
-			}.EncodeAndEncrypt(
-				s.Config.GetServices().GetEncryption(),
-			),
+			Scopes:      []string{"email", "profile"},
+			State:       encodedState,
 			RedirectUri: s.GetConfig().GetAuthCallbackUrl(provider),
 		},
 	)
@@ -94,9 +135,9 @@ func (s *Server) getAuthRequest(c *gin.Context) {
 	)
 }
 
-// getAuthCallback handles the OAuth2 callback
+// getAuthCallback handles OAuth2 GET callback requests
 //
-//	@Summary		Authentication callback
+//	@Summary		OAuth2 authentication callback
 //	@Description	Handle the OAuth2 callback from the provider
 //	@Tags			auth
 //	@Accept			json
@@ -108,34 +149,126 @@ func (s *Server) getAuthRequest(c *gin.Context) {
 //	@Failure		400			{object}	map[string]any	"Bad request"
 //	@Router			/auth/callback/{provider} [get]
 func (s *Server) getAuthCallback(c *gin.Context) {
+	// OAuth2 flow: state and code come in query parameters (GET)
+	state := c.Query("state")
 
-	// Handle the callback to the CLI to store the users session state
+	// Debug logging
+	logrus.WithFields(logrus.Fields{
+		"method": c.Request.Method,
+		"state":  state,
+	}).Debugln("OAuth2 callback parameters")
 
-	// Check if the callback is a workflow resumption or
-	// a local callback response
+	// Validate state parameter is required for OAuth2
+	if len(state) == 0 {
+		s.getErrorPage(c, http.StatusBadRequest, "State is required for OAuth2 flow")
+		return
+	}
 
-	state := c.Query("state")
+	// Decode and decrypt state
+	decoded, err := s.decodeState(state)
+	if err != nil {
+		s.getErrorPage(c, http.StatusBadRequest, "Invalid state", err)
+		return
+	}
 
-	if len(state) == 0 {
-		s.getErrorPage(c, http.StatusBadRequest, "State is required")
+	// Process decoded state
+	s.processDecodedState(c, decoded)
+}
+
+// postAuthCallback handles SAML POST callback requests
+//
+//	@Summary		SAML authentication callback
+//	@Description	Handle the SAML POST callback from the provider
+//	@Tags			auth
+//	@Accept			x-www-form-urlencoded
+//	@Produce		json
+//	@Param			provider		path		string	true	"Provider name"
+//	@Param			RelayState		formData	string	false	"SAML RelayState (SP-initiated)"
+//	@Param			SAMLResponse	formData	string	true	"SAML Response"
+//	@Success		200				"Authentication successful"
+//	@Failure		400				{object}	map[string]any	"Bad request"
+//	@Router			/auth/callback/{provider} [post]
+func (s *Server) postAuthCallback(c *gin.Context) {
+	// SAML flow: RelayState and SAMLResponse come in form parameters (POST)
+	relayState := c.PostForm("RelayState")
+	samlResponse := c.PostForm("SAMLResponse")
+
+	// Debug logging
+	logrus.WithFields(logrus.Fields{
+		"method":       c.Request.Method,
+		"relay_state":  relayState,
+		"has_response": len(samlResponse) > 0,
+	}).Debugln("SAML callback parameters")
+
+	// Handle IdP-initiated SAML flow (no RelayState parameter)
+	if len(relayState) == 0 {
+		// Check if this is a SAML callback with SAMLResponse
+		if len(samlResponse) > 0 {
+			// IdP-initiated flow: validate provider allows this
+			providerName := c.Param("provider")
+
+			// Get provider config to verify IdP-initiated is allowed
+			_, err := s.GetConfig().GetProviderByName(providerName)
+			if err != nil {
+				logrus.WithFields(logrus.Fields{
+					"provider": providerName,
+					"error":    err,
+				}).Warn("Provider not found for IdP-initiated SAML flow")
+				s.getErrorPage(c, http.StatusBadRequest, "Provider not configured")
+				return
+			}
+
+			// Security logging for IdP-initiated flows (for audit/monitoring)
+			logrus.WithFields(logrus.Fields{
+				"provider":   providerName,
+				"source_ip":  c.ClientIP(),
+				"user_agent": c.Request.UserAgent(),
+			}).Info("Processing IdP-initiated SAML authentication - verify this is expected")
+
+			authWrapper := models.AuthWrapper{
+				Callback: "", // No callback for IdP-initiated
+				Provider: providerName,
+				Code:     "", // No client code
+				Client:   "", // No client identifier
+			}
+			s.getAuthCallbackPage(c, authWrapper)
+			return
+		}
+
+		// Not a SAML IdP-initiated flow, RelayState is required
+		s.getErrorPage(c, http.StatusBadRequest, "RelayState is required for SP-initiated SAML flow")
+		return
+	}
+
+	// SP-initiated flow: decode and decrypt RelayState
+	decoded, err := s.decodeState(relayState)
+	if err != nil {
+		s.getErrorPage(c, http.StatusBadRequest, "Invalid RelayState", err)
 		return
 	}
 
+	// Process decoded state
+	s.processDecodedState(c, decoded)
+}
+
+// decodeState decodes and decrypts the state parameter
+func (s *Server) decodeState(state string) (models.EncodingWrapper, error) {
 	decoded, err := models.EncodingWrapper{}.DecodeAndDecrypt(
 		state,
 		s.Config.GetServices().GetEncryption(),
 	)
-
 	if err != nil {
-		s.getErrorPage(c, http.StatusBadRequest, "Invalid state", err)
-		return
+		return models.EncodingWrapper{}, fmt.Errorf("failed to decode state: %w", err)
 	}
+	return *decoded, nil
+}
 
+// processDecodedState routes based on decoded state type
+func (s *Server) processDecodedState(c *gin.Context, decoded models.EncodingWrapper) {
 	switch decoded.Type {
 	case models.ENCODED_WORKFLOW_TASK:
 		s.getElevateAuthOAuth2(c)
 	case models.ENCODED_AUTH:
-
 		authWrapper := models.AuthWrapper{}
 		err := common.ConvertMapToInterface(
 			decoded.Data.(map[string]any), &authWrapper)
@@ -146,7 +279,6 @@ func (s *Server) getAuthCallback(c *gin.Context) {
 		}
 
 		s.getAuthCallbackPage(c, authWrapper)
-
 	default:
 		s.getErrorPage(c, http.StatusBadRequest, "Invalid state type")
 	}
@@ -251,8 +383,17 @@ func (s *Server) getAuthCallbackPage(c *gin.Context, auth models.AuthWrapper) {
 		return
 	}
 
+	// For OAuth2: state and code come in query parameters (GET)
+	// For SAML: RelayState and SAMLResponse come in form parameters (POST)
 	state := c.Query("state")
+	if len(state) == 0 {
+		state = c.PostForm("RelayState")
+	}
+
 	code := c.Query("code") // This is the code from the provider - not the client
+	if len(code) == 0 {
+		code = c.PostForm("SAMLResponse")
+	}
 
 	session, err := provider.GetClient().CreateSession(c, &models.AuthorizeUser{
 		State:       state,
@@ -292,7 +433,8 @@ func (s *Server) getAuthCallbackPage(c *gin.Context, auth models.AuthWrapper) {
 	}
 
 	if len(auth.Callback) == 0 {
-		c.Redirect(http.StatusTemporaryRedirect, "/")
+		// Use 303 See Other to force a GET redirect from the POST callback
+		c.Redirect(http.StatusSeeOther, "/")
 	} else {
 		s.renderHtml(c, "auth_callback.html", data)
 	}

internal/daemon/server.go

@@ -435,7 +435,8 @@ func (s *Server) setupRoutes(router *gin.Engine) {
 			api.GET("/sync", s.getSync)
 
 			api.GET("/auth/request/:provider", s.getAuthRequest)
-			api.GET("/auth/callback/:provider", s.getAuthCallback)
+			api.GET("/auth/callback/:provider", s.getAuthCallback)   // OAuth2 callbacks
+			api.POST("/auth/callback/:provider", s.postAuthCallback) // SAML callbacks
 			api.GET("/auth/logout/:provider", s.getLogoutPage)
 			api.GET("/auth/logout", s.getLogoutPage)