feat: Add validation for user identity provider (#183)

Problem
When assigning  non-existent identity provider, Keycloak returns
a 409 Conflict error. This error message is confusing and doesn't
clearly indicate that the root cause is a missing identity provider.
Change
Added explicit identity provider existence validation before
attempting to create user federated identity to prevent confusing
409 Conflict errors and provide clearer error messages.

Author: zmotso

api/v1/keycloakrealmuser_types.go

@@ -83,7 +83,7 @@ type KeycloakRealmUserSpec struct {
 	// +optional
 	PasswordSecret PasswordSecret `json:"passwordSecret,omitempty"`
 
-	// IdentityProviders linked to the user.
+	// IdentityProviders is a list of identity providers aliases linked to the user.
 	// +nullable
 	// +optional
 	IdentityProviders *[]string `json:"identityProviders,omitempty"`

config/crd/bases/v1.edp.epam.com_keycloakrealmusers.yaml

@@ -88,7 +88,8 @@ spec:
                 nullable: true
                 type: array
               identityProviders:
-                description: IdentityProviders linked to the user.
+                description: IdentityProviders is a list of identity providers aliases
+                  linked to the user.
                 items:
                   type: string
                 nullable: true

deploy-templates/_crd_examples/keycloakrealmidentityprovider.yaml

@@ -5,7 +5,7 @@ metadata:
 spec:
   realmRef:
     kind: KeycloakRealm
-    name: realm
+    name: keycloakrealm-sample
   alias: instagram
   authenticateByDefault: false
   enabled: true

deploy-templates/crds/v1.edp.epam.com_keycloakrealmusers.yaml

@@ -88,7 +88,8 @@ spec:
                 nullable: true
                 type: array
               identityProviders:
-                description: IdentityProviders linked to the user.
+                description: IdentityProviders is a list of identity providers aliases
+                  linked to the user.
                 items:
                   type: string
                 nullable: true

keycloakrealmidentityproviders.v1.edp.epam.com-keycloakrealmidentityprovider-sample.yaml

@@ -0,0 +1,39 @@
+apiVersion: v1.edp.epam.com/v1
+kind: KeycloakRealmIdentityProvider
+metadata:
+  annotations:
+    kubectl.kubernetes.io/last-applied-configuration: |
+      {"apiVersion":"v1.edp.epam.com/v1","kind":"KeycloakRealmIdentityProvider","metadata":{"annotations":{},"name":"keycloakrealmidentityprovider-sample","namespace":"default"},"spec":{"alias":"instagram","authenticateByDefault":false,"config":{"clientId":"foo","clientSecret":"$secretName:secretKey","hideOnLoginPage":"true","syncMode":"IMPORT","useJwksUrl":"true"},"enabled":true,"firstBrokerLoginFlowAlias":"first broker login","mappers":[{"config":{"attribute":"foo","attribute.value":"bar","syncMode":"IMPORT"},"identityProviderAlias":"instagram","identityProviderMapper":"hardcoded-attribute-idp-mapper","name":"test-33221"}],"providerId":"instagram","realmRef":{"kind":"KeycloakRealm","name":"realm"}}}
+  creationTimestamp: "2025-07-03T08:50:19Z"
+  generation: 1
+  name: keycloakrealmidentityprovider-sample
+  namespace: default
+  resourceVersion: "84034"
+  uid: e646f1ba-4665-47bf-9eae-6f79d64e78dd
+spec:
+  alias: instagram
+  authenticateByDefault: false
+  config:
+    clientId: foo
+    clientSecret: $secretName:secretKey
+    hideOnLoginPage: "true"
+    syncMode: IMPORT
+    useJwksUrl: "true"
+  enabled: true
+  firstBrokerLoginFlowAlias: first broker login
+  mappers:
+  - config:
+      attribute: foo
+      attribute.value: bar
+      syncMode: IMPORT
+    identityProviderAlias: instagram
+    identityProviderMapper: hardcoded-attribute-idp-mapper
+    name: test-33221
+  providerId: instagram
+  realmRef:
+    kind: KeycloakRealm
+    name: keycloakrealm-sample
+status:
+  failureCount: 6
+  value: 'unable to create keycloak client from realm ref: unable to get realm: KeycloakRealm.v1.edp.epam.com
+    "realm" not found'

pkg/client/keycloak/adapter/gocloak_adapter_user.go

@@ -448,6 +448,15 @@ func (a GoCloakAdapter) addMissingIdentityProviders(
 			continue
 		}
 
+		exists, err := a.IdentityProviderExists(ctx, realmName, provider)
+		if err != nil {
+			return fmt.Errorf("unable to check if identity provider exists: %w", err)
+		}
+
+		if !exists {
+			return fmt.Errorf("identity provider %s does not exist", provider)
+		}
+
 		federatedIdentity := gocloak.FederatedIdentityRepresentation{
 			IdentityProvider: &provider,
 			UserID:           &userID,

pkg/client/keycloak/adapter/gocloak_adapter_user_test.go

@@ -32,6 +32,22 @@ func TestGoCloakAdapter_SyncRealmUser(t *testing.T) {
 			return
 		}
 
+		if strings.Contains(r.URL.Path, "identity-provider/instances/idp1") {
+			w.WriteHeader(http.StatusOK)
+			_, err := w.Write([]byte(`{"alias":"idp1"}`))
+			assert.NoError(t, err)
+
+			return
+		}
+
+		if strings.Contains(r.URL.Path, "identity-provider/instances/non-existent-idp") {
+			w.WriteHeader(http.StatusNotFound)
+			_, err := w.Write([]byte(`{"error":"idp not found"}`))
+			assert.NoError(t, err)
+
+			return
+		}
+
 		w.WriteHeader(http.StatusOK)
 	}))
 
@@ -381,6 +397,79 @@ func TestGoCloakAdapter_SyncRealmUser(t *testing.T) {
 				assert.Contains(t, err.Error(), "failed to get user")
 			},
 		},
+		{
+			name: "identity provider does not exist",
+			userDto: &KeycloakUser{
+				Username:            "user",
+				Enabled:             true,
+				EmailVerified:       true,
+				Email:               "mail@mail.com",
+				FirstName:           "first-name",
+				LastName:            "last-name",
+				RequiredUserActions: []string{"change-password"},
+				Roles:               []string{"role1"},
+				Groups:              []string{"group1"},
+				Attributes:          map[string]string{"attr1": "attr1value"},
+				Password:            "password",
+				IdentityProviders:   &[]string{"non-existent-idp"},
+			},
+			client: func(t *testing.T) *mocks.MockGoCloak {
+				m := mocks.NewMockGoCloak(t)
+
+				m.On("GetUsers", mock.Anything, "", "realm", mock.Anything).
+					Return(nil, nil)
+				m.On("CreateUser",
+					mock.Anything,
+					"",
+					"realm",
+					mock.MatchedBy(func(user gocloak.User) bool {
+						return assert.Equal(t, "user", *user.Username)
+					})).
+					Return("user-id", nil)
+				m.On("GetRoleMappingByUserID", mock.Anything, "", "realm", "user-id").
+					Return(&gocloak.MappingsRepresentation{
+						RealmMappings:  &[]gocloak.Role{},
+						ClientMappings: map[string]*gocloak.ClientMappingsRepresentation{},
+					}, nil)
+				m.On("GetRealmRole", mock.Anything, "", "realm", "role1").
+					Return(&gocloak.Role{
+						Name: gocloak.StringP("role1"),
+						ID:   gocloak.StringP("role1-id"),
+					}, nil)
+				m.On("AddRealmRoleToUser",
+					mock.Anything,
+					"",
+					"realm",
+					"user-id",
+					mock.MatchedBy(func(roles []gocloak.Role) bool {
+						return assert.Len(t, roles, 1) &&
+							assert.Equal(t, "role1-id", *roles[0].ID)
+					})).
+					Return(nil)
+				m.On("GetGroups",
+					mock.Anything,
+					"",
+					"realm",
+					mock.Anything).
+					Return([]*gocloak.Group{{
+						Name: gocloak.StringP("group1"),
+						ID:   gocloak.StringP("group1-id"),
+					}}, nil)
+				m.On("RestyClient").Return(resty.New())
+				m.On("GetUserFederatedIdentities",
+					mock.Anything,
+					"",
+					"realm",
+					"user-id").
+					Return([]*gocloak.FederatedIdentityRepresentation{}, nil)
+
+				return m
+			},
+			wantErr: func(t require.TestingT, err error, i ...interface{}) {
+				require.Error(t, err)
+				assert.Contains(t, err.Error(), "identity provider non-existent-idp does not exist")
+			},
+		},
 	}
 
 	for _, tt := range tests {