chore: add guidance for external_id in tokenizer (#2414)

Author: jonas-jonas

docs/identities/session-to-jwt-cors.mdx

@@ -114,13 +114,13 @@ session:
   whoami:
     tokenizer:
       templates:
-      jwt_template_1:
-        jwks_url: base64://... # A JSON Web Key Set (required)
-        claims_mapper_url: base64://... # A JsonNet template for modifying the claims
-        ttl: 1m # 1 minute (defaults to 10 minutes)
-        subject_source: id # (optional, defaults to id, other option: external_id if you're using `external_id` on identities)
-      another_jwt_template:
-        jwks_url: base64://... # A JSON Web Key Set
+        jwt_template_1:
+          jwks_url: base64://... # A JSON Web Key Set (required)
+          claims_mapper_url: base64://... # A JsonNet template for modifying the claims
+          ttl: 1m # 1 minute (defaults to 10 minutes)
+          subject_source: id # (optional, defaults to id, other option: external_id if you're using `external_id` on identities)
+        another_jwt_template:
+          jwks_url: base64://... # A JSON Web Key Set
 ```
 
 ### JSON Web Token claim mapper
@@ -220,3 +220,17 @@ If the key set contains more than one key, the first key in the list will be use
   ],
 }
 ```
+
+### Handling `external_id` in the JWT sub claim
+
+If your identities use `external_id`, set `subject_source` to `external_id` in the tokenizer template to populate the JWT sub
+claim with that value.
+
+Tokenization will fail if `subject_source` is set to `external_id` but an identity is missing `external_id`. This is a security
+measure that prevents issuing tokens with the same sub claim for different identities, since identity IDs and `external_id` values
+are only guaranteed to be unique within their own namespaces, not across both.
+
+To avoid this, configure a webhook to automatically set `external_id` for new identities (for example using the same ID generation
+logic as your previous system).
+
+After migration, you can switch to using Ory identity IDs and set `subject_source` back to `id`.

docs/kratos/manage-identities/60_external-id.mdx

@@ -34,7 +34,7 @@ create or update identities.
 
 Do not add `external_id` to your identity schema definition. It is handled separately by Ory Kratos internally.
 
-### Use `external_id` in JWT `sub` claim
+### Use `external_id` in tokenized session JWTs `sub` claim
 
 Set the `subject_source` to `external_id` in the tokenization config:
 
@@ -43,15 +43,17 @@ session:
   whoami:
     tokenizer:
       templates:
-      jwt_template_1:
-        jwks_url: base64://... # A JSON Web Key Set (required)
-        claims_mapper_url: base64://... # A JsonNet template for modifying the claims
-        ttl: 1m # 1 minute (defaults to 10 minutes)
-        subject_source: external_id
-      another_jwt_template:
-        jwks_url: base64://... # A JSON Web Key Set
+        jwt_template_1:
+          jwks_url: base64://... # A JSON Web Key Set (required)
+          claims_mapper_url: base64://... # A JsonNet template for modifying the claims
+          ttl: 1m # 1 minute (defaults to 10 minutes)
+          subject_source: external_id
+        another_jwt_template:
+          jwks_url: base64://... # A JSON Web Key Set
 ```
 
+Read more about [session tokenization here](../../identities/session-to-jwt-cors.mdx).
+
 This will populate the `sub` claim in JWTs with the value of `external_id`.
 
 If `external_id` is not set for a user when `subject_source` is `external_id`, tokenization will fail.