Azure Active Directory User

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://schema.api.gov/azure-active-directory/user",
  "title": "Azure Active Directory User",
  "description": "Represents a user account in Azure Active Directory (Microsoft Entra ID). A user is a core identity object in the Microsoft identity platform, containing profile information, authentication credentials, organizational relationships, and license assignments. This schema is based on the Microsoft Graph v1.0 user resource type as documented at https://learn.microsoft.com/en-us/graph/api/resources/user.",
  "type": "object",
  "required": [
    "displayName",
    "userPrincipalName"
  ],
  "properties": {
    "@odata.type": {
      "type": "string",
      "const": "#microsoft.graph.user",
      "description": "The OData type annotation for the user resource."
    },
    "id": {
      "type": "string",
      "format": "uuid",
      "description": "The unique identifier for the user. This is a GUID assigned by Azure AD when the user object is created. Read-only.",
      "readOnly": true
    },
    "deletedDateTime": {
      "type": ["string", "null"],
      "format": "date-time",
      "description": "The date and time the user was deleted. Null if the user has not been deleted. Read-only.",
      "readOnly": true
    },
    "accountEnabled": {
      "type": "boolean",
      "description": "True if the account is enabled; otherwise, false. This property is required when creating a user. A disabled account cannot authenticate."
    },
    "ageGroup": {
      "type": ["string", "null"],
      "description": "Sets the age group of the user. Allowed values: null, Minor, NotAdult, Adult.",
      "enum": [null, "Minor", "NotAdult", "Adult"]
    },
    "assignedLicenses": {
      "type": "array",
      "description": "The licenses assigned to the user, including specific disabled service plans. Read-only. Not nullable.",
      "readOnly": true,
      "items": {
        "$ref": "#/$defs/assignedLicense"
      }
    },
    "assignedPlans": {
      "type": "array",
      "description": "The plans assigned to the user from subscriptions. Read-only. Not nullable.",
      "readOnly": true,
      "items": {
        "$ref": "#/$defs/assignedPlan"
      }
    },
    "businessPhones": {
      "type": "array",
      "description": "The telephone numbers for the user. Only one number can be set for this property. Read-only for users synced from on-premises directory.",
      "items": {
        "type": "string"
      }
    },
    "city": {
      "type": ["string", "null"],
      "description": "The city where the user is located. Maximum length is 128 characters.",
      "maxLength": 128
    },
    "companyName": {
      "type": ["string", "null"],
      "description": "The name of the company associated with the user. This property can be useful for describing the company that an external user comes from. Maximum length is 64 characters.",
      "maxLength": 64
    },
    "consentProvidedForMinor": {
      "type": ["string", "null"],
      "description": "Sets whether consent was obtained for minors. Allowed values: null, Granted, Denied, NotRequired.",
      "enum": [null, "Granted", "Denied", "NotRequired"]
    },
    "country": {
      "type": ["string", "null"],
      "description": "The country or region where the user is located. Use the ISO 3166 two-letter country code format (e.g., US, GB, DE). Maximum length is 128 characters.",
      "maxLength": 128
    },
    "createdDateTime": {
      "type": ["string", "null"],
      "format": "date-time",
      "description": "The date and time the user was created in ISO 8601 format and UTC time. Read-only.",
      "readOnly": true
    },
    "creationType": {
      "type": ["string", "null"],
      "description": "Indicates whether the user account was created through one of the following methods: as a regular school or work account (null), as an external account (Invitation), as a local account for an Azure Active Directory B2C tenant (LocalAccount), or through self-service sign-up by an internal user using email verification (EmailVerified). Read-only.",
      "readOnly": true
    },
    "department": {
      "type": ["string", "null"],
      "description": "The name of the department in which the user works. Maximum length is 64 characters.",
      "maxLength": 64
    },
    "displayName": {
      "type": "string",
      "description": "The name displayed in the address book for the user. This is usually the combination of the first name, middle initial, and last name. This property is required when a user is created and cannot be cleared during updates. Maximum length is 256 characters.",
      "maxLength": 256
    },
    "employeeHireDate": {
      "type": ["string", "null"],
      "format": "date-time",
      "description": "The date and time when the user was hired or will start work in case of a future hire."
    },
    "employeeId": {
      "type": ["string", "null"],
      "description": "The employee identifier assigned to the user by the organization. The maximum length is 16 characters.",
      "maxLength": 16
    },
    "employeeLeaveDateTime": {
      "type": ["string", "null"],
      "format": "date-time",
      "description": "The date and time when the user left or will leave the organization."
    },
    "employeeOrgData": {
      "description": "Represents organization data (e.g., division and costCenter) associated with a user.",
      "$ref": "#/$defs/employeeOrgData"
    },
    "employeeType": {
      "type": ["string", "null"],
      "description": "Captures enterprise worker type. For example, Employee, Contractor, Consultant, or Vendor."
    },
    "externalUserState": {
      "type": ["string", "null"],
      "description": "For an external user invited to the tenant, this property represents the invited user's invitation status. Possible values: PendingAcceptance, Accepted, null. Read-only.",
      "readOnly": true,
      "enum": [null, "PendingAcceptance", "Accepted"]
    },
    "externalUserStateChangeDateTime": {
      "type": ["string", "null"],
      "format": "date-time",
      "description": "Shows the timestamp for the latest change to the externalUserState property. Read-only.",
      "readOnly": true
    },
    "faxNumber": {
      "type": ["string", "null"],
      "description": "The fax number of the user."
    },
    "givenName": {
      "type": ["string", "null"],
      "description": "The given name (first name) of the user. Maximum length is 64 characters.",
      "maxLength": 64
    },
    "identities": {
      "type": "array",
      "description": "Represents the identities that can be used to sign in to this user account. An identity can be provided by Microsoft, by organizations, or by social identity providers. May contain multiple items with the same signInType value.",
      "items": {
        "$ref": "#/$defs/objectIdentity"
      }
    },
    "imAddresses": {
      "type": "array",
      "description": "The instant message voice-over-IP (VOIP) session initiation protocol (SIP) addresses for the user. Read-only.",
      "readOnly": true,
      "items": {
        "type": "string"
      }
    },
    "isResourceAccount": {
      "type": ["boolean", "null"],
      "description": "Do not use. Reserved for future use."
    },
    "jobTitle": {
      "type": ["string", "null"],
      "description": "The user's job title. Maximum length is 128 characters.",
      "maxLength": 128
    },
    "lastPasswordChangeDateTime": {
      "type": ["string", "null"],
      "format": "date-time",
      "description": "The time when this Azure AD user last changed their password or when their password was created. Read-only.",
      "readOnly": true
    },
    "legalAgeGroupClassification": {
      "type": ["string", "null"],
      "description": "Used by enterprise applications to determine the legal age group of the user. Read-only.",
      "readOnly": true,
      "enum": [null, "MinorWithOutParentalConsent", "MinorWithParentalConsent", "MinorNoParentalConsentRequired", "NotAdult", "Adult"]
    },
    "licenseAssignmentStates": {
      "type": "array",
      "description": "State of license assignments for this user. Read-only.",
      "readOnly": true,
      "items": {
        "$ref": "#/$defs/licenseAssignmentState"
      }
    },
    "mail": {
      "type": ["string", "null"],
      "format": "email",
      "description": "The SMTP address for the user (e.g., [email protected]). Changes to this property also update the user's proxyAddresses collection to include the value as an SMTP address. This property cannot contain accent characters."
    },
    "mailNickname": {
      "type": "string",
      "description": "The mail alias for the user. This property must be specified when a user is created. Maximum length is 64 characters.",
      "maxLength": 64
    },
    "mobilePhone": {
      "type": ["string", "null"],
      "description": "The primary cellular telephone number for the user. Read-only for users synced from on-premises directory."
    },
    "officeLocation": {
      "type": ["string", "null"],
      "description": "The office location in the user's place of business."
    },
    "onPremisesDistinguishedName": {
      "type": ["string", "null"],
      "description": "Contains the on-premises Active Directory distinguished name or DN. Read-only.",
      "readOnly": true
    },
    "onPremisesDomainName": {
      "type": ["string", "null"],
      "description": "Contains the on-premises domainFQDN, also called dnsDomainName, synced from the on-premises directory. Read-only.",
      "readOnly": true
    },
    "onPremisesExtensionAttributes": {
      "description": "Contains extensionAttributes1-15 for the user. These extension attributes are also known as Exchange custom attributes. Read-only for cloud-only users.",
      "$ref": "#/$defs/onPremisesExtensionAttributes"
    },
    "onPremisesImmutableId": {
      "type": ["string", "null"],
      "description": "This property is used to associate an on-premises Active Directory user account to their Azure AD user object. This property must be specified when creating a new user if you are using a federated domain for the userPrincipalName (UPN)."
    },
    "onPremisesLastSyncDateTime": {
      "type": ["string", "null"],
      "format": "date-time",
      "description": "Indicates the last time at which the object was synced with the on-premises directory. Read-only.",
      "readOnly": true
    },
    "onPremisesProvisioningErrors": {
      "type": "array",
      "description": "Errors when using Microsoft synchronization product during provisioning. Read-only.",
      "readOnly": true,
      "items": {
        "$ref": "#/$defs/onPremisesProvisioningError"
      }
    },
    "onPremisesSamAccountName": {
      "type": ["string", "null"],
      "description": "Contains the on-premises samAccountName synced from the on-premises directory. Read-only.",
      "readOnly": true
    },
    "onPremisesSecurityIdentifier": {
      "type": ["string", "null"],
      "description": "Contains the on-premises security identifier (SID) for the user that was synced from on-premises to the cloud. Read-only.",
      "readOnly": true
    },
    "onPremisesSyncEnabled": {
      "type": ["boolean", "null"],
      "description": "True if this user object is currently being synced from an on-premises Active Directory (AD); otherwise, the user isn't being synced and can be managed in Azure Active Directory. Read-only.",
      "readOnly": true
    },
    "onPremisesUserPrincipalName": {
      "type": ["string", "null"],
      "description": "Contains the on-premises userPrincipalName synced from the on-premises directory. Read-only.",
      "readOnly": true
    },
    "otherMails": {
      "type": "array",
      "description": "A list of additional email addresses for the user (e.g., [\"[email protected]\", \"[email protected]\"]).",
      "items": {
        "type": "string",
        "format": "email"
      }
    },
    "passwordPolicies": {
      "type": ["string", "null"],
      "description": "Specifies password policies for the user. This value is an enumeration with one possible value being DisableStrongPassword, which allows weaker passwords than the default policy to be specified. DisablePasswordExpiration can also be specified. The two may be specified together; for example: DisablePasswordExpiration, DisableStrongPassword."
    },
    "passwordProfile": {
      "description": "Specifies the password profile for the user. The profile contains the user's password. This property is required when a user is created.",
      "$ref": "#/$defs/passwordProfile"
    },
    "postalCode": {
      "type": ["string", "null"],
      "description": "The postal code for the user's postal address. The postal code is specific to the user's country/region. Maximum length is 40 characters.",
      "maxLength": 40
    },
    "preferredLanguage": {
      "type": ["string", "null"],
      "description": "The preferred language for the user, expressed in ISO 639-1 code format (e.g., en-US)."
    },
    "preferredDataLocation": {
      "type": ["string", "null"],
      "description": "The preferred data location for the user, indicating the geographic region for their data."
    },
    "provisionedPlans": {
      "type": "array",
      "description": "The plans that are provisioned for the user. Read-only. Not nullable.",
      "readOnly": true,
      "items": {
        "$ref": "#/$defs/provisionedPlan"
      }
    },
    "proxyAddresses": {
      "type": "array",
      "description": "A list that includes the user's SMTP and SIP proxy addresses. For example: [\"SMTP:[email protected]\", \"smtp:[email protected]\"]. The address prefixed with SMTP (uppercase) is the primary. Read-only.",
      "readOnly": true,
      "items": {
        "type": "string"
      }
    },
    "securityIdentifier": {
      "type": ["string", "null"],
      "description": "Security identifier (SID) of the user, used in Windows scenarios. Read-only.",
      "readOnly": true
    },
    "showInAddressList": {
      "type": ["boolean", "null"],
      "description": "Do not use in Microsoft Graph. Manage this property through the Microsoft 365 admin center instead."
    },
    "signInActivity": {
      "description": "Get the last signed-in date and request ID of the sign-in for a given user. Read-only. Requires Azure AD Premium P1 or P2 license.",
      "readOnly": true,
      "$ref": "#/$defs/signInActivity"
    },
    "signInSessionsValidFromDateTime": {
      "type": ["string", "null"],
      "format": "date-time",
      "description": "Any refresh tokens or sessions tokens (session cookies) issued before this time are invalid, and applications will get an error when using an invalid refresh or sessions token to acquire a delegated access token. Read-only.",
      "readOnly": true
    },
    "state": {
      "type": ["string", "null"],
      "description": "The state or province in the user's address. Maximum length is 128 characters.",
      "maxLength": 128
    },
    "streetAddress": {
      "type": ["string", "null"],
      "description": "The street address of the user's place of business. Maximum length is 1024 characters.",
      "maxLength": 1024
    },
    "surname": {
      "type": ["string", "null"],
      "description": "The user's surname (family name or last name). Maximum length is 64 characters.",
      "maxLength": 64
    },
    "usageLocation": {
      "type": ["string", "null"],
      "description": "A two-letter country code (ISO standard 3166). Required for users that will be assigned licenses due to legal requirements to check for availability of services in countries/regions. Examples include US, JP, and GB. Not nullable.",
      "pattern": "^[A-Z]{2}$"
    },
    "userPrincipalName": {
      "type": "string",
      "description": "The user principal name (UPN) of the user. The UPN is an Internet-style sign-in name based on the Internet standard RFC 822. By convention, this should map to the user's email name. The general format is alias@domain, where domain must be present in the tenant's verified domain collection. This property is required when a user is created.",
      "format": "email"
    },
    "userType": {
      "type": ["string", "null"],
      "description": "A string value that can be used to classify user types in your directory, such as Member and Guest.",
      "enum": [null, "Member", "Guest"]
    }
  },
  "$defs": {
    "assignedLicense": {
      "type": "object",
      "description": "Represents a license assigned to a user, specifying the SKU and any disabled plans.",
      "properties": {
        "disabledPlans": {
          "type": "array",
          "description": "A 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 through a subscription.",
      "properties": {
        "assignedDateTime": {
          "type": "string",
          "format": "date-time",
          "description": "The date and time at which 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": "A GUID that identifies the service plan."
        }
      }
    },
    "employeeOrgData": {
      "type": ["object", "null"],
      "description": "Represents organization data associated with a user.",
      "properties": {
        "costCenter": {
          "type": ["string", "null"],
          "description": "The cost center associated with the user."
        },
        "division": {
          "type": ["string", "null"],
          "description": "The name of the division in which the user works."
        }
      }
    },
    "objectIdentity": {
      "type": "object",
      "description": "Represents an identity used to sign in to a user account.",
      "properties": {
        "signInType": {
          "type": "string",
          "description": "Specifies the user sign-in types in your directory, such as emailAddress, userName, federated, or userPrincipalName."
        },
        "issuer": {
          "type": "string",
          "description": "Specifies the issuer of the identity (e.g., contoso.com for federated identities, or the tenant name for local accounts)."
        },
        "issuerAssignedId": {
          "type": "string",
          "description": "Specifies the unique value associated with the identity issued by the issuer. The combination of issuer and issuerAssignedId must be unique."
        }
      }
    },
    "licenseAssignmentState": {
      "type": "object",
      "description": "Provides details about license assignments.",
      "properties": {
        "assignedByGroup": {
          "type": ["string", "null"],
          "format": "uuid",
          "description": "The id of the group that assigns this license. If the assignment is a direct-assigned license, this field will be null."
        },
        "disabledPlans": {
          "type": "array",
          "items": {
            "type": "string",
            "format": "uuid"
          }
        },
        "error": {
          "type": ["string", "null"],
          "description": "License assignment failure error."
        },
        "lastUpdatedDateTime": {
          "type": ["string", "null"],
          "format": "date-time"
        },
        "skuId": {
          "type": "string",
          "format": "uuid"
        },
        "state": {
          "type": "string",
          "enum": ["Active", "ActiveWithError", "Disabled", "Error"]
        }
      }
    },
    "onPremisesExtensionAttributes": {
      "type": ["object", "null"],
      "description": "Contains 15 custom extension attribute properties (extensionAttribute1 through extensionAttribute15). These attributes are synced from on-premises AD for hybrid users.",
      "properties": {
        "extensionAttribute1": { "type": ["string", "null"] },
        "extensionAttribute2": { "type": ["string", "null"] },
        "extensionAttribute3": { "type": ["string", "null"] },
        "extensionAttribute4": { "type": ["string", "null"] },
        "extensionAttribute5": { "type": ["string", "null"] },
        "extensionAttribute6": { "type": ["string", "null"] },
        "extensionAttribute7": { "type": ["string", "null"] },
        "extensionAttribute8": { "type": ["string", "null"] },
        "extensionAttribute9": { "type": ["string", "null"] },
        "extensionAttribute10": { "type": ["string", "null"] },
        "extensionAttribute11": { "type": ["string", "null"] },
        "extensionAttribute12": { "type": ["string", "null"] },
        "extensionAttribute13": { "type": ["string", "null"] },
        "extensionAttribute14": { "type": ["string", "null"] },
        "extensionAttribute15": { "type": ["string", "null"] }
      }
    },
    "onPremisesProvisioningError": {
      "type": "object",
      "description": "Represents errors encountered during directory synchronization.",
      "properties": {
        "category": {
          "type": "string",
          "description": "Category of the provisioning error."
        },
        "occurredDateTime": {
          "type": "string",
          "format": "date-time"
        },
        "propertyCausingError": {
          "type": "string",
          "description": "Name of the directory property causing the error."
        },
        "value": {
          "type": "string",
          "description": "Value of the property causing the error."
        }
      }
    },
    "passwordProfile": {
      "type": "object",
      "description": "Contains the password profile associated with a user, including the password itself and policies for password changes.",
      "required": ["password"],
      "properties": {
        "forceChangePasswordNextSignIn": {
          "type": "boolean",
          "description": "If true, at next sign-in, the user must change their password. After a password change, this property is automatically reset to false.",
          "default": false
        },
        "forceChangePasswordNextSignInWithMfa": {
          "type": "boolean",
          "description": "If true, at next sign-in, the user must perform multi-factor authentication (MFA) before being forced to change their password.",
          "default": false
        },
        "password": {
          "type": "string",
          "description": "The password for the user. This property is required when creating a user. It can be updated, but the user will be required to change the password on the next sign-in. The password must satisfy minimum requirements as specified by the tenant's password complexity policy. By default, a strong password is required."
        }
      }
    },
    "provisionedPlan": {
      "type": "object",
      "description": "Represents a service plan that has been provisioned for a user.",
      "properties": {
        "capabilityStatus": {
          "type": "string",
          "description": "Condition of the capability assignment.",
          "enum": ["Enabled", "Warning", "Suspended", "Deleted", "LockedOut"]
        },
        "provisioningStatus": {
          "type": "string",
          "description": "The provisioning status of the plan."
        },
        "service": {
          "type": "string",
          "description": "The name of the service."
        }
      }
    },
    "signInActivity": {
      "type": ["object", "null"],
      "description": "Provides the last interactive and non-interactive sign-in date and request ID for a specific user.",
      "properties": {
        "lastSignInDateTime": {
          "type": ["string", "null"],
          "format": "date-time",
          "description": "The last interactive sign-in date and time for a specific user."
        },
        "lastSignInRequestId": {
          "type": ["string", "null"],
          "description": "Request identifier of the last interactive sign-in performed by this user."
        },
        "lastNonInteractiveSignInDateTime": {
          "type": ["string", "null"],
          "format": "date-time",
          "description": "The last non-interactive sign-in date for a specific user."
        },
        "lastNonInteractiveSignInRequestId": {
          "type": ["string", "null"],
          "description": "Request identifier of the last non-interactive sign-in performed by this user."
        }
      }
    }
  },
  "examples": [
    {
      "id": "87d349ed-44d7-43e1-9a83-5f2406dee5bd",
      "displayName": "Adele Vance",
      "givenName": "Adele",
      "surname": "Vance",
      "userPrincipalName": "[email protected]",
      "mail": "[email protected]",
      "mailNickname": "adelev",
      "accountEnabled": true,
      "jobTitle": "Retail Manager",
      "department": "Retail",
      "city": "Seattle",
      "state": "WA",
      "country": "US",
      "usageLocation": "US",
      "userType": "Member",
      "businessPhones": ["+1 425 555 0100"],
      "mobilePhone": "+1 425 555 0101",
      "officeLocation": "Building 18/2111",
      "preferredLanguage": "en-US",
      "createdDateTime": "2023-06-15T08:00:00Z"
    }
  ]
}