Microsoft Entra User

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://graph.microsoft.com/schemas/microsoft-entra/user.json",
  "title": "Microsoft Entra User",
  "description": "Schema for a Microsoft Entra ID (formerly Azure AD) user resource as represented in the Microsoft Graph API. Contains identity, contact, organizational, and authentication profile properties.",
  "type": "object",
  "required": [
    "displayName",
    "accountEnabled",
    "mailNickname",
    "userPrincipalName",
    "passwordProfile"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the user (GUID). Assigned automatically by Microsoft Entra ID.",
      "readOnly": true
    },
    "displayName": {
      "type": "string",
      "description": "The name displayed in the address book for the user. Maximum length is 256 characters.",
      "maxLength": 256
    },
    "givenName": {
      "type": ["string", "null"],
      "description": "The given name (first name) of the user. Maximum length is 64 characters.",
      "maxLength": 64
    },
    "surname": {
      "type": ["string", "null"],
      "description": "The surname (family name or last name) of the user. Maximum length is 64 characters.",
      "maxLength": 64
    },
    "userPrincipalName": {
      "type": "string",
      "description": "The user principal name (UPN) in the format alias@domain. The domain portion must be a verified domain in the tenant.",
      "format": "email"
    },
    "mail": {
      "type": ["string", "null"],
      "description": "The SMTP address of the user (e.g., [email protected]). Changes to this property also update the proxyAddresses collection.",
      "format": "email"
    },
    "mailNickname": {
      "type": "string",
      "description": "The mail alias for the user. Must be specified when creating a new user. Maximum length is 64 characters.",
      "maxLength": 64
    },
    "accountEnabled": {
      "type": "boolean",
      "description": "true if the account is enabled; otherwise, false. Must be specified when creating a new user."
    },
    "passwordProfile": {
      "$ref": "#/$defs/PasswordProfile"
    },
    "jobTitle": {
      "type": ["string", "null"],
      "description": "The user's job title. Maximum length is 128 characters.",
      "maxLength": 128
    },
    "department": {
      "type": ["string", "null"],
      "description": "The name of the department in which the user works. Maximum length is 64 characters.",
      "maxLength": 64
    },
    "officeLocation": {
      "type": ["string", "null"],
      "description": "The office location in the user's place of business.",
      "maxLength": 128
    },
    "companyName": {
      "type": ["string", "null"],
      "description": "The company name associated with the user. Maximum length is 64 characters.",
      "maxLength": 64
    },
    "mobilePhone": {
      "type": ["string", "null"],
      "description": "The primary cellular telephone number for the user. Maximum length is 64 characters.",
      "maxLength": 64
    },
    "businessPhones": {
      "type": "array",
      "description": "The telephone numbers for the user. Only one number can be set. Read-only for users synced from on-premises.",
      "items": {
        "type": "string"
      }
    },
    "streetAddress": {
      "type": ["string", "null"],
      "description": "The street address of the user's place of business. Maximum length is 1024 characters.",
      "maxLength": 1024
    },
    "city": {
      "type": ["string", "null"],
      "description": "The city in which the user is located. Maximum length is 128 characters.",
      "maxLength": 128
    },
    "state": {
      "type": ["string", "null"],
      "description": "The state or province in the user's address. Maximum length is 128 characters.",
      "maxLength": 128
    },
    "postalCode": {
      "type": ["string", "null"],
      "description": "The postal code for the user's postal address. Maximum length is 40 characters.",
      "maxLength": 40
    },
    "country": {
      "type": ["string", "null"],
      "description": "The country or region in which the user is located. Use ISO 3166 two-letter country code (e.g., US, GB).",
      "maxLength": 128
    },
    "usageLocation": {
      "type": ["string", "null"],
      "description": "A two-letter country code (ISO 3166). Required for users assigned licenses due to legal requirements.",
      "pattern": "^[A-Z]{2}$"
    },
    "preferredLanguage": {
      "type": ["string", "null"],
      "description": "The preferred language for the user in ISO 639-1 code format (e.g., en-US)."
    },
    "userType": {
      "type": "string",
      "description": "A string value that classifies the user type. Member users are internal to the tenant, Guest users are invited from outside.",
      "enum": ["Member", "Guest"]
    },
    "employeeId": {
      "type": ["string", "null"],
      "description": "The employee identifier assigned to the user by the organization. Maximum length is 16 characters.",
      "maxLength": 16
    },
    "employeeType": {
      "type": ["string", "null"],
      "description": "Captures the enterprise worker type (e.g., Employee, Contractor, Consultant, Vendor)."
    },
    "employeeHireDate": {
      "type": ["string", "null"],
      "format": "date-time",
      "description": "The date and time when the user was hired or will start work in a future hire."
    },
    "onPremisesSyncEnabled": {
      "type": ["boolean", "null"],
      "description": "true if synced from an on-premises directory; false if originally cloud-created; null if never synced.",
      "readOnly": true
    },
    "onPremisesSamAccountName": {
      "type": ["string", "null"],
      "description": "The on-premises SAM account name synchronized from the on-premises directory.",
      "readOnly": true
    },
    "onPremisesDistinguishedName": {
      "type": ["string", "null"],
      "description": "The on-premises distinguished name (DN) synchronized from Active Directory.",
      "readOnly": true
    },
    "onPremisesDomainName": {
      "type": ["string", "null"],
      "description": "The on-premises domain name synchronized from Active Directory.",
      "readOnly": true
    },
    "onPremisesImmutableId": {
      "type": ["string", "null"],
      "description": "Used to associate an on-premises Active Directory user account to their Entra user object. Must be specified if using a federated domain for the UPN."
    },
    "onPremisesLastSyncDateTime": {
      "type": ["string", "null"],
      "format": "date-time",
      "description": "The last time the object was synced with the on-premises directory.",
      "readOnly": true
    },
    "proxyAddresses": {
      "type": "array",
      "description": "List of proxy addresses (e.g., SMTP:[email protected], smtp:[email protected]).",
      "readOnly": true,
      "items": {
        "type": "string"
      }
    },
    "assignedLicenses": {
      "type": "array",
      "description": "The licenses assigned to the user including disabled service plans.",
      "readOnly": true,
      "items": {
        "$ref": "#/$defs/AssignedLicense"
      }
    },
    "assignedPlans": {
      "type": "array",
      "description": "The plans assigned to the user.",
      "readOnly": true,
      "items": {
        "$ref": "#/$defs/AssignedPlan"
      }
    },
    "identities": {
      "type": "array",
      "description": "Identities associated with the user account including social identities for B2B/B2C scenarios.",
      "items": {
        "$ref": "#/$defs/ObjectIdentity"
      }
    },
    "createdDateTime": {
      "type": "string",
      "format": "date-time",
      "description": "The date and time the user was created.",
      "readOnly": true
    },
    "lastSignInDateTime": {
      "type": ["string", "null"],
      "format": "date-time",
      "description": "The last interactive sign-in date and time for the user.",
      "readOnly": true
    },
    "deletedDateTime": {
      "type": ["string", "null"],
      "format": "date-time",
      "description": "The date and time the user was deleted. Only present for deleted users in the deletedItems container.",
      "readOnly": true
    }
  },
  "$defs": {
    "PasswordProfile": {
      "type": "object",
      "description": "Contains the password profile associated with a user including the password and policies for change enforcement.",
      "required": ["password"],
      "properties": {
        "password": {
          "type": "string",
          "description": "The password for the user. Must satisfy the tenant's password complexity requirements. Required when creating a user.",
          "writeOnly": true
        },
        "forceChangePasswordNextSignIn": {
          "type": "boolean",
          "description": "If true, the user must change the password on the next sign-in.",
          "default": false
        },
        "forceChangePasswordNextSignInWithMfa": {
          "type": "boolean",
          "description": "If true, the user must perform MFA before being forced to change password.",
          "default": false
        }
      }
    },
    "AssignedLicense": {
      "type": "object",
      "description": "Represents a license assigned to a user.",
      "properties": {
        "disabledPlans": {
          "type": "array",
          "description": "Collection of the unique identifiers for plans that have been disabled.",
          "items": {
            "type": "string",
            "format": "uuid"
          }
        },
        "skuId": {
          "type": "string",
          "format": "uuid",
          "description": "The unique identifier for the SKU."
        }
      }
    },
    "AssignedPlan": {
      "type": "object",
      "description": "Represents a plan assigned to a user.",
      "properties": {
        "assignedDateTime": {
          "type": "string",
          "format": "date-time",
          "description": "Date and time the plan was assigned."
        },
        "capabilityStatus": {
          "type": "string",
          "description": "Condition of the capability assignment.",
          "enum": ["Enabled", "Warning", "Suspended", "Deleted", "LockedOut"]
        },
        "service": {
          "type": "string",
          "description": "The name of the service (e.g., exchange, SharePoint)."
        },
        "servicePlanId": {
          "type": "string",
          "format": "uuid",
          "description": "GUID that identifies the service plan."
        }
      }
    },
    "ObjectIdentity": {
      "type": "object",
      "description": "Represents an identity used to sign in to a user account, including social identities.",
      "properties": {
        "signInType": {
          "type": "string",
          "description": "Specifies the user sign-in type (e.g., emailAddress, userName, federated)."
        },
        "issuer": {
          "type": "string",
          "description": "The issuer of the identity (e.g., contoso.com, facebook.com)."
        },
        "issuerAssignedId": {
          "type": "string",
          "description": "The unique identifier assigned to the user by the issuer."
        }
      }
    }
  }
}