Membership mapping and lifecycle

Nanaade does not create a tenant relationship merely because an assertion has a valid signature. The person must have an active TenantMembership in the tenant identified by the integration credential.

First-launch resolution

For an active tenant, Nanaade looks for an active membership where either:

1. externalSubject already equals the assertion's sub; or
2. normalizedEmail equals the lowercased assertion email.

If an email-matched membership has no external subject, Nanaade stores sub and updates lastAccessedAt.

Assertion: sub=student_10482, email=amara@northbridge.edu
Membership: externalSubject=null, normalizedEmail=amara@northbridge.edu
Result: membership is bound to student_10482

Later launches should resolve by the subject. If the same membership is already bound to student_10482 but the assertion supplies student_90210, Nanaade returns 409 SSO_SUBJECT_MISMATCH.

Choose a stable subject

Use your immutable internal user ID:

const identity = {
  sub: databaseUser.id,       // e.g. "usr_01J4M8..."
  email: databaseUser.email,
};

Do not use email, employee/student number if it can be reassigned, a login session ID, an OAuth access token, or a random UUID generated during launch.

Membership states

| State | SSO access | Operational meaning | |---|---|---| | Invited | Denied | User has not activated the sponsored relationship. | | Active | Allowed | Role, permissions, and tenant entitlements are evaluated. | | Revoked | Denied immediately | Sponsored access was withdrawn. | | Ended/transferred | Denied | Historical membership remains for audit purposes. |

Removing a module is different from revoking membership. Module removal blocks that capability; membership revocation blocks all tenant-sponsored access.

Example onboarding flow

1. University admin imports or invites amara@northbridge.edu.
2. Nanaade creates the user/membership or links the existing identity according to the roster workflow.
3. Amara activates the invitation; membership becomes active.
4. The university portal signs sub=student_10482 with the same normalized email.
5. Nanaade binds the subject and enters the tenant workspace.

Transfers and duplicate access

V1 permits one active sponsored member tenant per Nanaade user. If the person is active under another sponsored tenant, Nanaade requires an explicit, audited transfer. Do not create a second Nanaade user to bypass this rule. Tenant administrators should confirm the destination invitation and explain the access change to the user.

Troubleshooting mapping

• SSO_MEMBERSHIP_REQUIRED: verify tenant, normalized email, and active status.
• SSO_SUBJECT_MISMATCH: verify your immutable ID mapping; do not rotate subjects.
• User enters but sees fewer features: membership succeeded; inspect role, permissions, and tenant modules.
• User changed email: keep the original subject and update membership/user email through the approved account workflow.