feat(saml): allow setting nameid-format and alternative mapping for transient format (#7979)

# Which Problems Are Solved

ZITADEL currently always uses
`urn:oasis:names:tc:SAML:2.0:nameid-format:persistent` in SAML requests,
relying on the IdP to respect that flag and always return a peristent
nameid in order to be able to map the external user with an existing
user (idp link) in ZITADEL.
In case the IdP however returns a
`urn:oasis:names:tc:SAML:2.0:nameid-format:transient` (transient)
nameid, the attribute will differ between each request and it will not
be possible to match existing users.

# How the Problems Are Solved

This PR adds the following two options on SAML IdP:
- **nameIDFormat**: allows to set the nameid-format used in the SAML
Request
- **transientMappingAttributeName**: allows to set an attribute name,
which will be used instead of the nameid itself in case the returned
nameid-format is transient

# Additional Changes

To reduce impact on current installations, the `idp_templates6_saml`
table is altered with the two added columns by a setup job. New
installations will automatically get the table with the two columns
directly.
All idp unit tests are updated to use `expectEventstore` instead of the
deprecated `eventstoreExpect`.

# Additional Context

Closes #7483
Closes #7743

---------

Co-authored-by: peintnermax <max@caos.ch>
Co-authored-by: Stefan Benz <46600784+stebenz@users.noreply.github.com>

internal/idp/providers/saml/session.go

@@ -17,8 +17,9 @@ var _ idp.Session = (*Session)(nil)
 
 // Session is the [idp.Session] implementation for the SAML provider.
 type Session struct {
-	ServiceProvider *samlsp.Middleware
-	state           string
+	ServiceProvider               *samlsp.Middleware
+	state                         string
+	TransientMappingAttributeName string
 
 	RequestID string
 	Request   *http.Request
@@ -26,6 +27,19 @@ type Session struct {
 	Assertion *saml.Assertion
 }
 
+func NewSession(provider *Provider, requestID string, request *http.Request) (*Session, error) {
+	sp, err := provider.GetSP()
+	if err != nil {
+		return nil, err
+	}
+	return &Session{
+		ServiceProvider:               sp,
+		TransientMappingAttributeName: provider.TransientMappingAttributeName(),
+		RequestID:                     requestID,
+		Request:                       request,
+	}, nil
+}
+
 // GetAuth implements the [idp.Session] interface.
 func (s *Session) GetAuth(ctx context.Context) (string, bool) {
 	url, _ := url.Parse(s.state)
@@ -56,8 +70,17 @@ func (s *Session) FetchUser(ctx context.Context) (user idp.User, err error) {
 		return nil, zerrors.ThrowInvalidArgument(err, "SAML-nuo0vphhh9", "Errors.Intent.ResponseInvalid")
 	}
 
+	nameID := s.Assertion.Subject.NameID
 	userMapper := NewUser()
-	userMapper.SetID(s.Assertion.Subject.NameID)
+	// use the nameID as default mapping id
+	userMapper.SetID(nameID.Value)
+	if nameID.Format == string(saml.TransientNameIDFormat) {
+		mappingID, err := s.transientMappingID()
+		if err != nil {
+			return nil, err
+		}
+		userMapper.SetID(mappingID)
+	}
 	for _, statement := range s.Assertion.AttributeStatements {
 		for _, attribute := range statement.Attributes {
 			values := make([]string, len(attribute.Values))
@@ -70,6 +93,21 @@ func (s *Session) FetchUser(ctx context.Context) (user idp.User, err error) {
 	return userMapper, nil
 }
 
+func (s *Session) transientMappingID() (string, error) {
+	for _, statement := range s.Assertion.AttributeStatements {
+		for _, attribute := range statement.Attributes {
+			if attribute.Name != s.TransientMappingAttributeName {
+				continue
+			}
+			if len(attribute.Values) != 1 {
+				return "", zerrors.ThrowInvalidArgument(nil, "SAML-Soij4", "Errors.Intent.MissingSingleMappingAttribute")
+			}
+			return attribute.Values[0].Value, nil
+		}
+	}
+	return "", zerrors.ThrowInvalidArgument(nil, "SAML-swwg2", "Errors.Intent.MissingSingleMappingAttribute")
+}
+
 type TempResponseWriter struct {
 	header  http.Header
 	content *bytes.Buffer