An application can authenticate a user without receiving their real email address. The important design question is how the application recognizes that user on the next visit and what information it needs to keep.
With OIDC, associate a local user with the validated issuer and subject: iss and sub. Treat email as separately shared profile information. Sudomimus also scopes the subject to a sector, so applications in different sectors receive different identifiers for the same account.
Use the validated issuer and subject as the identity key
iss identifies the OIDC issuer. sub identifies the user within that issuer’s identity model. Together they identify the external identity your application accepts. The OIDC claim stability rules specify this pair as the user identifier; email and display names do not provide the same guarantees.
Your application can keep its own local user ID and store a unique association with the exact (issuer, subject) pair. Obtain those values only after your OIDC library has validated the login result, including the expected issuer, audience, signature, expiry, and nonce when used. Decoding a JWT payload alone does not validate it.
Treat the subject as opaque. Do not parse it to infer an account ID, organization, email, or permission. If you fetch UserInfo, verify that its sub matches the subject from the validated ID Token before attaching the returned information to the local user.
| Value | Application use |
|---|---|
Validated iss and sub |
Associate the external identity with a local user. |
email |
Use as contact information only when its source and verification meet the application’s needs. |
given_name, family_name, or picture |
Present profile information when available and permitted. |
| Local user ID | Associate the application’s projects, preferences, and business permissions with its user record. |
Keep email changes separate from user identity
Consider a user who signs in to a task application and later changes their primary email. While their Sudomimus sector subject remains unchanged, the application should find the same local user through iss and sub. A changed email is a profile update, not a reason to create a second task account.
Email can also be absent because the user did not grant sharing, or it can contain a generated placeholder under the application’s policy. Even a verified address is not a permanent user identifier. email_verified describes verification of an email address; it does not turn that address into the subject.
Do not automatically merge two external identities because their email values match. Such a match does not prove that a newly authenticated identity may access an existing local account.
Understand the sector boundary
Sudomimus uses pairwise subjects. A sector groups applications that intentionally share a user’s external identifier. Applications in the same sector see the same subject for that user. Applications in different sectors receive unrelated subjects. The internal account UUID is never exposed to applications.
For example, a company may place its task board and project wiki in one sector, while an unrelated community application uses another:
| Application | Sector | Subject for the same person |
|---|---|---|
| Task board | Company workspace | subject-A |
| Project wiki | Company workspace | subject-A |
| Community forum | Community | subject-B |
These subject labels are illustrative, not actual token values. The task board and wiki can recognize the same external identity by design. The forum cannot establish that relationship by comparing its subject with theirs.
Sector membership does not share business permissions or consent. The wiki still owns its document permissions, and a grant to share email with the task board does not authorize sharing it with the wiki. See pairwise identity and organizations and sectors for the configuration model.
Pairwise subjects and claim sharing work together
Different subjects limit correlation through the identifier. If two applications also receive the same real email address, they can still compare that address. A shared name or account avatar can also reveal information. Pairwise subjects do not make users anonymous.
Sudomimus therefore evaluates identity disclosure separately for each application. Real information requires a policy that permits it, the user’s grant, and available account data. OIDC also requires the relevant scope. For example, the email scope alone does not override a user’s decision or an application’s synthetic-only policy.
Choose the policy according to the application’s need:
- Use
OFFwhen the application does not need a field. - Use
SYNTHETIC_ONLYwhen a sector-scoped placeholder is sufficient. - Use
OPTIONALwhen the user can decline and the application can handle an omitted value. - Use
SYNTHETIC_FALLBACKwhen the application can use a placeholder until real sharing is granted. - Use
REQUIREDonly when real information is necessary to complete sign-in or refresh.
Synthetic email addresses use proxy.sudomimus.email and carry email_verified: false. They are placeholders, not verified recovery addresses. Mail delivery is not guaranteed; do not depend on them for notifications or account recovery. Synthetic values are scoped to the sector, while permission to share real values remains specific to each application.
The identity claims guide explains the full policy model. For an unexpected response, follow OIDC sign-in succeeded, but the email claim is missing.
Account for deliberate identity changes
A Sudomimus subject remains consistent across ordinary logins in the same sector. A user can deliberately rotate that sector subject. Moving an application to another sector also changes the identity relationship. These are different events from changing a primary email.
Subject rotation replaces the subject and its synthetic identity values. Sudomimus terminates application sessions bound to the old subject. A later login presents a new external identity, and your application must not silently restore the old association by matching email or profile fields.
These changes cannot erase information an application already received. An application’s independent local session also needs its own lifecycle handling. Offline JWT verification can continue to accept an already issued token until expiry; use Session introspection when your operation needs current Sudomimus session authority.
Likewise, revoking an optional email-sharing grant stops later real-email disclosure through UserInfo. It does not delete copies already stored in the application’s database. Decide what information your application needs to retain and how it responds when that information is no longer shared.
Check the integration with a few concrete cases
- Sign in twice without changing the subject. Confirm that both visits find the same local user.
- Change the primary email while keeping the subject. Confirm that the local user and their project permissions remain the same.
- Decline optional email sharing. Confirm that sign-in works and the application handles the omitted field.
- Use a synthetic email policy. Confirm that the application does not treat the placeholder as a verified recovery mailbox.
- Rotate the sector subject. Confirm that a fresh login does not silently attach the new subject to the old local account.
For an overview of how identity, sessions, and application permissions fit together, read What is Sudomimus?. For protocol setup, continue with the OIDC integration guide.