feat: Annotate users when givenName and familyName are identical

When signing up via GitHub with a single-word display name, the identity
provider populates both givenName and familyName with the same value.
Front-end clients have no way to detect this situation and prompt the
user to correct their profile.

The user controller now reconciles the
`iam.miloapis.com/name-review-required` annotation on every reconcile
loop: it is added when givenName equals familyName (and both are
non-empty), and removed automatically once they differ. The annotation
key is exported as a typed constant in user_types.go with inline
documentation describing its semantics and usage.

Co-Authored-By: Claude <claude@anthropic.com>

Author: JoseSzycho

internal/controllers/iam/user_controller.go

@@ -71,6 +71,12 @@ func (r *UserController) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.
 		return ctrl.Result{}, err
 	}
 
+	// Reconcile the name-review annotation based on whether givenName and familyName match
+	if err := r.reconcileNameReviewAnnotation(ctx, user); err != nil {
+		log.Error(err, "Failed to reconcile name review annotation")
+		return ctrl.Result{}, err
+	}
+
 	// Determine desired state based on existence of any UserDeactivation for this user
 	var udList iamv1alpha1.UserDeactivationList
 	if err := r.Client.List(ctx, &udList, client.MatchingFields{"spec.userRef.name": user.Name}); err != nil {
@@ -131,6 +137,40 @@ func (r *UserController) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.
 	return ctrl.Result{}, nil
 }
 
+// reconcileNameReviewAnnotation adds or removes the name-review-required annotation depending on
+// whether givenName and familyName are identical. This situation arises when an identity provider
+// (e.g. GitHub) supplies a single display name and the system copies it into both fields.
+func (r *UserController) reconcileNameReviewAnnotation(ctx context.Context, user *iamv1alpha1.User) error {
+	log := log.FromContext(ctx).WithName("reconcile-name-review-annotation")
+
+	annotations := user.GetAnnotations()
+	_, annotationPresent := annotations[iamv1alpha1.UserNameReviewRequiredAnnotation]
+	namesAreEqual := user.Spec.GivenName != "" && user.Spec.GivenName == user.Spec.FamilyName
+
+	switch {
+	case namesAreEqual && !annotationPresent:
+		if annotations == nil {
+			annotations = map[string]string{}
+		}
+		annotations[iamv1alpha1.UserNameReviewRequiredAnnotation] = "true"
+		user.SetAnnotations(annotations)
+		if err := r.Client.Update(ctx, user); err != nil {
+			return fmt.Errorf("failed to add name-review annotation: %w", err)
+		}
+		log.Info("Added name-review-required annotation", "user", user.Name)
+
+	case !namesAreEqual && annotationPresent:
+		delete(annotations, iamv1alpha1.UserNameReviewRequiredAnnotation)
+		user.SetAnnotations(annotations)
+		if err := r.Client.Update(ctx, user); err != nil {
+			return fmt.Errorf("failed to remove name-review annotation: %w", err)
+		}
+		log.Info("Removed name-review-required annotation", "user", user.Name)
+	}
+
+	return nil
+}
+
 // ensureOwnerReferences ensures that PolicyBinding and UserPreference resources have proper owner references
 func (r *UserController) ensureOwnerReferences(ctx context.Context, user *iamv1alpha1.User) error {
 	log := log.FromContext(ctx).WithName("ensure-owner-references")

pkg/apis/iam/v1alpha1/user_types.go

@@ -130,3 +130,23 @@ const (
 	AuthProviderGitHub AuthProvider = "github"
 	AuthProviderGoogle AuthProvider = "google"
 )
+
+const (
+	// UserNameReviewRequiredAnnotation is set on a User when givenName and familyName are
+	// identical, which typically happens when the identity provider (e.g. GitHub) supplies
+	// only a single display name and the system splits it across both fields.
+	//
+	// Presence of this annotation signals that the user has not yet provided distinct given
+	// and family names. Front-end clients should prompt the user to review and update their
+	// profile when this annotation is present.
+	//
+	// The annotation value is always "true". The annotation is removed automatically by the
+	// user controller once givenName and familyName differ.
+	//
+	// Example:
+	//
+	//   metadata:
+	//     annotations:
+	//       iam.miloapis.com/name-review-required: "true"
+	UserNameReviewRequiredAnnotation = "iam.miloapis.com/name-review-required"
+)