Support Custom Subject Mapping via Webhook for OAuth2 Flows

[tongium]

Preflight checklist

• I could not find a solution in the existing issues, docs, nor discussions.
• I agree to follow this project's Code of Conduct.
• I have read and am following this repository's Contribution Guidelines.
• I have joined the Ory Community Slack.
• I am signed up to the Ory Security Patch Newsletter.

Ory Network Project

No response

Describe your problem

While Ory Kratos provides excellent support for identity migration via external_id and standard pairwise subject identifiers, some complex migration scenarios require dynamic logic.

Specifically, when a legacy system uses a custom pairwise algorithm that varies per OAuth2 client, a static mapping is insufficient. Currently, Kratos is limited to using the Internal Identity ID or a pre-defined External ID, which makes it difficult to maintain backward compatibility for specialized subject (sub) requirements.

Describe your ideal solution

Add a subject_hook to the oauth2_provider configuration. This hook would trigger during the login acceptance flow, sending the identity context and the login challenge to an external service. The external service would then return the desired subject identifier.

Example Configuration:

oauth2_provider:
  url: http://hydra-admin.internal
  subject_hook:
    enabled: true
    config:
      url: http://hook-sever.internal
      body: "file:///etc/config/subject-hook.jsonet"

Expected Webhook Response:

The hook should return the mapping between the Kratos Identity and the custom identifier:

{
  "identity_id": "abc",
  "obfuscated_id": "xyz"
}

Implementation Logic

When the hook is enabled and returns a successful response, Kratos would use the obfuscated_id to set the ForceSubjectIdentifier when communicating with Hydra:

alr := hydraclientgo.NewAcceptOAuth2LoginRequest(params.IdentityID)
if params.ObfuscatedID != "" {
    alr.ForceSubjectIdentifier = &params.ObfuscatedID
}

Workarounds or alternatives

Add server between Kratos and Hydra to modify AcceptOAuth2LoginRequest body

oauth2_provider:
  url: http://custom-server.internal

Version

v25.4.0

Additional Context

No response