feat: use subject_source pattern for OAuth2 provider subject

Replace `use_external_id` boolean config with `subject_source` enum to
match the existing tokenizer pattern. The new config accepts:
- "id" (default): Use identity ID as OAuth2 subject
- "external_id": Use identity's external_id as OAuth2 subject

Returns an error when `subject_source` is set to "external_id" but the
identity's external_id is unset, ensuring predictable behavior and
making it easier to identify which ID was used.

This aligns the OAuth2 provider configuration with the session
tokenizer implementation for consistency across the codebase.

Closes #4528

Author: Micaso

driver/config/config.go

@@ -192,7 +192,7 @@ const (
 	ViperKeyOAuth2ProviderURL                                = "oauth2_provider.url"
 	ViperKeyOAuth2ProviderHeader                             = "oauth2_provider.headers"
 	ViperKeyOAuth2ProviderOverrideReturnTo                   = "oauth2_provider.override_return_to"
-	ViperKeyOAuth2ProviderUseExternalID                      = "oauth2_provider.use_external_id"
+	ViperKeyOAuth2ProviderSubjectSource                      = "oauth2_provider.subject_source"
 	ViperKeyClientHTTPNoPrivateIPRanges                      = "clients.http.disallow_private_ip_ranges"
 	ViperKeyClientHTTPPrivateIPExceptionURLs                 = "clients.http.private_ip_exception_urls"
 	ViperKeyWebhookHeaderAllowlist                           = "clients.web_hook.header_allowlist"
@@ -961,8 +961,8 @@ func (p *Config) OAuth2ProviderOverrideReturnTo(ctx context.Context) bool {
 	return p.GetProvider(ctx).Bool(ViperKeyOAuth2ProviderOverrideReturnTo)
 }
 
-func (p *Config) OAuth2ProviderUseExternalID(ctx context.Context) bool {
-	return p.GetProvider(ctx).Bool(ViperKeyOAuth2ProviderUseExternalID)
+func (p *Config) OAuth2ProviderSubjectSource(ctx context.Context) string {
+	return p.GetProvider(ctx).String(ViperKeyOAuth2ProviderSubjectSource)
 }
 
 func (p *Config) OAuth2ProviderURL(ctx context.Context) *url.URL {

driver/config/config_test.go

@@ -1299,15 +1299,15 @@ func TestOAuth2Provider(t *testing.T) {
 		assert.Equal(t, "https://oauth2_provider/", conf.OAuth2ProviderURL(ctx).String())
 		assert.Equal(t, http.Header{"Authorization": {"Basic"}}, conf.OAuth2ProviderHeader(ctx))
 		assert.True(t, conf.OAuth2ProviderOverrideReturnTo(ctx))
-		assert.True(t, conf.OAuth2ProviderUseExternalID(ctx))
+		assert.Equal(t, "external_id", conf.OAuth2ProviderSubjectSource(ctx))
 	})
 
 	t.Run("case=defaults", func(t *testing.T) {
 		conf, _ := config.New(ctx, logrusx.New("", ""), os.Stderr, &contextx.Default{}, configx.SkipValidation())
 		assert.Empty(t, conf.OAuth2ProviderURL(ctx))
 		assert.Empty(t, conf.OAuth2ProviderHeader(ctx))
 		assert.False(t, conf.OAuth2ProviderOverrideReturnTo(ctx))
-		assert.False(t, conf.OAuth2ProviderUseExternalID(ctx))
+		assert.Equal(t, "id", conf.OAuth2ProviderSubjectSource(ctx))
 	})
 }
 

driver/config/stub/.kratos.oauth2_provider.yaml

@@ -3,4 +3,4 @@ oauth2_provider:
   headers:
     Authorization: Basic
   override_return_to: true
-  use_external_id: true
+  subject_source: external_id

embedx/config.schema.json

@@ -2286,11 +2286,12 @@
           "default": false,
           "description": "Override the return_to query parameter with the OAuth2 provider request URL when perfoming an OAuth2 login flow."
         },
-        "use_external_id": {
-          "title": "Use external_id as subject",
-          "type": "boolean",
-          "default": false,
-          "description": "If set, the external_id of the identity will be used as the subject in the OAuth2 login request. If no external_id is set, the identity ID will be used."
+        "subject_source": {
+          "title": "Subject source for OAuth2 login",
+          "type": "string",
+          "enum": ["id", "external_id"],
+          "default": "id",
+          "description": "Determines which identifier to use as the subject in OAuth2 login requests. Can be either 'id' (identity ID, default) or 'external_id' (identity's external ID). If 'external_id' is selected but not set on the identity, an error will be returned."
         }
       },
       "additionalProperties": false

hydra/fake.go

@@ -20,9 +20,10 @@ const (
 var ErrFakeAcceptLoginRequestFailed = errors.New("failed to accept login request")
 
 type FakeHydra struct {
-	Skip       bool
-	RequestURL string
-	params     []AcceptLoginRequestParams
+	Skip          bool
+	RequestURL    string
+	SubjectSource string
+	params        []AcceptLoginRequestParams
 }
 
 func (h *FakeHydra) Params() []AcceptLoginRequestParams {
@@ -42,6 +43,19 @@ func (h *FakeHydra) AcceptLoginRequest(_ context.Context, params AcceptLoginRequ
 	if params.SessionID == "" {
 		return "", errors.New("session id must not be empty")
 	}
+
+	// Validate subject source just like DefaultHydra does
+	switch h.SubjectSource {
+	case "", "id":
+		// Use identity ID - no validation needed
+	case "external_id":
+		if params.ExternalID == "" {
+			return "", herodot.ErrBadRequest.WithReasonf("The identity does not have an external ID set, but it is required for the OAuth2 provider subject.")
+		}
+	default:
+		return "", herodot.ErrBadRequest.WithReasonf("Unknown OAuth2 provider subject source %q", h.SubjectSource)
+	}
+
 	switch params.LoginChallenge {
 	case FakeInvalidLoginChallenge:
 		return "", ErrFakeAcceptLoginRequestFailed

hydra/hydra.go

@@ -94,9 +94,17 @@ func (h *DefaultHydra) AcceptLoginRequest(ctx context.Context, params AcceptLogi
 	remember := h.d.Config().SessionPersistentCookie(ctx)
 	rememberFor := int64(h.d.Config().SessionLifespan(ctx) / time.Second)
 
-	subject := params.IdentityID
-	if h.d.Config().OAuth2ProviderUseExternalID(ctx) && params.ExternalID != "" {
+	var subject string
+	switch h.d.Config().OAuth2ProviderSubjectSource(ctx) {
+	case "", "id":
+		subject = params.IdentityID
+	case "external_id":
+		if params.ExternalID == "" {
+			return "", errors.WithStack(herodot.ErrBadRequest.WithReasonf("The identity does not have an external ID set, but it is required for the OAuth2 provider subject."))
+		}
 		subject = params.ExternalID
+	default:
+		return "", errors.WithStack(herodot.ErrBadRequest.WithReasonf("Unknown OAuth2 provider subject source %q", h.d.Config().OAuth2ProviderSubjectSource(ctx)))
 	}
 
 	alr := hydraclientgo.NewAcceptOAuth2LoginRequest(subject)

selfservice/flow/login/hook_external_id_test.go

@@ -44,8 +44,9 @@ func TestLoginExecutorWithExternalID(t *testing.T) {
 	}
 	require.NoError(t, reg.Persister().CreateIdentity(ctx, i))
 
-	t.Run("case=use_external_id=false", func(t *testing.T) {
-		conf.MustSet(ctx, config.ViperKeyOAuth2ProviderUseExternalID, false)
+	t.Run("case=subject_source=id", func(t *testing.T) {
+		conf.MustSet(ctx, config.ViperKeyOAuth2ProviderSubjectSource, "id")
+		fakeHydra.SubjectSource = "id"
 		loginFlow, err := login.NewFlow(conf, time.Minute, hydra.FakeValidLoginChallenge, &http.Request{URL: &url.URL{Path: "/", RawQuery: "login_challenge=" + hydra.FakeValidLoginChallenge}}, flow.TypeBrowser)
 		require.NoError(t, err)
 		loginFlow.OAuth2LoginChallenge = hydra.FakeValidLoginChallenge
@@ -63,8 +64,9 @@ func TestLoginExecutorWithExternalID(t *testing.T) {
 		assert.Equal(t, "external-id", fakeHydra.Params()[0].ExternalID)
 	})
 
-	t.Run("case=use_external_id=true", func(t *testing.T) {
-		conf.MustSet(ctx, config.ViperKeyOAuth2ProviderUseExternalID, true)
+	t.Run("case=subject_source=external_id", func(t *testing.T) {
+		conf.MustSet(ctx, config.ViperKeyOAuth2ProviderSubjectSource, "external_id")
+		fakeHydra.SubjectSource = "external_id"
 		loginFlow, err := login.NewFlow(conf, time.Minute, hydra.FakeValidLoginChallenge, &http.Request{URL: &url.URL{Path: "/", RawQuery: "login_challenge=" + hydra.FakeValidLoginChallenge}}, flow.TypeBrowser)
 		require.NoError(t, err)
 		loginFlow.OAuth2LoginChallenge = hydra.FakeValidLoginChallenge
@@ -85,4 +87,27 @@ func TestLoginExecutorWithExternalID(t *testing.T) {
 		assert.Equal(t, i.ID.String(), lastParams.IdentityID)
 		assert.Equal(t, "external-id", lastParams.ExternalID)
 	})
+
+	t.Run("case=subject_source=external_id without external_id set", func(t *testing.T) {
+		iWithoutExtID := &identity.Identity{
+			ID:       uuid.Must(uuid.NewV4()),
+			SchemaID: config.DefaultIdentityTraitsSchemaID,
+			State:    identity.StateActive,
+		}
+		require.NoError(t, reg.Persister().CreateIdentity(ctx, iWithoutExtID))
+
+		conf.MustSet(ctx, config.ViperKeyOAuth2ProviderSubjectSource, "external_id")
+		fakeHydra.SubjectSource = "external_id"
+		loginFlow, err := login.NewFlow(conf, time.Minute, hydra.FakeValidLoginChallenge, &http.Request{URL: &url.URL{Path: "/", RawQuery: "login_challenge=" + hydra.FakeValidLoginChallenge}}, flow.TypeBrowser)
+		require.NoError(t, err)
+		loginFlow.OAuth2LoginChallenge = hydra.FakeValidLoginChallenge
+
+		w := httptest.NewRecorder()
+		r := &http.Request{URL: &url.URL{Path: "/login/post"}}
+		sess := session.NewInactiveSession()
+		sess.CompletedLoginFor(identity.CredentialsTypePassword, identity.AuthenticatorAssuranceLevel1)
+
+		err = reg.LoginHookExecutor().PostLoginHook(w, r, identity.CredentialsTypePassword.ToUiNodeGroup(), loginFlow, iWithoutExtID, sess, "")
+		require.Error(t, err)
+	})
 }