FederatedIdentity

Links a local user account to an external identity in a federated authentication system. Captures provider subject identifier, authentication claims, linking metadata, and trust status. Supports multiple federated identities per user for enterprise SSO, B2B collaboration, and social login scenarios.

15 properties

Schema

Properties

Property	Type	Mode	Description	Required
user	User	stored	Reference to the local User account linked to this external identity	Required
identityProvider	IdentityProvider	stored	Reference to the IdentityProvider through which this identity was authenticated	Required
providerSubject	string	stored	Unique identifier for the user in the external identity provider's namespace (OIDC 'sub', SAML NameID, OAuth user_id) Example: `"a1b2c3d4-e5f6-7890-abcd-ef1234567890"`	Required
providerUsername	string	stored	Username or identifier in the external provider (may differ from providerSubject) Example: `"john.doe@corp.example.com"`	Optional
claims	json	stored	Claims or attributes received from the identity provider during authentication (email, name, groups, roles, custom attributes)	Required
linkedAt	datetime	stored	Date/time when this federated identity was linked to the user account Example: `"2024-01-15T10:30:00Z"`	Required
lastAuthenticatedAt	datetime	stored	Date/time of the most recent successful authentication using this federated identity Example: `"2024-11-22T08:15:00Z"`	Optional
linkMethod	string	stored	Method used to establish the link between external identity and local user Values: `auto-provision, email-match, manual-link, admin-link, self-service` Example: `"email-match"`	Required
status	string	stored	Current status of this federated identity link Values: `active, suspended, revoked, pending-verification` Example: `"active"`	Required
isPrimary	boolean	stored	Whether this is the primary/preferred federated identity for the user Example: `true`	Optional
isVerified	boolean	stored	Whether this federated identity has been verified through email confirmation or admin approval Example: `true`	Required
verifiedAt	datetime	stored	Date/time when this federated identity was verified Example: `"2024-01-15T10:35:00Z"`	Optional
authenticationCount	number	stored	Number of times this federated identity has been used for authentication Example: `147`	Optional
metadata	json	stored	Additional metadata including provider-specific data, linking context, or audit information	Optional
daysSinceLastAuth	number	calculated	Number of days since this identity was last used for authentication	Optional

Examples

Example 1

{
  "@type": "FederatedIdentity",
  "user": {
    "@type": "User",
    "username": "john.doe"
  },
  "identityProvider": {
    "@type": "IdentityProvider",
    "name": "Enterprise OIDC Provider",
    "protocol": "oidc"
  },
  "providerSubject": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "providerUsername": "john.doe@enterprise-a.example",
  "claims": {
    "email": "john.doe@enterprise-a.example",
    "name": "John Doe",
    "given_name": "John",
    "family_name": "Doe",
    "groups": [
      "Engineering",
      "Developers",
      "Full-Time"
    ],
    "department": "Engineering",
    "employee_id": "EMP-12345"
  },
  "linkedAt": "2024-01-15T10:30:00Z",
  "lastAuthenticatedAt": "2024-11-22T08:15:00Z",
  "linkMethod": "auto-provision",
  "status": "active",
  "isPrimary": true,
  "isVerified": true,
  "verifiedAt": "2024-01-15T10:30:00Z",
  "authenticationCount": 147
}

Example 2

{
  "@type": "FederatedIdentity",
  "user": {
    "@type": "User",
    "username": "jane.smith"
  },
  "identityProvider": {
    "@type": "IdentityProvider",
    "name": "Social Provider A",
    "protocol": "oidc"
  },
  "providerSubject": "109876543210987654321",
  "providerUsername": "jane.smith@example.com",
  "claims": {
    "email": "jane.smith@example.com",
    "email_verified": true,
    "name": "Jane Smith",
    "given_name": "Jane",
    "family_name": "Smith",
    "picture": "https://cdn.social-provider-a.example/avatars/default-user.png",
    "locale": "en"
  },
  "linkedAt": "2024-03-10T14:20:00Z",
  "lastAuthenticatedAt": "2024-11-21T16:45:00Z",
  "linkMethod": "email-match",
  "status": "active",
  "isPrimary": false,
  "isVerified": true,
  "verifiedAt": "2024-03-10T14:20:00Z",
  "authenticationCount": 89
}

Example 3

{
  "@type": "FederatedIdentity",
  "user": {
    "@type": "User",
    "username": "bob.wilson"
  },
  "identityProvider": {
    "@type": "IdentityProvider",
    "name": "Corporate SAML IdP",
    "protocol": "saml2"
  },
  "providerSubject": "bob.wilson@corp.example.com",
  "providerUsername": "bwilson",
  "claims": {
    "email": "bob.wilson@corp.example.com",
    "givenName": "Bob",
    "surname": "Wilson",
    "department": "Sales",
    "title": "Sales Manager",
    "office": "New York",
    "groups": "CN=Sales-Team,OU=Groups,DC=corp,DC=example,DC=com"
  },
  "linkedAt": "2024-02-01T09:00:00Z",
  "lastAuthenticatedAt": "2024-11-22T07:30:00Z",
  "linkMethod": "auto-provision",
  "status": "active",
  "isPrimary": true,
  "isVerified": true,
  "verifiedAt": "2024-02-01T09:00:00Z",
  "authenticationCount": 234,
  "metadata": {
    "saml_session_index": "s2a1b2c3d4e5f6g7h8i9j0",
    "assertion_id": "_a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

Example 4

{
  "@type": "FederatedIdentity",
  "user": {
    "@type": "User",
    "username": "alice.brown"
  },
  "identityProvider": {
    "@type": "IdentityProvider",
    "name": "Developer Platform OAuth",
    "protocol": "oauth2"
  },
  "providerSubject": "12345678",
  "providerUsername": "alicebrown",
  "claims": {
    "login": "alicebrown",
    "id": 12345678,
    "email": "alice.brown@example.com",
    "name": "Alice Brown",
    "avatar_url": "https://avatars.devplatform.example/u/12345678",
    "company": "Example Corp",
    "bio": "Software Engineer"
  },
  "linkedAt": "2024-06-15T11:00:00Z",
  "lastAuthenticatedAt": "2024-11-20T13:22:00Z",
  "linkMethod": "self-service",
  "status": "active",
  "isPrimary": false,
  "isVerified": true,
  "verifiedAt": "2024-06-15T11:05:00Z",
  "authenticationCount": 42
}

Example 5

{
  "@type": "FederatedIdentity",
  "user": {
    "@type": "User",
    "username": "charlie.davis"
  },
  "identityProvider": {
    "@type": "IdentityProvider",
    "name": "Partner IdP - Acme Corp",
    "protocol": "oidc"
  },
  "providerSubject": "ext-user-9876",
  "providerUsername": "charlie.davis@acme.com",
  "claims": {
    "email": "charlie.davis@acme.com",
    "name": "Charlie Davis",
    "organization": "Acme Corp",
    "partner_id": "ACME-001"
  },
  "linkedAt": "2024-09-01T15:30:00Z",
  "linkMethod": "admin-link",
  "status": "pending-verification",
  "isPrimary": true,
  "isVerified": false,
  "authenticationCount": 0,
  "metadata": {
    "linked_by_admin": "admin@example.com",
    "verification_email_sent": "2024-09-01T15:35:00Z"
  }
}