diff --git a/.github/policies/resourceManagement.yml b/.github/policies/resourceManagement.yml index a07799da2b5..b88254cf55d 100644 --- a/.github/policies/resourceManagement.yml +++ b/.github/policies/resourceManagement.yml @@ -972,61 +972,8 @@ configuration: - isOpen - isAction: action: Opened - - activitySenderHasAssociation: - association: COLLABORATOR - - not: - or: - - hasLabel: - label: do not merge - - hasLabel: - label: ready to merge - - hasLabel: - label: ready for content review - - hasLabel: - label: blocked - - hasLabel: - label: changelog required - - hasLabel: - label: changes requested - - hasLabel: - label: awaiting internal response - - hasLabel: - label: content review in progress - - hasLabel: - label: content review complete - then: - - addLabel: - label: do not merge - - addReply: - reply: >- - > [!NOTE] - - > The following guidance is for Microsoft employees only. Community contributors can ignore this message; our content team will manage the status. - - - Thanks for your pull request, ${issueAuthor}! I've added the **do not merge** label as a default status. - - - Please add the **ready for content review** label to start a review. Your PR won't be reviewed until you add this label. - - - After the content review is complete and the updates in this PR are ready for external customers to use, please replace the **do not merge** label with **ready to merge**. - - - > [!NOTE] - - > Pull requests will not be merged until the **ready to merge** label is set. - - - For details, see the [Content review process summary](https://dev.azure.com/msazure/One/_wiki/wikis/Microsoft%20Graph%20Partners/614263/Content-workflow). - - description: Add do not merge label to new pull requests opened by members - if: - - payloadType: Pull_Request - - isOpen - - isAction: - action: Opened - - activitySenderHasAssociation: - association: MEMBER + - activitySenderHasPermission: + permission: write - not: or: - hasLabel: diff --git a/api-reference/beta/api/schemaextension-delete.md b/api-reference/beta/api/schemaextension-delete.md index 423741796da..a48a7e32b61 100644 --- a/api-reference/beta/api/schemaextension-delete.md +++ b/api-reference/beta/api/schemaextension-delete.md @@ -13,7 +13,9 @@ Namespace: microsoft.graph [!INCLUDE [beta-disclaimer](../../includes/beta-disclaimer.md)] -Delete the definition of a [schema extension](../resources/schemaextension.md). Only the app that created the schema extension (owner app) can delete the schema extension definition, and only when the extension is in the `InDevelopment` state. Deleting a schema extension definition does not affect accessing custom data that has been added to resource instances based on that definition. +Delete the definition of a [schema extension](../resources/schemaextension.md). In app-only scenarios, only the app that created the schema extension (owner app) can delete the schema extension definition, and only when the extension is in the `InDevelopment` state. In delegated scenarios, the owner of the owner app can delete the schema extension definition, and only when the extension is in the `InDevelopment` state. + +Deleting a schema extension definition before deleting the data associated with the extension in the target resources makes the data inaccessible. To recover the data, you can recreate the schema extension definition with the same configuration, but only if you used the verified domain for the schema extension **id**. [!INCLUDE [national-cloud-support](../../includes/all-clouds.md)] diff --git a/api-reference/beta/api/security-auditcoreroot-list-auditlogqueries.md b/api-reference/beta/api/security-auditcoreroot-list-auditlogqueries.md new file mode 100644 index 00000000000..9fdfa20f01e --- /dev/null +++ b/api-reference/beta/api/security-auditcoreroot-list-auditlogqueries.md @@ -0,0 +1,117 @@ +--- +title: "List auditLogQueries" +description: "Get a list of the auditLogQuery objects and their properties." +author: "arishojaswi" +ms.localizationpriority: medium +ms.prod: "security" +doc_type: apiPageType +--- + +# List auditLogQueries +Namespace: microsoft.graph.security + +[!INCLUDE [beta-disclaimer](../../includes/beta-disclaimer.md)] + +Get a list of [auditLogQuery](../resources/security-auditlogquery.md) objects and their properties. + +## Permissions +Auditing data can be accessed through Microsoft Purview Audit Search API via the following permissions, which are classified at a Microsoft 365 service level. To learn more, including how to choose permissions, see [Permissions](/graph/permissions-reference). + + +|Microsoft 365 service|Delegated (work or school account)|Delegated (personal Microsoft account)|Application +|:---|:---|:---|:---| +|Microsoft OneDrive|AuditLogsQuery-OneDrive.Read.All|Not supported|AuditLogsQuery-OneDrive.Read.All| +|Microsoft Exchange|AuditLogsQuery-Exchange.Read.All|Not supported|AuditLogsQuery-Exchange.Read.All| +|Microsoft SharePoint|AuditLogsQuery-SharePoint.Read.All|Not supported|AuditLogsQuery-SharePoint.Read.All| +|Microsoft Intune|AuditLogsQuery-Endpoint.Read.All|Not supported|AuditLogsQuery-Endpoint.Read.All| +|Microsoft Dynamics CRM|AuditLogsQuery-CRM.Read.All|Not supported|AuditLogsQuery-CRM.Read.All| +|Microsoft Entra|AuditLogsQuery-Entra.Read.All|Not supported|AuditLogsQuery-Entra.Read.All| +|All Audit Logs|AuditLogsQuery.Read.All|Not supported|AuditLogsQuery.Read.All| + +## HTTP request + + +``` http +GET /security/auditCore/auditLogQueries +``` + +## Optional query parameters +This method supports some of the OData query parameters to help customize the response. For general information, see [OData query parameters](/graph/query-parameters). + +## Request headers +|Name|Description| +|:---|:---| +|Authorization|Bearer {token}. Required.| + +## Request body +Don't supply a request body for this method. + +## Response + +If successful, this method returns a `200 OK` response code and a collection of [auditLogQuery](../resources/security-auditlogquery.md) objects in the response body. + +## Examples + +### Request +The following example shows a request. + +``` http +GET https://graph.microsoft.com/beta/security/auditCore/auditLogQueries +``` + + +### Response +The following example shows the response. +>**Note:** The response object shown here might be shortened for readability. + +``` http +HTTP/1.1 200 OK +Content-Type: application/json + +{ + "value": [ + { + "@odata.type": "#microsoft.graph.security.auditLogQuery", + "id": "168ec429-084b-a489-90d8-504a87846305", + "displayName": "String", + "filterStartDateTime": "String (timestamp)", + "filterEndDateTime": "String (timestamp)", + "recordTypeFilter": "String", + "keywordFilter": "String", + "serviceFilter": "String", + "operationFilters": [ + "String" + ], + "userPrincipalNameFilters": [ + "String" + ], + "ipAddressFilters": [ + "String" + ], + "objectIdFilters": [ + "String" + ], + "administrativeUnitIdFilters": [ + "String" + ], + "status": "String" + } + ] +} +``` + diff --git a/api-reference/beta/api/security-auditcoreroot-post-auditlogqueries.md b/api-reference/beta/api/security-auditcoreroot-post-auditlogqueries.md new file mode 100644 index 00000000000..76b666526be --- /dev/null +++ b/api-reference/beta/api/security-auditcoreroot-post-auditlogqueries.md @@ -0,0 +1,159 @@ +--- +title: "Create auditLogQuery" +description: "Create a new auditLogQuery object." +author: "arishojaswi" +ms.localizationpriority: medium +ms.prod: "security" +doc_type: apiPageType +--- + +# Create auditLogQuery +Namespace: microsoft.graph.security + +[!INCLUDE [beta-disclaimer](../../includes/beta-disclaimer.md)] + +Create a new [auditLogQuery](../resources/security-auditlogquery.md) object. + +## Permissions +Auditing data can be accessed through Microsoft Purview Audit Search API via the following permissions, which are classified at a Microsoft 365 service level. To learn more, including how to choose permissions, see [Permissions](/graph/permissions-reference). + + + +|Microsoft 365 service|Delegated (work or school account)|Delegated (personal Microsoft account)|Application +|:---|:---|:---|:---| +|Microsoft OneDrive|AuditLogsQuery-OneDrive.Read.All|Not supported|AuditLogsQuery-OneDrive.Read.All| +|Microsoft Exchange|AuditLogsQuery-Exchange.Read.All|Not supported|AuditLogsQuery-Exchange.Read.All| +|Microsoft SharePoint|AuditLogsQuery-SharePoint.Read.All|Not supported|AuditLogsQuery-SharePoint.Read.All| +|Microsoft Intune|AuditLogsQuery-Endpoint.Read.All|Not supported|AuditLogsQuery-Endpoint.Read.All| +|Microsoft Dynamics CRM|AuditLogsQuery-CRM.Read.All|Not supported|AuditLogsQuery-CRM.Read.All| +|Microsoft Entra|AuditLogsQuery-Entra.Read.All|Not supported|AuditLogsQuery-Entra.Read.All| +|All Audit Logs|AuditLogsQuery.Read.All|Not supported|AuditLogsQuery.Read.All| + + +## HTTP request + + +``` http +POST /security/auditCore/auditLogQueries +``` + +## Request headers +|Name|Description| +|:---|:---| +|Authorization|Bearer {token}. Required.| +|Content-Type|application/json. Required.| + +## Request body +In the request body, supply a JSON representation of the [auditLogQuery](../resources/security-auditlogquery.md) object. + +You can specify the following properties when creating a **auditLogQuery**. + +|Property|Type|Description| +|:---|:---|:---| +|displayName|String|Display name for the saved audit log query. Optional.| +|filterStartDateTime|DateTimeOffset|Start date of the date range in the query. Optional.| +|filterEndDateTime|DateTimeOffset|End date of the date range in the query. Optional.| +|recordTypeFilter|microsoft.graph.security.auditLogRecordType|The type of operation indicated by the record. The possible values are: `exchangeAdmin`, `exchangeItem`, `exchangeItemGroup`, `sharePoint`, `syntheticProbe`, `sharePointFileOperation`, `oneDrive`, `azureActiveDirectory`, `azureActiveDirectoryAccountLogon`, `dataCenterSecurityCmdlet`, `complianceDLPSharePoint`, `sway`, `complianceDLPExchange`, `sharePointSharingOperation`, `azureActiveDirectoryStsLogon`, `skypeForBusinessPSTNUsage`, `skypeForBusinessUsersBlocked`, `securityComplianceCenterEOPCmdlet`, `exchangeAggregatedOperation`, `powerBIAudit`, `crm`, `yammer`, `skypeForBusinessCmdlets`, `discovery`, `microsoftTeams`, `threatIntelligence`, `mailSubmission`, `microsoftFlow`, `aeD`, `microsoftStream`, `complianceDLPSharePointClassification`, `threatFinder`, `project`, `sharePointListOperation`, `sharePointCommentOperation`, `dataGovernance`, `kaizala`, `securityComplianceAlerts`, `threatIntelligenceUrl`, `securityComplianceInsights`, `mipLabel`, `workplaceAnalytics`, `powerAppsApp`, `powerAppsPlan`, `threatIntelligenceAtpContent`, `labelContentExplorer`, `teamsHealthcare`, `exchangeItemAggregated`, `hygieneEvent`, `dataInsightsRestApiAudit`, `informationBarrierPolicyApplication`, `sharePointListItemOperation`, `sharePointContentTypeOperation`, `sharePointFieldOperation`, `microsoftTeamsAdmin`, `hrSignal`, `microsoftTeamsDevice`, `microsoftTeamsAnalytics`, `informationWorkerProtection`, `campaign`, `dlpEndpoint`, `airInvestigation`, `quarantine`, `microsoftForms`, `applicationAudit`, `complianceSupervisionExchange`, `customerKeyServiceEncryption`, `officeNative`, `mipAutoLabelSharePointItem`, `mipAutoLabelSharePointPolicyLocation`, `microsoftTeamsShifts`, `secureScore`, `mipAutoLabelExchangeItem`, `cortanaBriefing`, `search`, `wdatpAlerts`, `powerPlatformAdminDlp`, `powerPlatformAdminEnvironment`, `mdatpAudit`, `sensitivityLabelPolicyMatch`, `sensitivityLabelAction`, `sensitivityLabeledFileAction`, `attackSim`, `airManualInvestigation`, `securityComplianceRBAC`, `userTraining`, `airAdminActionInvestigation`, `mstic`, `physicalBadgingSignal`, `teamsEasyApprovals`, `aipDiscover`, `aipSensitivityLabelAction`, `aipProtectionAction`, `aipFileDeleted`, `aipHeartBeat`, `mcasAlerts`, `onPremisesFileShareScannerDlp`, `onPremisesSharePointScannerDlp`, `exchangeSearch`, `sharePointSearch`, `privacyDataMinimization`, `labelAnalyticsAggregate`, `myAnalyticsSettings`, `securityComplianceUserChange`, `complianceDLPExchangeClassification`, `complianceDLPEndpoint`, `mipExactDataMatch`, `msdeResponseActions`, `msdeGeneralSettings`, `msdeIndicatorsSettings`, `ms365DCustomDetection`, `msdeRolesSettings`, `mapgAlerts`, `mapgPolicy`, `mapgRemediation`, `privacyRemediationAction`, `privacyDigestEmail`, `mipAutoLabelSimulationProgress`, `mipAutoLabelSimulationCompletion`, `mipAutoLabelProgressFeedback`, `dlpSensitiveInformationType`, `mipAutoLabelSimulationStatistics`, `largeContentMetadata`, `microsoft365Group`, `cdpMlInferencingResult`, `filteringMailMetadata`, `cdpClassificationMailItem`, `cdpClassificationDocument`, `officeScriptsRunAction`, `filteringPostMailDeliveryAction`, `cdpUnifiedFeedback`, `tenantAllowBlockList`, `consumptionResource`, `healthcareSignal`, `dlpImportResult`, `cdpCompliancePolicyExecution`, `multiStageDisposition`, `privacyDataMatch`, `filteringDocMetadata`, `filteringEmailFeatures`, `powerBIDlp`, `filteringUrlInfo`, `filteringAttachmentInfo`, `coreReportingSettings`, `complianceConnector`, `powerPlatformLockboxResourceAccessRequest`, `powerPlatformLockboxResourceCommand`, `cdpPredictiveCodingLabel`, `cdpCompliancePolicyUserFeedback`, `webpageActivityEndpoint`, `omePortal`, `cmImprovementActionChange`, `filteringUrlClick`, `mipLabelAnalyticsAuditRecord`, `filteringEntityEvent`, `filteringRuleHits`, `filteringMailSubmission`, `labelExplorer`, `microsoftManagedServicePlatform`, `powerPlatformServiceActivity`, `scorePlatformGenericAuditRecord`, `filteringTimeTravelDocMetadata`, `alert`, `alertStatus`, `alertIncident`, `incidentStatus`, `case`, `caseInvestigation`, `recordsManagement`, `privacyRemediation`, `dataShareOperation`, `cdpDlpSensitive`, `ehrConnector`, `filteringMailGradingResult`, `publicFolder`, `privacyTenantAuditHistoryRecord`, `aipScannerDiscoverEvent`, `eduDataLakeDownloadOperation`, `m365ComplianceConnector`, `microsoftGraphDataConnectOperation`, `microsoftPurview`, `filteringEmailContentFeatures`, `powerPagesSite`, `powerAppsResource`, `plannerPlan`, `plannerCopyPlan`, `plannerTask`, `plannerRoster`, `plannerPlanList`, `plannerTaskList`, `plannerTenantSettings`, `projectForTheWebProject`, `projectForTheWebTask`, `projectForTheWebRoadmap`, `projectForTheWebRoadmapItem`, `projectForTheWebProjectSettings`, `projectForTheWebRoadmapSettings`, `quarantineMetadata`, `microsoftTodoAudit`, `timeTravelFilteringDocMetadata`, `teamsQuarantineMetadata`, `sharePointAppPermissionOperation`, `microsoftTeamsSensitivityLabelAction`, `filteringTeamsMetadata`, `filteringTeamsUrlInfo`, `filteringTeamsPostDeliveryAction`, `mdcAssessments`, `mdcRegulatoryComplianceStandards`, `mdcRegulatoryComplianceControls`, `mdcRegulatoryComplianceAssessments`, `mdcSecurityConnectors`, `mdaDataSecuritySignal`, `vivaGoals`, `filteringRuntimeInfo`, `attackSimAdmin`, `microsoftGraphDataConnectConsent`, `filteringAtpDetonationInfo`, `privacyPortal`, `managedTenants`, `unifiedSimulationMatchedItem`, `unifiedSimulationSummary`, `updateQuarantineMetadata`, `ms365DSuppressionRule`, `purviewDataMapOperation`, `filteringUrlPostClickAction`, `irmUserDefinedDetectionSignal`, `teamsUpdates`, `plannerRosterSensitivityLabel`, `ms365DIncident`, `filteringDelistingMetadata`, `complianceDLPSharePointClassificationExtended`, `microsoftDefenderForIdentityAudit`, `supervisoryReviewDayXInsight`, `defenderExpertsforXDRAdmin`, `cdpEdgeBlockedMessage`, `hostedRpa`, `cdpContentExplorerAggregateRecord`, `cdpHygieneAttachmentInfo`, `cdpHygieneSummary`, `cdpPostMailDeliveryAction`, `cdpEmailFeatures`, `cdpHygieneUrlInfo`, `cdpUrlClick`, `cdpPackageManagerHygieneEvent`, `filteringDocScan`, `timeTravelFilteringDocScan`, `mapgOnboard`, `unknownFutureValue`. Optional.| +|keywordFilter|String|Free text field to search non-indexed properties of the audit log. Optional.| +|serviceFilter|String|The Office 365 service where the activity occurred. Optional.| +|operationFilters|String collection|The name of the user or admin activity. For a description of the most common operations/activities, see [Search the audit log in the Office 365 Protection Center](https://go.microsoft.com/fwlink/p/?LinkId=708432). Optional.| +|userPrincipalNameFilters|String collection|The UPN (user principal name) of the user who performed the action (specified in the operation property) that resulted in the record being logged; for example, _my_name@my_domain_name_. Optional.| +|ipAddressFilters|String collection|The IP address of the device that was used when the activity was logged. Optional.| +|objectIdFilters|String collection|For SharePoint and OneDrive for Business activity, the full path name of the file or folder accessed by the user. For Exchange admin audit logging, the name of the object that was modified by the cmdlet. Optional.| +|administrativeUnitIdFilters|String collection|Administrative units tagged to an audit log record. Optional.| +|status|microsoft.graph.security.auditLogQueryStatus|Current status of the query. The possible values are: `notStarted`, `running`, `succeeded`, `failed`, `cancelled`, `unknownFutureValue`. Optional.| + + + +## Response + +If successful, this method returns a `201 Created` response code and a [auditLogQuery](../resources/security-auditlogquery.md) object in the response body. + +## Examples + +### Request +The following example shows a request. + +``` http +POST https://graph.microsoft.com/beta/security/auditCore/auditLogQueries +Content-Type: application/json + +{ + "@odata.type": "#microsoft.graph.security.auditLogQuery", + "displayName": "String", + "filterStartDateTime": "String (timestamp)", + "filterEndDateTime": "String (timestamp)", + "recordTypeFilter": "String", + "keywordFilter": "String", + "serviceFilter": "String", + "operationFilters": [ + "String" + ], + "userPrincipalNameFilters": [ + "String" + ], + "ipAddressFilters": [ + "String" + ], + "objectIdFilters": [ + "String" + ], + "administrativeUnitIdFilters": [ + "String" + ], + "status": "String" +} +``` + + +### Response +The following example shows the response. +>**Note:** The response object shown here might be shortened for readability. + +``` http +HTTP/1.1 201 Created +Content-Type: application/json + +{ + "@odata.type": "#microsoft.graph.security.auditLogQuery", + "id": "168ec429-084b-a489-90d8-504a87846305", + "displayName": "String", + "filterStartDateTime": "String (timestamp)", + "filterEndDateTime": "String (timestamp)", + "recordTypeFilter": "String", + "keywordFilter": "String", + "serviceFilter": "String", + "operationFilters": [ + "String" + ], + "userPrincipalNameFilters": [ + "String" + ], + "ipAddressFilters": [ + "String" + ], + "objectIdFilters": [ + "String" + ], + "administrativeUnitIdFilters": [ + "String" + ], + "status": "String" +} +``` + diff --git a/api-reference/beta/api/security-auditlogquery-get.md b/api-reference/beta/api/security-auditlogquery-get.md new file mode 100644 index 00000000000..76dbf0b8764 --- /dev/null +++ b/api-reference/beta/api/security-auditlogquery-get.md @@ -0,0 +1,116 @@ +--- +title: "Get auditLogQuery" +description: "Read the properties and relationships of an auditLogQuery object." +author: "arishojaswi" +ms.localizationpriority: medium +ms.prod: "security" +doc_type: apiPageType +--- + +# Get auditLogQuery +Namespace: microsoft.graph.security + +[!INCLUDE [beta-disclaimer](../../includes/beta-disclaimer.md)] + +Read the properties and relationships of an [auditLogQuery](../resources/security-auditlogquery.md) object. + +## Permissions +Auditing data can be accessed through Microsoft Purview Audit Search API via the following permissions, which are classified at a Microsoft 365 service level. To learn more, including how to choose permissions, see [Permissions](/graph/permissions-reference). + + + +|Microsoft 365 Service|Delegated (work or school account)|Delegated (personal Microsoft account)|Application +|:---|:---|:---|:---| +|Microsoft OneDrive|AuditLogsQuery-OneDrive.Read.All|Not supported|AuditLogsQuery-OneDrive.Read.All| +|Microsoft Exchange|AuditLogsQuery-Exchange.Read.All|Not supported|AuditLogsQuery-Exchange.Read.All| +|Microsoft SharePoint|AuditLogsQuery-SharePoint.Read.All|Not supported|AuditLogsQuery-SharePoint.Read.All| +|Microsoft Intune|AuditLogsQuery-Endpoint.Read.All|Not supported|AuditLogsQuery-Endpoint.Read.All| +|Microsoft Dynamics CRM|AuditLogsQuery-CRM.Read.All|Not supported|AuditLogsQuery-CRM.Read.All| +|Microsoft Entra|AuditLogsQuery-Entra.Read.All|Not supported|AuditLogsQuery-Entra.Read.All| +|All Audit Logs|AuditLogsQuery.Read.All|Not supported|AuditLogsQuery.Read.All| + +## HTTP request + + +``` http +GET /security/auditCore/auditLogQueries/{auditLogQueryId} +``` + +## Optional query parameters +This method supports some of the OData query parameters to help customize the response. For general information, see [OData query parameters](/graph/query-parameters). + +## Request headers +|Name|Description| +|:---|:---| +|Authorization|Bearer {token}. Required.| + +## Request body +Don't supply a request body for this method. + +## Response + +If successful, this method returns a `200 OK` response code and a [auditLogQuery](../resources/security-auditlogquery.md) object in the response body. + +## Examples + +### Request +The following example shows a request. + +``` http +GET https://graph.microsoft.com/beta/security/auditCore/auditLogQueries/{auditLogQueryId} +``` + + +### Response +The following example shows the response. +>**Note:** The response object shown here might be shortened for readability. + +``` http +HTTP/1.1 200 OK +Content-Type: application/json + +{ + "value": { + "@odata.type": "#microsoft.graph.security.auditLogQuery", + "id": "168ec429-084b-a489-90d8-504a87846305", + "displayName": "String", + "filterStartDateTime": "String (timestamp)", + "filterEndDateTime": "String (timestamp)", + "recordTypeFilter": "String", + "keywordFilter": "String", + "serviceFilter": "String", + "operationFilters": [ + "String" + ], + "userPrincipalNameFilters": [ + "String" + ], + "ipAddressFilters": [ + "String" + ], + "objectIdFilters": [ + "String" + ], + "administrativeUnitIdFilters": [ + "String" + ], + "status": "String" + } +} +``` + diff --git a/api-reference/beta/api/security-auditlogquery-list-records.md b/api-reference/beta/api/security-auditlogquery-list-records.md new file mode 100644 index 00000000000..10fab83a46c --- /dev/null +++ b/api-reference/beta/api/security-auditlogquery-list-records.md @@ -0,0 +1,123 @@ +--- +title: "List auditLogRecords" +description: "Get a list of auditLogRecord objects and their properties." +author: "arishojaswi" +ms.localizationpriority: medium +ms.prod: "security" +doc_type: apiPageType +--- + +# List auditLogRecords + +Namespace: microsoft.graph.security + +[!INCLUDE [beta-disclaimer](../../includes/beta-disclaimer.md)] + +Get a list of the [auditLogRecord](../resources/security-auditlogrecord.md) objects and their properties. + +## Permissions + +Auditing data can be accessed through Microsoft Purview Audit Search API via the following permissions, which are classified at a Microsoft 365 service level. To learn more, including how to choose permissions, see [Permissions](/graph/permissions-reference). + + + +|Microsoft 365 Service|Delegated (work or school account)|Delegated (personal Microsoft account)|Application +|:---|:---|:---|:---| +|Microsoft OneDrive|AuditLogsQuery-OneDrive.Read.All|Not supported|AuditLogsQuery-OneDrive.Read.All| +|Microsoft Exchange|AuditLogsQuery-Exchange.Read.All|Not supported|AuditLogsQuery-Exchange.Read.All| +|Microsoft SharePoint|AuditLogsQuery-SharePoint.Read.All|Not supported|AuditLogsQuery-SharePoint.Read.All| +|Microsoft Intune|AuditLogsQuery-Endpoint.Read.All|Not supported|AuditLogsQuery-Endpoint.Read.All| +|Microsoft Dynamics CRM|AuditLogsQuery-CRM.Read.All|Not supported|AuditLogsQuery-CRM.Read.All| +|Microsoft Entra|AuditLogsQuery-Entra.Read.All|Not supported|AuditLogsQuery-Entra.Read.All| +|All Audit Logs|AuditLogsQuery.Read.All|Not supported|AuditLogsQuery.Read.All| + +## HTTP request + + + +```http +GET /security/auditCore/auditLogQueries/{auditLogQueryId}/records +``` + +## Optional query parameters + +This method supports some of the OData query parameters to help customize the response. For general information, see [OData query parameters](/graph/query-parameters). + +## Request headers + +| Name | Description | +| :------------ | :------------------------ | +| Authorization | Bearer {token}. Required. | + +## Request body + +Don't supply a request body for this method. + +## Response + +If successful, this method returns a `200 OK` response code and a collection of [auditLogRecord](../resources/security-auditlogrecord.md) objects in the response body. + +## Examples + +### Request + +The following example shows a request. + + + +```http +GET https://graph.microsoft.com/beta/security/auditCore/auditLogQueries/{auditLogQueryId}/records +``` + +### Response + +The following example shows the response. + +> **Note:** The response object shown here might be shortened for readability. + + + +```http +HTTP/1.1 200 OK +Content-Type: application/json + +{ + "value": [ + { + "@odata.type": "#microsoft.graph.security.auditLogRecord", + "id": "40706737-7eca-f9a1-97a5-dedd3260e24a", + "createdDateTime": "String (timestamp)", + "auditLogRecordType": "String", + "operation": "String", + "organizationId": "String", + "userType": "String", + "userId": "String", + "service": "String", + "objectId": "String", + "userPrincipalName": "String", + "clientIp": "String", + "administrativeUnits": [ + "String" + ], + "auditData": { + "@odata.type": "microsoft.graph.security.auditData" + } + } + ] +} +``` diff --git a/api-reference/beta/resources/enums-security.md b/api-reference/beta/resources/enums-security.md index e9d70750f65..393736bf39e 100644 --- a/api-reference/beta/resources/enums-security.md +++ b/api-reference/beta/resources/enums-security.md @@ -1,7 +1,7 @@ --- title: "Security enum values" description: "Microsoft Graph security subnamespace enumeration values" -doc_type: enumPageType +doc_type: enumPageType" ms.localizationpriority: medium ms.prod: "security" author: "BenAlfasi" @@ -11,7 +11,288 @@ author: "BenAlfasi" Namespace: microsoft.graph.security - +### auditLogQueryStatus values + +|Member| +|:---| +|notStarted| +|running| +|succeeded| +|failed| +|cancelled| +|unknownFutureValue| + +### auditLogRecordType values + +|Member| +|:---| +|exchangeAdmin| +|exchangeItem| +|exchangeItemGroup| +|sharePoint| +|syntheticProbe| +|sharePointFileOperation| +|oneDrive| +|azureActiveDirectory| +|azureActiveDirectoryAccountLogon| +|dataCenterSecurityCmdlet| +|complianceDLPSharePoint| +|sway| +|complianceDLPExchange| +|sharePointSharingOperation| +|azureActiveDirectoryStsLogon| +|skypeForBusinessPSTNUsage| +|skypeForBusinessUsersBlocked| +|securityComplianceCenterEOPCmdlet| +|exchangeAggregatedOperation| +|powerBIAudit| +|crm| +|yammer| +|skypeForBusinessCmdlets| +|discovery| +|microsoftTeams| +|threatIntelligence| +|mailSubmission| +|microsoftFlow| +|aeD| +|microsoftStream| +|complianceDLPSharePointClassification| +|threatFinder| +|project| +|sharePointListOperation| +|sharePointCommentOperation| +|dataGovernance| +|kaizala| +|securityComplianceAlerts| +|threatIntelligenceUrl| +|securityComplianceInsights| +|mipLabel| +|workplaceAnalytics| +|powerAppsApp| +|powerAppsPlan| +|threatIntelligenceAtpContent| +|labelContentExplorer| +|teamsHealthcare| +|exchangeItemAggregated| +|hygieneEvent| +|dataInsightsRestApiAudit| +|informationBarrierPolicyApplication| +|sharePointListItemOperation| +|sharePointContentTypeOperation| +|sharePointFieldOperation| +|microsoftTeamsAdmin| +|hrSignal| +|microsoftTeamsDevice| +|microsoftTeamsAnalytics| +|informationWorkerProtection| +|campaign| +|dlpEndpoint| +|airInvestigation| +|quarantine| +|microsoftForms| +|applicationAudit| +|complianceSupervisionExchange| +|customerKeyServiceEncryption| +|officeNative| +|mipAutoLabelSharePointItem| +|mipAutoLabelSharePointPolicyLocation| +|microsoftTeamsShifts| +|secureScore| +|mipAutoLabelExchangeItem| +|cortanaBriefing| +|search| +|wdatpAlerts| +|powerPlatformAdminDlp| +|powerPlatformAdminEnvironment| +|mdatpAudit| +|sensitivityLabelPolicyMatch| +|sensitivityLabelAction| +|sensitivityLabeledFileAction| +|attackSim| +|airManualInvestigation| +|securityComplianceRBAC| +|userTraining| +|airAdminActionInvestigation| +|mstic| +|physicalBadgingSignal| +|teamsEasyApprovals| +|aipDiscover| +|aipSensitivityLabelAction| +|aipProtectionAction| +|aipFileDeleted| +|aipHeartBeat| +|mcasAlerts| +|onPremisesFileShareScannerDlp| +|onPremisesSharePointScannerDlp| +|exchangeSearch| +|sharePointSearch| +|privacyDataMinimization| +|labelAnalyticsAggregate| +|myAnalyticsSettings| +|securityComplianceUserChange| +|complianceDLPExchangeClassification| +|complianceDLPEndpoint| +|mipExactDataMatch| +|msdeResponseActions| +|msdeGeneralSettings| +|msdeIndicatorsSettings| +|ms365DCustomDetection| +|msdeRolesSettings| +|mapgAlerts| +|mapgPolicy| +|mapgRemediation| +|privacyRemediationAction| +|privacyDigestEmail| +|mipAutoLabelSimulationProgress| +|mipAutoLabelSimulationCompletion| +|mipAutoLabelProgressFeedback| +|dlpSensitiveInformationType| +|mipAutoLabelSimulationStatistics| +|largeContentMetadata| +|microsoft365Group| +|cdpMlInferencingResult| +|filteringMailMetadata| +|cdpClassificationMailItem| +|cdpClassificationDocument| +|officeScriptsRunAction| +|filteringPostMailDeliveryAction| +|cdpUnifiedFeedback| +|tenantAllowBlockList| +|consumptionResource| +|healthcareSignal| +|dlpImportResult| +|cdpCompliancePolicyExecution| +|multiStageDisposition| +|privacyDataMatch| +|filteringDocMetadata| +|filteringEmailFeatures| +|powerBIDlp| +|filteringUrlInfo| +|filteringAttachmentInfo| +|coreReportingSettings| +|complianceConnector| +|powerPlatformLockboxResourceAccessRequest| +|powerPlatformLockboxResourceCommand| +|cdpPredictiveCodingLabel| +|cdpCompliancePolicyUserFeedback| +|webpageActivityEndpoint| +|omePortal| +|cmImprovementActionChange| +|filteringUrlClick| +|mipLabelAnalyticsAuditRecord| +|filteringEntityEvent| +|filteringRuleHits| +|filteringMailSubmission| +|labelExplorer| +|microsoftManagedServicePlatform| +|powerPlatformServiceActivity| +|scorePlatformGenericAuditRecord| +|filteringTimeTravelDocMetadata| +|alert| +|alertStatus| +|alertIncident| +|incidentStatus| +|case| +|caseInvestigation| +|recordsManagement| +|privacyRemediation| +|dataShareOperation| +|cdpDlpSensitive| +|ehrConnector| +|filteringMailGradingResult| +|publicFolder| +|privacyTenantAuditHistoryRecord| +|aipScannerDiscoverEvent| +|eduDataLakeDownloadOperation| +|m365ComplianceConnector| +|microsoftGraphDataConnectOperation| +|microsoftPurview| +|filteringEmailContentFeatures| +|powerPagesSite| +|powerAppsResource| +|plannerPlan| +|plannerCopyPlan| +|plannerTask| +|plannerRoster| +|plannerPlanList| +|plannerTaskList| +|plannerTenantSettings| +|projectForTheWebProject| +|projectForTheWebTask| +|projectForTheWebRoadmap| +|projectForTheWebRoadmapItem| +|projectForTheWebProjectSettings| +|projectForTheWebRoadmapSettings| +|quarantineMetadata| +|microsoftTodoAudit| +|timeTravelFilteringDocMetadata| +|teamsQuarantineMetadata| +|sharePointAppPermissionOperation| +|microsoftTeamsSensitivityLabelAction| +|filteringTeamsMetadata| +|filteringTeamsUrlInfo| +|filteringTeamsPostDeliveryAction| +|mdcAssessments| +|mdcRegulatoryComplianceStandards| +|mdcRegulatoryComplianceControls| +|mdcRegulatoryComplianceAssessments| +|mdcSecurityConnectors| +|mdaDataSecuritySignal| +|vivaGoals| +|filteringRuntimeInfo| +|attackSimAdmin| +|microsoftGraphDataConnectConsent| +|filteringAtpDetonationInfo| +|privacyPortal| +|managedTenants| +|unifiedSimulationMatchedItem| +|unifiedSimulationSummary| +|updateQuarantineMetadata| +|ms365DSuppressionRule| +|purviewDataMapOperation| +|filteringUrlPostClickAction| +|irmUserDefinedDetectionSignal| +|teamsUpdates| +|plannerRosterSensitivityLabel| +|ms365DIncident| +|filteringDelistingMetadata| +|complianceDLPSharePointClassificationExtended| +|microsoftDefenderForIdentityAudit| +|supervisoryReviewDayXInsight| +|defenderExpertsforXDRAdmin| +|cdpEdgeBlockedMessage| +|hostedRpa| +|cdpContentExplorerAggregateRecord| +|cdpHygieneAttachmentInfo| +|cdpHygieneSummary| +|cdpPostMailDeliveryAction| +|cdpEmailFeatures| +|cdpHygieneUrlInfo| +|cdpUrlClick| +|cdpPackageManagerHygieneEvent| +|filteringDocScan| +|timeTravelFilteringDocScan| +|mapgOnboard| +|unknownFutureValue| + +### auditLogUserType values + + + +|Member| +|:---| +|regular| +|reserved| +|admin| +|dcAdmin| +|system| +|application| +|servicePrincipal| +|customPolicy| +|systemPolicy| +|partnerTechnician| +|guest| +|unknownFutureValue| ### actionAfterRetentionPeriod values | Member | diff --git a/api-reference/beta/resources/enums.md b/api-reference/beta/resources/enums.md index 47adc9331b4..766ef9a53fd 100644 --- a/api-reference/beta/resources/enums.md +++ b/api-reference/beta/resources/enums.md @@ -2669,7 +2669,7 @@ Possible values for user account types (group membership), per Windows definitio | :-------------------------------- | :-------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | None | 0 | User isn't allowed to override the message. User isn't allowed to report a message as false positive if policyTip isn't provided. In all other scenarios, user can report a message as false positive. | | AllowFalsePositiveOverride | 1 | User isn't allowed to explicitly override the block unless this is combined with `AllowOverrideWithoutJustification` or `AllowOverrideWithJustification` flags. Reporting a false positive on the violation automatically overrides the block and sends the message. | -| AllowOverrideWithoutJustification | 2 | User is allowed to override the block and send the message. Justification text is not required. Exclusive to `AllowOverrideWithJustification`. | +| AllowOverrideWithoutJustification | 2 | User is allowed to override the block and send the message. Justification text isn't required. Exclusive to `AllowOverrideWithJustification`. | | AllowOverrideWithJustification | 4 | User is allowed to override the block and send the message. Justification text is required. Exclusive to `AllowOverrideWithoutJustification`. | ### entityType values @@ -2916,10 +2916,10 @@ Possible values for user account types (group membership), per Windows definitio ### threatExpectedAssessment values -| Member | Value | Description | -| :------ | :---- | :-------------------------------- | -| block | 1 | The threat should be blocked. | -| unblock | 2 | The threat should not be blocked. | +| Member | Value | Description | +| :------ | :---- | :------------------------------- | +| block | 1 | The threat should be blocked. | +| unblock | 2 | The threat shouldn't be blocked. | ### threatCategory values @@ -3049,7 +3049,7 @@ Possible values for user account types (group membership), per Windows definitio | Member | Value | Description | | :----------------- | :---- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | configured | 0 | Connected Organizations with this state value are included in assignment policies with requestor scope type `AllConfiguredConnectedOrganizationSubjects`. | -| proposed | 1 | Connected Organizations that are automatically created by the system have this state value. They are not included in assignment policies with requestor scope type `AllConfiguredConnectedOrganizationSubjects`. | +| proposed | 1 | Connected Organizations that are automatically created by the system have this state value. They aren't included in assignment policies with requestor scope type `AllConfiguredConnectedOrganizationSubjects`. | | unknownFutureValue | 2 | A sentinel member. | ### identityUserFlowAttributeDataType values @@ -3115,8 +3115,8 @@ Possible values for user account types (group membership), per Windows definitio | Member | Value | Description | | :----------------- | :---- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| oneOnOne | 0 | Indicates that the chat is a 1:1 chat. The roster size is fixed for this type of chat, the member cannot be removed / added. | -| group | 1 | Indicates that the chat is a Group chat. The roster size (of at least 2 person) can be updated for this type of chat. The members can be removed / added later on. | +| oneOnOne | 0 | Indicates that the chat is a 1:1 chat. The roster size is fixed for this type of chat, the member can't be removed / added. | +| group | 1 | Indicates that the chat is a Group chat. The roster size (of at least two person) can be updated for this type of chat. The members can be removed / added later on. | | meeting | 2 | Indicates that the chat is a Meeting chat, which is created as a side effect of creation of an OnlineMeeting. | | unknownFutureValue | 3 | Sentinel value to indicate future values. | @@ -3637,26 +3637,26 @@ Possible values for user account types (group membership), per Windows definitio ### teamworkDeviceActivityState values -| Member | Value | Description | -| :----------------- | :---- | :------------------------------------------------ | -| unknown | 0 | Unknown state. | -| busy | 1 | The device is busy. | -| idle | 2 | The device is idle. | -| unavailable | 3 | The device is unavailable. | -| unknownFutureValue | 4 | Evolvable enumeration sentinel value. Do not use. | +| Member | Value | Description | +| :----------------- | :---- | :----------------------------------------------- | +| unknown | 0 | Unknown state. | +| busy | 1 | The device is busy. | +| idle | 2 | The device is idle. | +| unavailable | 3 | The device is unavailable. | +| unknownFutureValue | 4 | Evolvable enumeration sentinel value. Don't use. | ### teamworkDeviceOperationType values -| Member | Value | Description | -| :-------------------------------- | :---- | :------------------------------------------------ | -| deviceRestart | 0 | Restart a device. | -| configUpdate | 1 | Update the device configuration. | -| deviceDiagnostics | 2 | Get the device logs. | -| softwareUpdate | 3 | Update a software on the device. | -| deviceManagementAgentConfigUpdate | 4 | Update the device agent configuration. | -| remoteLogin | 5 | Device remote login. | -| remoteLogout | 6 | Device remote logout. | -| unknownFutureValue | 7 | Evolvable enumeration sentinel value. Do not use. | +| Member | Value | Description | +| :-------------------------------- | :---- | :----------------------------------------------- | +| deviceRestart | 0 | Restart a device. | +| configUpdate | 1 | Update the device configuration. | +| deviceDiagnostics | 2 | Get the device logs. | +| softwareUpdate | 3 | Update a software on the device. | +| deviceManagementAgentConfigUpdate | 4 | Update the device agent configuration. | +| remoteLogin | 5 | Device remote login. | +| remoteLogout | 6 | Device remote logout. | +| unknownFutureValue | 7 | Evolvable enumeration sentinel value. Don't use. | ### teamworkSoftwareFreshness values @@ -3665,7 +3665,7 @@ Possible values for user account types (group membership), per Windows definitio | unknown | 0 | Unknown value. | | latest | 1 | Indicates whether a device component runs the latest version of the software. | | updateAvailable | 2 | Indicates that a software update is available for a device component. | -| unknownFutureValue | 3 | Evolvable enumeration sentinel value. Do not use. | +| unknownFutureValue | 3 | Evolvable enumeration sentinel value. Don't use. | ### teamworkSoftwareType values @@ -3688,7 +3688,7 @@ Possible values for user account types (group membership), per Windows definitio | teamsDefaultAndSkype | 2 | Supports both `Skype` and `Teams`. Default is `Teams`. | | skypeOnly | 3 | Supports only `Skype`. | | teamsOnly | 4 | Supports only `Teams`. | -| unknownFutureValue | 5 | Evolvable enumeration sentinel value. Do not use. | +| unknownFutureValue | 5 | Evolvable enumeration sentinel value. Don't use. | ### longRunningOperationStatus values diff --git a/api-reference/beta/resources/federatedidentitycredentials-overview.md b/api-reference/beta/resources/federatedidentitycredentials-overview.md index d740ffe3b61..bd4c77c2e8d 100644 --- a/api-reference/beta/resources/federatedidentitycredentials-overview.md +++ b/api-reference/beta/resources/federatedidentitycredentials-overview.md @@ -39,7 +39,7 @@ The combination of **issuer** and **subject** must be unique on the app. ## Design considerations -Federated identity credentials are supported on applications only. A maximum of 20 federated identity credentials can be added per application object. +A maximum of 20 federated identity credentials can be added per application object or user-assigned managed identity. ## See also diff --git a/api-reference/beta/resources/security-api-overview.md b/api-reference/beta/resources/security-api-overview.md index 7ba63d013bc..e2d3b7acf4f 100644 --- a/api-reference/beta/resources/security-api-overview.md +++ b/api-reference/beta/resources/security-api-overview.md @@ -11,7 +11,7 @@ doc_type: resourcePageType [!INCLUDE [beta-disclaimer](../../includes/beta-disclaimer.md)] -The Microsoft Graph security API provides a unified interface and schema to integrate with security solutions from Microsoft and ecosystem partners. This empowers customers to streamline security operations and better defend against increasing cyber threats. The Microsoft Graph security API federates queries to all onboarded security providers and aggregates responses. Use the Microsoft Graph security API to build applications that: +The Microsoft Graph security API provides a unified interface and schema to integrate with security solutions from Microsoft and ecosystem partners. It empowers customers to streamline security operations and better defend against increasing cyber threats. The Microsoft Graph security API federates queries to all onboarded security providers and aggregates responses. Use the Microsoft Graph security API to build applications that: - Consolidate and correlate security alerts from multiple sources. - Pull and investigate all incidents and alerts from services that are part of or integrated with Microsoft 365 Defender. @@ -30,9 +30,9 @@ Take immediate action to defend against threats using the [securityAction](secur > **Note:** Currently security actions only support application permissions. ## Advanced hunting -Advanced hunting is a query-based threat hunting tool that lets you explore up to 30 days of raw data. You can proactively inspect events in your network to locate threat indicators and entities. The flexible access to data enables unconstrained hunting for both known and potential threats. +Advanced hunting is a query-based threat-hunting tool that lets you explore up to 30 days of raw data. You can proactively inspect events in your network to locate threat indicators and entities. The flexible access to data enables unconstrained hunting for both known and potential threats. -Use [runHuntingQuery](../api/security-security-runhuntingquery.md) to run a [Kusto Query Language](/azure/data-explorer/kusto/query/) (KQL) query on data stored in Microsoft 365 Defender. Leverage the returned result set to enrich an existing investigation or to uncover undetected threats in your network. +Use [runHuntingQuery](../api/security-security-runhuntingquery.md) to run a [Kusto Query Language](/azure/data-explorer/kusto/query/) (KQL) query on data stored in Microsoft 365 Defender. Leverage the returned result set to enrich an existing investigation or uncover undetected threats in your network. ### Quotas and resource allocation @@ -53,13 +53,13 @@ Use [runHuntingQuery](../api/security-security-runhuntingquery.md) to run a [Kus ## Alerts Alerts are detailed warnings about suspicious activities in a customer's tenant that Microsoft or partner security providers have identified and flagged for action. Attacks typically employ various techniques against different types of entities, such as devices, users, and mailboxes. The result is alerts from multiple security providers for multiple entities in the tenant. Piecing the individual alerts together to gain insight into an attack can be challenging and time-consuming. -The beta version of the security API offers two types of alerts that aggregate other alerts from security providers and make analyzing attacks and determining response easier: -- [Alerts and incidents](#alerts-and-incidents) - these are the latest generation of alerts in the Microsoft Graph security API. They are represented by the [alert](security-alert.md) resource and its collection, [incident](security-incident.md) resource, defined in the `microsoft.graph.security` namespace. -- [Legacy alerts](#legacy-alerts) - these are the first generation of alerts in the Microsoft Graph security API. They are represented by the [alert](alert.md) resource defined in the `microsoft.graph` namespace. +The beta version of the security API offers two types of alerts that aggregate other alerts from security providers and make analyzing attacks and determining responses easier: +- [Alerts and incidents](#alerts-and-incidents) - the latest generation of alerts in the Microsoft Graph security API. They are represented by the [alert](security-alert.md) resource and its collection, [incident](security-incident.md) resource, defined in the `microsoft.graph.security` namespace. +- [Legacy alerts](#legacy-alerts) - the first generation of alerts in the Microsoft Graph security API. They are represented by the [alert](alert.md) resource defined in the `microsoft.graph` namespace. ### Alerts and incidents -These [alert](security-alert.md) resources first pull alert data from security provider services, that are either part of or integrated with [Microsoft 365 Defender](/microsoft-365/security/defender/microsoft-365-defender?view=o365-worldwide&preserve-view=true). Then they consume the data to return rich, valuable clues about a completed or ongoing attack, the impacted assets, and associated [evidence](security-alertevidence.md). In addition, they automatically correlate other alerts with the same attack techniques or the same attacker into an [incident](security-incident.md) to provide a broader context of an attack. They recommend response and remediation actions, offering consistent actionability across all the different providers. The rich content makes it easier for analysts to collectively investigate and respond to threats. +These [alert](security-alert.md) resources first pull alert data from security provider services, that are either part of or integrated with [Microsoft 365 Defender](/microsoft-365/security/defender/microsoft-365-defender?view=o365-worldwide&preserve-view=true). Then they consume the data to return rich, valuable clues about a completed or ongoing attack, the impacted assets, and associated [evidence](security-alertevidence.md). In addition, they automatically correlate other alerts with the same attack techniques or the same attacker into an [incident](security-incident.md) to provide a broader context of an attack. They recommend response and remediation actions, offering consistent actionability across all the different providers. The rich content makes it easier for analysts to investigate and respond to threats collectively. Alerts from the following security providers are available via these rich alerts and incidents: - [Microsoft Entra ID Protection](/azure/active-directory/identity-protection/overview-identity-protection) @@ -73,7 +73,7 @@ Alerts from the following security providers are available via these rich alerts ### Legacy alerts -These [alert](alert.md) resources federate calling of supported Azure and Microsoft 365 Defender security providers. They aggregate common alert data among the different domains to allow applications to unify and streamline management of security issues across all integrated solutions. They enable applications to correlate alerts and context to improve threat protection and response. +These [alert](alert.md) resources federate calling of supported Azure and Microsoft 365 Defender security providers. They aggregate common alert data among the different domains to allow applications to unify and streamline the management of security issues across all integrated solutions. They enable applications to correlate alerts and context to improve threat protection and response. With the alert update capability, you can sync the status of specific alerts across different security products and services that are integrated with the Microsoft Graph security API by updating your **alert** entity. @@ -105,9 +105,14 @@ Alerts from the following security providers are available via this legacy **ale [Microsoft Purview eDiscovery (Premium)](/microsoft-365/compliance/overview-ediscovery-20) provides an end-to-end workflow to preserve, collect, analyze, review, and export content that's responsive to your organization's internal and external investigations. +## Audit logs query (preview) + +[Microsoft Purview Audit](/microsoft-365/compliance/audit-solutions-overview) provides an integrated solution to help organizations effectively respond to security events, forensic investigations, internal investigations, and compliance obligations. Thousands of user and admin operations performed in dozens of Microsoft 365 services and solutions are captured, recorded, and retained in your organization's unified audit log. Audit records for these events are searchable by security ops, IT admins, insider risk teams, and compliance and legal investigators in your organization. This capability provides visibility into the activities performed across your Microsoft 365 organization. + + ## Incidents -An [incident](security-incident.md) is a collection of correlated  [alerts](security-alert.md) and associated data that make up the story of an attack. Incident management is part of Microsoft 365 Defender, and is available in the Microsoft 365 Defender portal (https://security.microsoft.com/). +An [incident](security-incident.md) is a collection of correlated  [alerts](security-alert.md) and associated data that make up the story of an attack. Incident management is part of Microsoft 365 Defender and is available in the Microsoft 365 Defender portal (https://security.microsoft.com/). Microsoft 365 services and apps create  alerts  when they detect a suspicious or malicious event or activity. Individual alerts provide valuable clues about a completed or ongoing attack. However, attacks typically employ various techniques against different types of entities, such as devices, users, and mailboxes. The result is multiple  alerts for multiple entities in your tenant. @@ -127,13 +132,13 @@ The  [incident](security-incident.md) resource and its APIs allow you to sort **Labels** - Information protection labels provide details about how to properly apply a sensitivity label to information. The information protection label API describes the configuration of sensitivity labels that apply to a user or tenant. -**Threat assessment** - The Microsoft Graph threat assessment API helps organizations to assess the threat received by any user in a tenant. This empowers customers to report spam or suspicious emails, phishing URLs, or malware attachments they receive to Microsoft. Microsoft check the sample in question and the organizational policies in play before generating a result so that tenant administrators can understand the threat scanning verdict and adjust their organizational policy. They can also use it to report legitimate emails to prevent them from getting blocked. +**Threat assessment** - The Microsoft Graph threat assessment API helps organizations to assess the threat received by any user in a tenant. This empowers customers to report spam or suspicious emails, phishing URLs, or malware attachments they receive to Microsoft. Microsoft checks the sample in question and the organizational policies in play before generating a result so that tenant administrators can understand the threat scanning verdict and adjust their organizational policy. They can also use it to report legitimate emails to prevent them from getting blocked. > **Note:** We recommend that you use the [threat submission](https://github.com/microsoftgraph/microsoft-graph-docs/pull/16242/files#threat-submission) API instead. ## Secure Score -[Microsoft Secure Score](https://techcommunity.microsoft.com/t5/Security-Privacy-and-Compliance/Office-365-Secure-Score-is-now-Microsoft-Secure-Score/ba-p/182358) is a security analytics solution that gives you visibility into your security portfolio and how to improve it. With a single score, you can better understand what you have done to reduce your risk in Microsoft solutions. You can also compare your score with other organizations and see how your score has been trending over time. The [secureScore](securescores.md) and [secureScoreControlProfile](securescorecontrolprofiles.md) entities help you balance your organization's security and productivity needs while enabling the appropriate mix of security features. You can also project what your score would be after you adopt security features. +[Microsoft Secure Score](https://techcommunity.microsoft.com/t5/Security-Privacy-and-Compliance/Office-365-Secure-Score-is-now-Microsoft-Secure-Score/ba-p/182358) is a security analytics solution that gives you visibility into your security portfolio and how to improve it. With a single score, you can better understand what you have done to reduce your risk in Microsoft solutions. You can also compare your score with other organizations and see how your score has been trending over time. The [secureScore](securescores.md) and [secureScoreControlProfile](securescorecontrolprofiles.md) entities help you balance your organization's security and productivity needs while enabling the appropriate mix of security features. You can also project what your score will be after you adopt security features. ## Threat intelligence (preview) @@ -143,15 +148,19 @@ The threat intelligence APIs (preview) allow you to operationalize intelligence ## Threat intelligence indicators (preview) -Threat indicators, also referred to as indicators of compromise (IoCs), represent data about known threats, such as malicious files, URLs, domains, and IP addresses. Customers can generate indicators through internal threat intelligence gathering or acquire indicators from threat intelligence communities, licensed feeds, and other sources. These indicators are then used in various security tools to defend against related threats. +Threat indicators also referred to as indicators of compromise (IoCs), represent data about known threats, such as malicious files, URLs, domains, and IP addresses. Customers can generate indicators through internal threat intelligence gathering or acquire indicators from threat intelligence communities, licensed feeds, and other sources. These indicators are then used in various security tools to defend against related threats. The [tiIndicator](tiindicator.md) entity allows customers to feed threat indicators to Microsoft security solutions to take a block or alert action on a malicious activity, or to allow the activity that has been determined to be irrelevant to the organization and suppress actions for the indicator. To send an indicator, specify the Microsoft security solution intended to utilize the indicator and the action to take for that indicator. +You can integrate the [tiIndicator](tiindicator.md) entity into your application or use one of the following integrated threat intelligence platforms (TIP): + +- [Palo Alto Networks MineMeld Threat Intelligence Sharing](https://www.paloaltonetworks.com/products/secure-the-network/subscriptions/minemeld) +- [MISP Open Source Threat Intelligence Platform](http://www.misp-project.org/) available through the [TI sample](https://aka.ms/tipmispsample) + Threat indicators sent via the Microsoft Graph security API are available today in the following products: -- [Microsoft Defender for Endpoint](/windows/security/threat-protection/microsoft-defender-atp/microsoft-defender-advanced-threat-protection) – Enables you to alert and/or block on threat indicators associated with malicious activity. You can also allow an indicator for ignoring the indicator from automated investigations. For details about the types of indicators supported and limits on indicator counts per tenant, see [Manage indicators](/windows/security/threat-protection/microsoft-defender-atp/manage-indicators). +- [Microsoft Defender for Endpoint](/windows/security/threat-protection/microsoft-defender-atp/microsoft-defender-advanced-threat-protection) – Enables you to alert and/or block threat indicators associated with malicious activity. You can also allow an indicator for ignoring the indicator from automated investigations. For details about the types of indicators supported and limits on indicator counts per tenant, see [Manage indicators](/windows/security/threat-protection/microsoft-defender-atp/manage-indicators). - [Microsoft Sentinel](/azure/sentinel/overview) – Only existing customers can use the [tiIndicator](tiindicator.md) API to send threat intelligence indicators to Microsoft Sentinel. For the most up-to-date, detailed instructions on how to send threat intelligent indicators to Microsoft Sentinel, see [Connect your threat intelligence platform to Microsoft Sentinel](/azure/sentinel/connect-threat-intelligence-tip). - ## Threat submission The Microsoft Graph threat submission API helps organizations to submit a threat received by any user in a tenant. This empowers customers to report spam or suspicious emails, phishing URLs, or malware attachments they receive to Microsoft. Microsoft checks the submission against the organizational policies in effect and sends it to human graders for analysis. The result then helps tenant administrators understand the threat scanning verdict and adjust their organizational policy. Admins can also use the results to report legitimate emails to prevent them from getting blocked. diff --git a/api-reference/beta/resources/security-auditdata.md b/api-reference/beta/resources/security-auditdata.md new file mode 100644 index 00000000000..53f767e175f --- /dev/null +++ b/api-reference/beta/resources/security-auditdata.md @@ -0,0 +1,34 @@ +--- +title: "auditData resource type" +description: "Abstract type that supports the audit logs of various Microsoft 365 services." +author: "arishojaswi" +ms.localizationpriority: medium +ms.prod: "security" +doc_type: resourcePageType +--- + +# auditData resource type + +Namespace: microsoft.graph.security + +[!INCLUDE [beta-disclaimer](../../includes/beta-disclaimer.md)] + +An abstract type that supports the audit logs of various Microsoft 365 services like [defaultAuditData](../resources/security-defaultauditdata.md), which contains the JSON files of these Microsoft 365 services. + +## Relationships + +None. + +## JSON representation + +The following JSON representation shows the resource type. + +``` json +{ + "@odata.type": "#microsoft.graph.security.auditData" +} +``` diff --git a/api-reference/beta/resources/security-auditlogquery.md b/api-reference/beta/resources/security-auditlogquery.md new file mode 100644 index 00000000000..9560710503a --- /dev/null +++ b/api-reference/beta/resources/security-auditlogquery.md @@ -0,0 +1,89 @@ +--- +title: "auditLogQuery resource type" +description: "Represents an audit log query that is used to query and retrieve relevant audit log records." +author: "arishojaswi" +ms.localizationpriority: medium +ms.prod: "security" +doc_type: resourcePageType +--- + +# auditLogQuery resource type + +Namespace: microsoft.graph.security + +[!INCLUDE [beta-disclaimer](../../includes/beta-disclaimer.md)] + +Represents an audit log query that is used to query and retrieve relevant audit log records. + +Inherits from [microsoft.graph.entity](../resources/entity.md). + +## Methods +|Method|Return type|Description| +|:---|:---|:---| +|[List auditLogQueries](../api/security-auditcoreroot-list-auditlogqueries.md)|[auditLogQuery](../resources/security-auditlogquery.md) collection|Get a list of the [auditLogQuery](../resources/security-auditlogquery.md) objects and their properties.| +|[Create auditLogQuery](../api/security-auditcoreroot-post-auditlogqueries.md)|[auditLogQuery](../resources/security-auditlogquery.md)|Create a new [auditLogQuery](../resources/security-auditlogquery.md) object.| +|[Get auditLogQuery](../api/security-auditlogquery-get.md)|[auditLogQuery](../resources/security-auditlogquery.md)|Read the properties and relationships of a [auditLogQuery](../resources/security-auditlogquery.md) object.| +|[List records](../api/security-auditlogquery-list-records.md)|[auditLogRecord](../resources/security-auditlogrecord.md) collection|Get the auditLogRecord resources from the records navigation property.| + +## Properties +|Property|Type|Description| +|:---|:---|:---| +|administrativeUnitIdFilters|String collection|The administrative units tagged to an audit log record.| +|displayName|String|The display name of the saved audit log query.| +|filterEndDateTime|DateTimeOffset|The end date of the date range in the query.| +|filterStartDateTime|DateTimeOffset|The start date of the date range in the query.| +|id|String|Unique identifier for the audit log query. Inherited from [microsoft.graph.entity](../resources/entity.md).| +|ipAddressFilters|String collection|The IP address of the device that was used when the activity was logged.| +|keywordFilter|String|Free text field to search non-indexed properties of the audit log.| +|objectIdFilters|String collection|For SharePoint and OneDrive for Business activity, the full path name of the file or folder accessed by the user. For Exchange admin audit logging, the name of the object that was modified by the cmdlet.| +|operationFilters|String collection|The name of the user or admin activity. For a description of the most common operations/activities, see [Search the audit log in the Office 365 Protection Center](https://go.microsoft.com/fwlink/p/?LinkId=708432).| +|recordTypeFilter|microsoft.graph.security.auditLogRecordType|The type of operation indicated by the record. The possible values are: `exchangeAdmin`, `exchangeItem`, `exchangeItemGroup`, `sharePoint`, `syntheticProbe`, `sharePointFileOperation`, `oneDrive`, `azureActiveDirectory`, `azureActiveDirectoryAccountLogon`, `dataCenterSecurityCmdlet`, `complianceDLPSharePoint`, `sway`, `complianceDLPExchange`, `sharePointSharingOperation`, `azureActiveDirectoryStsLogon`, `skypeForBusinessPSTNUsage`, `skypeForBusinessUsersBlocked`, `securityComplianceCenterEOPCmdlet`, `exchangeAggregatedOperation`, `powerBIAudit`, `crm`, `yammer`, `skypeForBusinessCmdlets`, `discovery`, `microsoftTeams`, `threatIntelligence`, `mailSubmission`, `microsoftFlow`, `aeD`, `microsoftStream`, `complianceDLPSharePointClassification`, `threatFinder`, `project`, `sharePointListOperation`, `sharePointCommentOperation`, `dataGovernance`, `kaizala`, `securityComplianceAlerts`, `threatIntelligenceUrl`, `securityComplianceInsights`, `mipLabel`, `workplaceAnalytics`, `powerAppsApp`, `powerAppsPlan`, `threatIntelligenceAtpContent`, `labelContentExplorer`, `teamsHealthcare`, `exchangeItemAggregated`, `hygieneEvent`, `dataInsightsRestApiAudit`, `informationBarrierPolicyApplication`, `sharePointListItemOperation`, `sharePointContentTypeOperation`, `sharePointFieldOperation`, `microsoftTeamsAdmin`, `hrSignal`, `microsoftTeamsDevice`, `microsoftTeamsAnalytics`, `informationWorkerProtection`, `campaign`, `dlpEndpoint`, `airInvestigation`, `quarantine`, `microsoftForms`, `applicationAudit`, `complianceSupervisionExchange`, `customerKeyServiceEncryption`, `officeNative`, `mipAutoLabelSharePointItem`, `mipAutoLabelSharePointPolicyLocation`, `microsoftTeamsShifts`, `secureScore`, `mipAutoLabelExchangeItem`, `cortanaBriefing`, `search`, `wdatpAlerts`, `powerPlatformAdminDlp`, `powerPlatformAdminEnvironment`, `mdatpAudit`, `sensitivityLabelPolicyMatch`, `sensitivityLabelAction`, `sensitivityLabeledFileAction`, `attackSim`, `airManualInvestigation`, `securityComplianceRBAC`, `userTraining`, `airAdminActionInvestigation`, `mstic`, `physicalBadgingSignal`, `teamsEasyApprovals`, `aipDiscover`, `aipSensitivityLabelAction`, `aipProtectionAction`, `aipFileDeleted`, `aipHeartBeat`, `mcasAlerts`, `onPremisesFileShareScannerDlp`, `onPremisesSharePointScannerDlp`, `exchangeSearch`, `sharePointSearch`, `privacyDataMinimization`, `labelAnalyticsAggregate`, `myAnalyticsSettings`, `securityComplianceUserChange`, `complianceDLPExchangeClassification`, `complianceDLPEndpoint`, `mipExactDataMatch`, `msdeResponseActions`, `msdeGeneralSettings`, `msdeIndicatorsSettings`, `ms365DCustomDetection`, `msdeRolesSettings`, `mapgAlerts`, `mapgPolicy`, `mapgRemediation`, `privacyRemediationAction`, `privacyDigestEmail`, `mipAutoLabelSimulationProgress`, `mipAutoLabelSimulationCompletion`, `mipAutoLabelProgressFeedback`, `dlpSensitiveInformationType`, `mipAutoLabelSimulationStatistics`, `largeContentMetadata`, `microsoft365Group`, `cdpMlInferencingResult`, `filteringMailMetadata`, `cdpClassificationMailItem`, `cdpClassificationDocument`, `officeScriptsRunAction`, `filteringPostMailDeliveryAction`, `cdpUnifiedFeedback`, `tenantAllowBlockList`, `consumptionResource`, `healthcareSignal`, `dlpImportResult`, `cdpCompliancePolicyExecution`, `multiStageDisposition`, `privacyDataMatch`, `filteringDocMetadata`, `filteringEmailFeatures`, `powerBIDlp`, `filteringUrlInfo`, `filteringAttachmentInfo`, `coreReportingSettings`, `complianceConnector`, `powerPlatformLockboxResourceAccessRequest`, `powerPlatformLockboxResourceCommand`, `cdpPredictiveCodingLabel`, `cdpCompliancePolicyUserFeedback`, `webpageActivityEndpoint`, `omePortal`, `cmImprovementActionChange`, `filteringUrlClick`, `mipLabelAnalyticsAuditRecord`, `filteringEntityEvent`, `filteringRuleHits`, `filteringMailSubmission`, `labelExplorer`, `microsoftManagedServicePlatform`, `powerPlatformServiceActivity`, `scorePlatformGenericAuditRecord`, `filteringTimeTravelDocMetadata`, `alert`, `alertStatus`, `alertIncident`, `incidentStatus`, `case`, `caseInvestigation`, `recordsManagement`, `privacyRemediation`, `dataShareOperation`, `cdpDlpSensitive`, `ehrConnector`, `filteringMailGradingResult`, `publicFolder`, `privacyTenantAuditHistoryRecord`, `aipScannerDiscoverEvent`, `eduDataLakeDownloadOperation`, `m365ComplianceConnector`, `microsoftGraphDataConnectOperation`, `microsoftPurview`, `filteringEmailContentFeatures`, `powerPagesSite`, `powerAppsResource`, `plannerPlan`, `plannerCopyPlan`, `plannerTask`, `plannerRoster`, `plannerPlanList`, `plannerTaskList`, `plannerTenantSettings`, `projectForTheWebProject`, `projectForTheWebTask`, `projectForTheWebRoadmap`, `projectForTheWebRoadmapItem`, `projectForTheWebProjectSettings`, `projectForTheWebRoadmapSettings`, `quarantineMetadata`, `microsoftTodoAudit`, `timeTravelFilteringDocMetadata`, `teamsQuarantineMetadata`, `sharePointAppPermissionOperation`, `microsoftTeamsSensitivityLabelAction`, `filteringTeamsMetadata`, `filteringTeamsUrlInfo`, `filteringTeamsPostDeliveryAction`, `mdcAssessments`, `mdcRegulatoryComplianceStandards`, `mdcRegulatoryComplianceControls`, `mdcRegulatoryComplianceAssessments`, `mdcSecurityConnectors`, `mdaDataSecuritySignal`, `vivaGoals`, `filteringRuntimeInfo`, `attackSimAdmin`, `microsoftGraphDataConnectConsent`, `filteringAtpDetonationInfo`, `privacyPortal`, `managedTenants`, `unifiedSimulationMatchedItem`, `unifiedSimulationSummary`, `updateQuarantineMetadata`, `ms365DSuppressionRule`, `purviewDataMapOperation`, `filteringUrlPostClickAction`, `irmUserDefinedDetectionSignal`, `teamsUpdates`, `plannerRosterSensitivityLabel`, `ms365DIncident`, `filteringDelistingMetadata`, `complianceDLPSharePointClassificationExtended`, `microsoftDefenderForIdentityAudit`, `supervisoryReviewDayXInsight`, `defenderExpertsforXDRAdmin`, `cdpEdgeBlockedMessage`, `hostedRpa`, `cdpContentExplorerAggregateRecord`, `cdpHygieneAttachmentInfo`, `cdpHygieneSummary`, `cdpPostMailDeliveryAction`, `cdpEmailFeatures`, `cdpHygieneUrlInfo`, `cdpUrlClick`, `cdpPackageManagerHygieneEvent`, `filteringDocScan`, `timeTravelFilteringDocScan`, `mapgOnboard`, `unknownFutureValue`.| +|serviceFilter|String|The Office 365 service where the activity occurred.| +|status|microsoft.graph.security.auditLogQueryStatus|Describes the current status of the query. The possible values are: `notStarted`, `running`, `succeeded`, `failed`, `cancelled`, `unknownFutureValue`.| +|userPrincipalNameFilters|String collection|The UPN (user principal name) of the user who performed the action (specified in the operation property) that resulted in the record being logged; for example, _my_name@my_domain_name_.| + +## Relationships + +|Relationship|Type|Description| +|:---|:---|:---| +|records|[microsoft.graph.security.auditLogRecord](../resources/security-auditlogrecord.md) collection|An individual audit log record.| + +## JSON representation + +The following JSON representation shows the resource type. + +``` json +{ + "@odata.type": "#microsoft.graph.security.auditLogQuery", + "id": "String (identifier)", + "displayName": "String", + "filterStartDateTime": "String (timestamp)", + "filterEndDateTime": "String (timestamp)", + "recordTypeFilter": "String", + "keywordFilter": "String", + "serviceFilter": "String", + "operationFilters": [ + "String" + ], + "userPrincipalNameFilters": [ + "String" + ], + "ipAddressFilters": [ + "String" + ], + "objectIdFilters": [ + "String" + ], + "administrativeUnitIdFilters": [ + "String" + ], + "status": "String" +} +``` \ No newline at end of file diff --git a/api-reference/beta/resources/security-auditlogrecord.md b/api-reference/beta/resources/security-auditlogrecord.md new file mode 100644 index 00000000000..4847bd391f6 --- /dev/null +++ b/api-reference/beta/resources/security-auditlogrecord.md @@ -0,0 +1,80 @@ +--- +title: "auditLogRecord resource type" +description: "Represents an audit log entry that contains standard audit attributes and auditData specific to the Microsoft 365 service." +author: "arishojaswi" +ms.localizationpriority: medium +ms.prod: "security" +doc_type: resourcePageType +--- + +# auditLogRecord resource type + +Namespace: microsoft.graph.security + +[!INCLUDE [beta-disclaimer](../../includes/beta-disclaimer.md)] + +Represents an audit log entry that contains standard audit attributes and auditData specific to the Microsoft 365 service. + +Inherits from [microsoft.graph.entity](../resources/entity.md). + +## Methods + +| Method | Return type | Description | +| :----------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------ | +| [List auditLogRecords](../api/security-auditlogquery-list-records.md) | [auditLogRecord](../resources/security-auditlogrecord.md) collection | Get a list of the [auditLogRecord](../resources/security-auditlogrecord.md) objects and their properties. | + +## Properties + +| Property | Type | Description | +| :------------------ | :----------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| administrativeUnits | String collection| The administrative units tagged to an audit log record.| +| auditData | [microsoft.graph.security.auditData](../resources/security-auditdata.md) | A JSON object that contains the actual audit log data.| +| auditLogRecordType | microsoft.graph.security.auditLogRecordType | The type of operation indicated by the record. The possible values are: `exchangeAdmin`, `exchangeItem`, `exchangeItemGroup`, `sharePoint`, `syntheticProbe`, `sharePointFileOperation`, `oneDrive`, `azureActiveDirectory`, `azureActiveDirectoryAccountLogon`, `dataCenterSecurityCmdlet`, `complianceDLPSharePoint`, `sway`, `complianceDLPExchange`, `sharePointSharingOperation`, `azureActiveDirectoryStsLogon`, `skypeForBusinessPSTNUsage`, `skypeForBusinessUsersBlocked`, `securityComplianceCenterEOPCmdlet`, `exchangeAggregatedOperation`, `powerBIAudit`, `crm`, `yammer`, `skypeForBusinessCmdlets`, `discovery`, `microsoftTeams`, `threatIntelligence`, `mailSubmission`, `microsoftFlow`, `aeD`, `microsoftStream`, `complianceDLPSharePointClassification`, `threatFinder`, `project`, `sharePointListOperation`, `sharePointCommentOperation`, `dataGovernance`, `kaizala`, `securityComplianceAlerts`, `threatIntelligenceUrl`, `securityComplianceInsights`, `mipLabel`, `workplaceAnalytics`, `powerAppsApp`, `powerAppsPlan`, `threatIntelligenceAtpContent`, `labelContentExplorer`, `teamsHealthcare`, `exchangeItemAggregated`, `hygieneEvent`, `dataInsightsRestApiAudit`, `informationBarrierPolicyApplication`, `sharePointListItemOperation`, `sharePointContentTypeOperation`, `sharePointFieldOperation`, `microsoftTeamsAdmin`, `hrSignal`, `microsoftTeamsDevice`, `microsoftTeamsAnalytics`, `informationWorkerProtection`, `campaign`, `dlpEndpoint`, `airInvestigation`, `quarantine`, `microsoftForms`, `applicationAudit`, `complianceSupervisionExchange`, `customerKeyServiceEncryption`, `officeNative`, `mipAutoLabelSharePointItem`, `mipAutoLabelSharePointPolicyLocation`, `microsoftTeamsShifts`, `secureScore`, `mipAutoLabelExchangeItem`, `cortanaBriefing`, `search`, `wdatpAlerts`, `powerPlatformAdminDlp`, `powerPlatformAdminEnvironment`, `mdatpAudit`, `sensitivityLabelPolicyMatch`, `sensitivityLabelAction`, `sensitivityLabeledFileAction`, `attackSim`, `airManualInvestigation`, `securityComplianceRBAC`, `userTraining`, `airAdminActionInvestigation`, `mstic`, `physicalBadgingSignal`, `teamsEasyApprovals`, `aipDiscover`, `aipSensitivityLabelAction`, `aipProtectionAction`, `aipFileDeleted`, `aipHeartBeat`, `mcasAlerts`, `onPremisesFileShareScannerDlp`, `onPremisesSharePointScannerDlp`, `exchangeSearch`, `sharePointSearch`, `privacyDataMinimization`, `labelAnalyticsAggregate`, `myAnalyticsSettings`, `securityComplianceUserChange`, `complianceDLPExchangeClassification`, `complianceDLPEndpoint`, `mipExactDataMatch`, `msdeResponseActions`, `msdeGeneralSettings`, `msdeIndicatorsSettings`, `ms365DCustomDetection`, `msdeRolesSettings`, `mapgAlerts`, `mapgPolicy`, `mapgRemediation`, `privacyRemediationAction`, `privacyDigestEmail`, `mipAutoLabelSimulationProgress`, `mipAutoLabelSimulationCompletion`, `mipAutoLabelProgressFeedback`, `dlpSensitiveInformationType`, `mipAutoLabelSimulationStatistics`, `largeContentMetadata`, `microsoft365Group`, `cdpMlInferencingResult`, `filteringMailMetadata`, `cdpClassificationMailItem`, `cdpClassificationDocument`, `officeScriptsRunAction`, `filteringPostMailDeliveryAction`, `cdpUnifiedFeedback`, `tenantAllowBlockList`, `consumptionResource`, `healthcareSignal`, `dlpImportResult`, `cdpCompliancePolicyExecution`, `multiStageDisposition`, `privacyDataMatch`, `filteringDocMetadata`, `filteringEmailFeatures`, `powerBIDlp`, `filteringUrlInfo`, `filteringAttachmentInfo`, `coreReportingSettings`, `complianceConnector`, `powerPlatformLockboxResourceAccessRequest`, `powerPlatformLockboxResourceCommand`, `cdpPredictiveCodingLabel`, `cdpCompliancePolicyUserFeedback`, `webpageActivityEndpoint`, `omePortal`, `cmImprovementActionChange`, `filteringUrlClick`, `mipLabelAnalyticsAuditRecord`, `filteringEntityEvent`, `filteringRuleHits`, `filteringMailSubmission`, `labelExplorer`, `microsoftManagedServicePlatform`, `powerPlatformServiceActivity`, `scorePlatformGenericAuditRecord`, `filteringTimeTravelDocMetadata`, `alert`, `alertStatus`, `alertIncident`, `incidentStatus`, `case`, `caseInvestigation`, `recordsManagement`, `privacyRemediation`, `dataShareOperation`, `cdpDlpSensitive`, `ehrConnector`, `filteringMailGradingResult`, `publicFolder`, `privacyTenantAuditHistoryRecord`, `aipScannerDiscoverEvent`, `eduDataLakeDownloadOperation`, `m365ComplianceConnector`, `microsoftGraphDataConnectOperation`, `microsoftPurview`, `filteringEmailContentFeatures`, `powerPagesSite`, `powerAppsResource`, `plannerPlan`, `plannerCopyPlan`, `plannerTask`, `plannerRoster`, `plannerPlanList`, `plannerTaskList`, `plannerTenantSettings`, `projectForTheWebProject`, `projectForTheWebTask`, `projectForTheWebRoadmap`, `projectForTheWebRoadmapItem`, `projectForTheWebProjectSettings`, `projectForTheWebRoadmapSettings`, `quarantineMetadata`, `microsoftTodoAudit`, `timeTravelFilteringDocMetadata`, `teamsQuarantineMetadata`, `sharePointAppPermissionOperation`, `microsoftTeamsSensitivityLabelAction`, `filteringTeamsMetadata`, `filteringTeamsUrlInfo`, `filteringTeamsPostDeliveryAction`, `mdcAssessments`, `mdcRegulatoryComplianceStandards`, `mdcRegulatoryComplianceControls`, `mdcRegulatoryComplianceAssessments`, `mdcSecurityConnectors`, `mdaDataSecuritySignal`, `vivaGoals`, `filteringRuntimeInfo`, `attackSimAdmin`, `microsoftGraphDataConnectConsent`, `filteringAtpDetonationInfo`, `privacyPortal`, `managedTenants`, `unifiedSimulationMatchedItem`, `unifiedSimulationSummary`, `updateQuarantineMetadata`, `ms365DSuppressionRule`, `purviewDataMapOperation`, `filteringUrlPostClickAction`, `irmUserDefinedDetectionSignal`, `teamsUpdates`, `plannerRosterSensitivityLabel`, `ms365DIncident`, `filteringDelistingMetadata`, `complianceDLPSharePointClassificationExtended`, `microsoftDefenderForIdentityAudit`, `supervisoryReviewDayXInsight`, `defenderExpertsforXDRAdmin`, `cdpEdgeBlockedMessage`, `hostedRpa`, `cdpContentExplorerAggregateRecord`, `cdpHygieneAttachmentInfo`, `cdpHygieneSummary`, `cdpPostMailDeliveryAction`, `cdpEmailFeatures`, `cdpHygieneUrlInfo`, `cdpUrlClick`, `cdpPackageManagerHygieneEvent`, `filteringDocScan`, `timeTravelFilteringDocScan`, `mapgOnboard`, `unknownFutureValue`. | +| clientIp | String | The IP address of the device used when the activity was logged. The IP address is displayed in either an IPv4 or IPv6 address format. | +| createdDateTime | DateTimeOffset| The date and time in UTC when the user performed the activity. | +| id | String | The ID of the report entry. The ID uniquely identifies the report entry. Inherited from [microsoft.graph.entity](../resources/entity.md). | +| objectId | String | For Exchange admin audit logging, the name of the object modified by the cmdlet. For SharePoint activity, the full URL path name of the file or folder accessed by a user. For Microsoft Entra activity, the name of the user account that was modified. | +| operation | String | The name of the user or admin activity. | +| organizationId | String | The GUID for your organization. | +| service | String | The Microsoft 365 service where the activity occurred. | +| userId | String | The user who performed the action (specified in the Operation property) that resulted in the record being logged. Audit records for activity performed by system accounts (such as SHAREPOINT\system or NT AUTHORITY\SYSTEM) are also included in the audit log. Another common value for the UserId property is app@sharepoint. It indicates that the "user" who performed the activity was an application with the necessary permissions in SharePoint to perform organization-wide actions (such as searching a SharePoint site or OneDrive account) on behalf of a user, admin, or service. | +| userPrincipalName | String | UPN of the user who performed the action. | +| userType | microsoft.graph.security.auditLogUserType | The type of user that performed the operation. The possible values are: `regular`, `reserved`, `admin`, `dcAdmin`, `system`, `application`, `servicePrincipal`, `customPolicy`, `systemPolicy`, `partnerTechnician`, `guest`, `unknownFutureValue`. | + +## Relationships + +None. + +## JSON representation + +The following JSON representation shows the resource type. + + + +```json +{ + "@odata.type": "#microsoft.graph.security.auditLogRecord", + "id": "String (identifier)", + "createdDateTime": "String (timestamp)", + "auditLogRecordType": "String", + "operation": "String", + "organizationId": "String", + "userType": "String", + "userId": "String", + "service": "String", + "objectId": "String", + "userPrincipalName": "String", + "clientIp": "String", + "administrativeUnits": ["String"], + "auditData": { + "@odata.type": "microsoft.graph.security.auditData" + } +} +``` diff --git a/api-reference/beta/resources/security-defaultauditdata.md b/api-reference/beta/resources/security-defaultauditdata.md new file mode 100644 index 00000000000..a3b1b22bf1a --- /dev/null +++ b/api-reference/beta/resources/security-defaultauditdata.md @@ -0,0 +1,36 @@ +--- +title: "defaultAuditData resource type" +description: "Represents a JSON object containing the actual audit log data." +author: "arishojaswi" +ms.localizationpriority: medium +ms.prod: "security" +doc_type: resourcePageType +--- + +# defaultAuditData resource type + +Namespace: microsoft.graph.security + +[!INCLUDE [beta-disclaimer](../../includes/beta-disclaimer.md)] + +Represents a JSON object containing the actual audit log data. + +Inherits from [auditData](../resources/security-auditdata.md). + +## Properties +None. +## Relationships +None. + +## JSON representation +The following JSON representation shows the resource type. + +``` json +{ + "@odata.type": "#microsoft.graph.security.defaultAuditData" +} +``` diff --git a/api-reference/beta/toc.yml b/api-reference/beta/toc.yml index 98ba8110fcd..be0de02e42b 100644 --- a/api-reference/beta/toc.yml +++ b/api-reference/beta/toc.yml @@ -16598,6 +16598,24 @@ items: href: resources/simulationautomationrun.md - name: List href: api/simulationautomation-list-runs.md + - name: Audit log query (preview) + items: + - name: Audit log query + href: resources/security-auditlogquery.md + items: + - name: List + href: api/security-auditcoreroot-list-auditlogqueries.md + - name: Create + href: api/security-auditcoreroot-post-auditlogqueries.md + - name: Get + href: api/security-auditlogquery-get.md + - name: List audit log records + href: api/security-auditlogquery-list-records.md + - name: Audit log record + href: resources/security-auditlogrecord.md + items: + - name: List + href: api/security-auditlogquery-list-records.md - name: eDiscovery (preview) items: - name: Case diff --git a/api-reference/v1.0/resources/enums.md b/api-reference/v1.0/resources/enums.md index 8dd0ca68f63..278d97cc478 100644 --- a/api-reference/v1.0/resources/enums.md +++ b/api-reference/v1.0/resources/enums.md @@ -1789,7 +1789,7 @@ Possible values for user account types (group membership), per Windows definitio | Member | Value | Description | | :------ | :---- | :-------------------------------- | | block | 1 | The threat should be blocked. | -| unblock | 2 | The threat should not be blocked. | +| unblock | 2 | The threat shouldn't be blocked. | ### threatCategory values @@ -1877,7 +1877,7 @@ Possible values for user account types (group membership), per Windows definitio | :-------------------------------- | :-------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | None | 0 | User is not allowed to override the message. User is not allowed to report a message as false positive if policyTip is not provided. In all other scenarios, user can report a message as false positive. | | AllowFalsePositiveOverride | 1 | User is not allowed to explicitly override the block unless this is combined with `AllowOverrideWithoutJustification` or `AllowOverrideWithJustification` flags. Reporting a false positive on the violation automatically overrides the block and sends the message. | -| AllowOverrideWithoutJustification | 2 | User is allowed to override the block and send the message. Justification text is not required. Exclusive to `AllowOverrideWithJustification`. | +| AllowOverrideWithoutJustification | 2 | User is allowed to override the block and send the message. Justification text isn't required. Exclusive to `AllowOverrideWithJustification`. | | AllowOverrideWithJustification | 4 | User is allowed to override the block and send the message. Justification text is required. Exclusive to `AllowOverrideWithoutJustification`. | ### wellknownListName values diff --git a/api-reference/v1.0/resources/federatedidentitycredentials-overview.md b/api-reference/v1.0/resources/federatedidentitycredentials-overview.md index 6ab2fd6f99f..1491d9bb3c7 100644 --- a/api-reference/v1.0/resources/federatedidentitycredentials-overview.md +++ b/api-reference/v1.0/resources/federatedidentitycredentials-overview.md @@ -38,7 +38,7 @@ The combination of **issuer** and **subject** must be unique on the app. ## Design considerations -Federated identity credentials are supported on applications only. A maximum of 20 federated identity credentials can be added per application object. +A maximum of 20 federated identity credentials can be added per application object or user-assigned managed identity. ## See also diff --git a/changelog/Microsoft.Security.AuditLogQuery.json b/changelog/Microsoft.Security.AuditLogQuery.json new file mode 100644 index 00000000000..2b3258fe3f8 --- /dev/null +++ b/changelog/Microsoft.Security.AuditLogQuery.json @@ -0,0 +1,70 @@ +{ + "changelog": [ + { + "ChangeList": [ + { + "Id": "95da9b0a-04da-4dc5-be44-eed390298791", + "ApiChange": "Resource", + "ChangedApiName": "auditLogQuery", + "ChangeType": "Addition", + "Description": "Added the [auditLogQuery](https://learn.microsoft.com/en-us/graph/api/resources/security-auditlogquery?view=graph-rest-beta) resource and supported methods.", + "Target": "auditLogQuery" + }, + { + "Id": "95da9b0a-04da-4dc5-be44-eed390298791", + "ApiChange": "Resource", + "ChangedApiName": "auditLogRecord", + "ChangeType": "Addition", + "Description": "Added the [auditLogRecord](https://learn.microsoft.com/en-us/graph/api/resources/security-auditlogrecord?view=graph-rest-beta) resource and supported methods.", + "Target": "auditLogRecord" + }, + { + "Id": "95da9b0a-04da-4dc5-be44-eed390298791", + "ApiChange": "Resource", + "ChangedApiName": "auditData", + "ChangeType": "Addition", + "Description": "Added the [auditData](https://learn.microsoft.com/en-us/graph/api/resources/security-auditdata?view=graph-rest-beta) resource.", + "Target": "auditData" + }, + { + "Id": "95da9b0a-04da-4dc5-be44-eed390298791", + "ApiChange": "Resource", + "ChangedApiName": "defaultAuditData", + "ChangeType": "Addition", + "Description": "Added the [defaultAuditData](https://learn.microsoft.com/en-us/graph/api/resources/security-defaultauditdata?view=graph-rest-beta) resource.", + "Target": "defaultAuditData" + }, + { + "Id": "95da9b0a-04da-4dc5-be44-eed390298791", + "ApiChange": "Enumeration", + "ChangedApiName": "auditLogQueryStatus", + "ChangeType": "Addition", + "Description": "Added the **auditLogQueryStatus** enumeration.", + "Target": "auditLogQueryStatus" + }, + { + "Id": "95da9b0a-04da-4dc5-be44-eed390298791", + "ApiChange": "Enumeration", + "ChangedApiName": "auditLogRecordType", + "ChangeType": "Addition", + "Description": "Added the **auditLogRecordType** enumeration.", + "Target": "auditLogRecordType" + }, + { + "Id": "95da9b0a-04da-4dc5-be44-eed390298791", + "ApiChange": "Enumeration", + "ChangedApiName": "auditLogUserType", + "ChangeType": "Addition", + "Description": "Added the **auditLogUserType** enumeration.", + "Target": "auditLogUserType" + } + ], + "Id": "b4937176-8221-4bc7-83a4-6e84c4ee02d1", + "Cloud": "Prod", + "Version": "beta", + "CreatedDateTime": "2024-01-25T15:48:54.3649155Z", + "WorkloadArea": "Security", + "SubArea": "" + } + ] + } diff --git a/concepts/connecting-external-content-connectors-overview.md b/concepts/connecting-external-content-connectors-overview.md index e6730da30db..0b384c51930 100644 --- a/concepts/connecting-external-content-connectors-overview.md +++ b/concepts/connecting-external-content-connectors-overview.md @@ -9,7 +9,7 @@ ms.prod: search # Microsoft Graph connectors overview -[Microsoft 365](https://www.microsoft.com/microsoft-365) is a complete, intelligent solution that empowers users and organizations with innovative productivity experiences and rich insights to increase efficiency and drive business growth. Microsoft Graph is the data fabric that powers these intelligent experiences, and the [Microsoft Search API](/graph/api/resources/indexing-api-overview) provides access to this data and intelligence. +[Microsoft 365](https://www.microsoft.com/microsoft-365) is a complete, intelligent solution that empowers users and organizations with innovative productivity experiences and rich insights to increase efficiency and drive business growth. Microsoft Graph is the data fabric that powers these intelligent experiences, and the [Microsoft Search API](/graph/api/resources/connectors-api-overview) provides access to this data and intelligence. Although most information workers spend much of their work time within productivity applications such as Microsoft 365, they also need a way to integrate that environment with the enterprise applications and other on-premises and SaaS cloud software and services that they use. Examples include enterprise resource planning (ERP) applications, customer resource management (CRM) applications, intranet applications, wikis, blogs, and social networking sites. diff --git a/concepts/connecting-external-content-manage-connections.md b/concepts/connecting-external-content-manage-connections.md index c01c8f29305..47706399155 100644 --- a/concepts/connecting-external-content-manage-connections.md +++ b/concepts/connecting-external-content-manage-connections.md @@ -134,5 +134,5 @@ To remove all items that were indexed via a connection, you can [delete a connec ## Next steps - [Register the connection schema](connecting-external-content-manage-schema.md) -- [Review the Microsoft Graph connectors API reference](/graph/api/resources/indexing-api-overview) +- [Review the Microsoft Graph connectors API reference](/graph/api/resources/connectors-api-overview) - [Download the sample search connector from GitHub](https://github.com/microsoftgraph/msgraph-search-connector-sample) diff --git a/concepts/connecting-external-content-manage-items.md b/concepts/connecting-external-content-manage-items.md index 994d7726e29..e95811d6b3f 100644 --- a/concepts/connecting-external-content-manage-items.md +++ b/concepts/connecting-external-content-manage-items.md @@ -151,6 +151,6 @@ Ultimately, the choice of data refresh strategy depends on your data type and co - [Use external groups to manage permissions](connecting-external-content-external-groups.md) - [Query using the Microsoft Search API](search-concept-overview.md#why-use-the-microsoft-search-api) -- [Review the Microsoft Graph connectors API reference](/graph/api/resources/indexing-api-overview) +- [Review the Microsoft Graph connectors API reference](/graph/api/resources/connectors-api-overview) - [Search custom types (externalItem)](search-concept-custom-types.md) - [Download the sample search connector from GitHub](https://github.com/microsoftgraph/msgraph-search-connector-sample) diff --git a/concepts/connecting-external-content-manage-schema.md b/concepts/connecting-external-content-manage-schema.md index c42e9168d2a..268ff0b586d 100644 --- a/concepts/connecting-external-content-manage-schema.md +++ b/concepts/connecting-external-content-manage-schema.md @@ -202,7 +202,7 @@ Adding a semantic label can affect experiences like Relevance and Viva Topics. ## Next steps - [Add items to the connection](connecting-external-content-manage-items.md) -- [Review the Microsoft Graph connectors API reference](/graph/api/resources/indexing-api-overview) +- [Review the Microsoft Graph connectors API reference](/graph/api/resources/connectors-api-overview) - [Search custom types (externalItem)](search-concept-custom-types.md) - [Build your first custom Microsoft Graph connector](/graph/connecting-external-content-build-quickstart) diff --git a/concepts/extensibility-open-users.md b/concepts/extensibility-open-users.md index d59d29e5810..9225c409b63 100644 --- a/concepts/extensibility-open-users.md +++ b/concepts/extensibility-open-users.md @@ -1,35 +1,44 @@ --- title: "Add custom data to users using open extensions" -description: "Follow the steps in this article to add an extension, query a user and return a roaming profile, change and then delete the user's roaming profile information." -author: "FaithOmbongi" -ms.author: ombongifaith +description: "Learn how to add an open extension to a user's profile, query it, change and delete the extension." +author: FaithOmbongi ms.reviewer: dkershaw ms.prod: "extensions" ms.localizationpriority: high ms.custom: graphiamtop20 -ms.date: 02/02/2023 +ms.topic: tutorial +ms.date: 01/25/2024 #Customer intent: As a developer, I want to learn how to store lightweight data to Microsoft Entra users through Microsoft Graph, and avoid using an external database system. --- # Add custom data to users using open extensions -This article demonstrates how to use *open extensions*. +In this tutorial, you lean how to use [open extensions](/graph/api/resources/opentypeextension). -Imagine you're building an application that is available on multiple client platforms, such as desktop and mobile. You want to let users configure their UI experience so it's consistent no matter which device they use to sign in to your app. +Imagine you're building an application that's available on multiple client platforms, such as desktop and mobile. You want to let users configure their UI experience so it's consistent no matter which device they use to sign in to your app. -For this scenario, this article will show you how to: +For this scenario, this article shows you how to: -1. Add an open extension representing some roaming profile information about the user. -2. Query the user and return the roaming profile. -3. Change the user's roaming profile information (the open extension value). -4. Delete the user's roaming profile information. +> [!div class="checklist"] +> +> - Represent some roaming profile information about the user using open extensions. +> - Query the user and return the roaming profile. +> - Change the user's roaming profile information stored in the open extension. +> - Delete the user's roaming profile information. > [!NOTE] > Apart from users, open extensions are also supported and can be managed for [other resource types](extensibility-overview.md#comparison-of-extension-types). -## 1. Add roaming profile information +## Prerequisites -The user signs in to the app and configures the look and feel of the app. These app settings should roam so that the user gets the same experience on whatever device they sign in to the app from. The app calls Microsoft Graph by running the following request to add the roaming profile information to a user resource. +To reproduce the steps in this article, you need the following privileges: + +- Sign in to an API client such as [Graph Explorer](https://aka.ms/ge) and the user you want to store the roaming profile for. +- Grant the app the *User.ReadWrite* delegated permission for the signed-in user. + +## Step 1. Add roaming profile information + +The user signs in to the app and configures the look and feel of the app. These app settings should roam so that the user gets the same experience on whatever device they sign in to the app from. The app calls Microsoft Graph by running the following request to add the roaming profile information to the signed-in user's resource object. ### Request @@ -97,22 +106,22 @@ HTTP/1.1 201 Created Content-Type: application/json { + "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('376bdbfc-e41f-4082-a8cf-b31731465eeb')/extensions/$entity", "@odata.type": "#microsoft.graph.openTypeExtension", "extensionName": "com.contoso.roamingSettings", - "id": "com.contoso.roamingSettings", "theme": "dark", "color": "purple", - "lang": "Japanese" + "lang": "Japanese", + "id": "com.contoso.roamingSettings" } ``` -## 2. Retrieve roaming profile information +## Step 2. Retrieve roaming profile information -When the user signs in to the app from another device, the app calls Microsoft Graph to retrieve the user's profile details and expand the **extensions** navigation property to get their roaming settings. +When the user signs in to the app from another device, the app calls Microsoft Graph to retrieve the user's profile details and expand the **extensions** navigation property to get their roaming settings, then uses this data to provide the same experience as on the other device. ### Request - # [HTTP](#tab/http) -``` -HTTP/1.1 204 No content -``` - -## 4. Delete a user's roaming profile - -The user decides that they don't want a roaming profile anymore, so they delete it and the app calls Microsoft Graph by running the following request. - -### Request +## Step 4. Delete a user's roaming profile +The user decides that they don't want a roaming profile anymore. To delete the extension property, the app calls Microsoft Graph by running the following request. The request returns a `204 No Content` response code. # [HTTP](#tab/http) -``` -HTTP/1.1 204 No content -``` - -## See also +## Related content - [Add custom data to resources using extensions](extensibility-overview.md) - [Add custom data to groups using schema extensions](extensibility-schema-groups.md) diff --git a/concepts/extensibility-overview.md b/concepts/extensibility-overview.md index 03e6312e631..a40e7592ac1 100644 --- a/concepts/extensibility-overview.md +++ b/concepts/extensibility-overview.md @@ -6,6 +6,7 @@ ms.author: ombongifaith ms.reviewer: dkershaw ms.localizationpriority: high ms.prod: "extensions" +ms.topic: overview ms.custom: graphiamtop20 ms.date: 11/29/2023 #Customer intent: As a developer, I want to learn how to store lightweight data to Microsoft Graph resources and avoid using an external database system, and use the data to customize authentication and other experiences. @@ -198,7 +199,7 @@ The 15 extension attributes are already predefined in Microsoft Graph and their [Directory extensions](/graph/api/resources/extensionProperty) provide developers with a strongly typed, discoverable and filterable extension experience for directory objects. -Directory extensions are first registered on an application through the [Create extensionProperty](/graph/api/application-post-extensionproperty) operation and must be explicitly targeted to specific and supported directory objects. After the application has been consented to by a user or an admin, the extension properties become immediately accessible in the tenant. All authorized applications in the tenant can read and write data on any extension properties defined on an instance of the target directory object. +Directory extensions are first registered on an application through the [Create extensionProperty](/graph/api/application-post-extensionproperty) operation and must be explicitly targeted to specific and supported directory objects. After a user or an admin has consented to the application in the tenant, the extension properties become immediately accessible in the tenant. All authorized applications in the tenant can read and write data on any extension properties defined on an instance of the target directory object. For the list of resource types that can be specified as target objects for a directory extension, see [Comparison of extension types](#comparison-of-extension-types). @@ -494,7 +495,7 @@ When a definition object is deleted before the corresponding extension property When the definition is deleted before data in the associated extension property is deleted, there's no way to know the existence of the extension property via Microsoft Graph - even though the undiscoverable property counts against the 100-limit. -Deleting an owner app in the home tenant makes the associated directory extensions and their data undiscoverable. When you restore an owner app restores the directory extension definitions *but doesn't* make the directory extension properties or their data immediately discoverable; because restoring an app doesn't automatically restore the associated service principal in the tenant. To make the directory extension properties and their data discoverable, either create a new service principal or restore the deleted service principal. NO changes are made to other tenants where the app has been consented to. +Deleting an owner app in the home tenant makes the associated directory extensions and their data undiscoverable. When you restore an owner app, it restores the directory extension definitions *but doesn't* make the directory extension properties or their data immediately discoverable; because restoring an app doesn't automatically restore the associated service principal in the tenant. To make the directory extension properties and their data discoverable, either create a new service principal or restore the deleted service principal. NO changes are made to other tenants where the app has been consented to. diff --git a/concepts/extensibility-schema-groups.md b/concepts/extensibility-schema-groups.md index cf1aa0c74e3..8a170677dea 100644 --- a/concepts/extensibility-schema-groups.md +++ b/concepts/extensibility-schema-groups.md @@ -1,41 +1,47 @@ --- title: "Add custom data to groups using schema extensions" -description: "Follow the steps in this article to register a schema extension definition, create a group with extended data, and update custom data in an existing group." -author: "FaithOmbongi" -ms.author: ombongifaith +description: "Learn how to register a schema extension definition, extend a group with the schema extension, and update custom data in the schema extension for the group." +author: FaithOmbongi ms.reviewer: dkershaw ms.prod: "extensions" ms.localizationpriority: high ms.custom: graphiamtop20 -ms.date: 02/02/2023 +ms.topic: tutorial +ms.date: 01/25/2024 #Customer intent: As a developer, I want to learn how to store lightweight data to Microsoft Entra groups through Microsoft Graph, and avoid using an external database system. --- # Add custom data to groups using schema extensions -This article demonstrates how to use *schema extensions*. +In this tutorial, you learn how to use [schema extensions](/graph/api/resources/schemaextension). -Imagine you're a developer in a Learning Management Software company called "Graph Learn" that builds training courses and materials for businesses. You use the collaborative experience of Microsoft 365 groups to deliver course content and record exercises among participants for both online courses and instructor-led courses. You want to make the Microsoft 365 groups used for training courses easily identifiable as training courses, which will allow other developers to discover your groups and build rich experiences on top of your learning courses. +Imagine you're a developer in a Learning Management Software company called **Bellows College** that builds training courses and materials for businesses. You use the collaborative experience of Microsoft 365 groups to deliver course content and record exercises among participants for both online courses and instructor-led courses. You want to make the Microsoft 365 groups used for training courses easily identifiable as training courses, which allows other developers to discover your groups and build rich experiences on top of your learning courses. -For this scenario, this article will show you how to: +For this scenario, this article shows you how to: -1. View available schema extension definitions that you could use. -2. Register a schema extension definition that targets groups for training courses. -3. Create a new group with custom data based on the schema extension definition that you registered. -4. Add, update, or remove custom data in an existing group based on a schema extension definition. -5. Read a group and the extension data. +> [!div class="checklist"] +> +> - Discover available schema extension definitions that you could use. +> - Register a schema extension definition that targets groups for training courses. +> - Create a new group with custom data based on the schema extension definition that you registered. +> - Add, update, or remove custom data in an existing group based on a schema extension definition. +> - Read a group and the extension data. +> - Delete the schema extension definition and the extension data. > [!NOTE] > Apart from groups, schema extensions are also supported and can be managed for [other resource types](extensibility-overview.md#comparison-of-extension-types). -## 1. View available schema extensions +## Prerequisites -First, as a developer, you might want to find any other schema extension definitions that our app could reuse. +To reproduce the steps in this article, you need the following privileges: -In the following example, you query the **schemaExtension** resource for a specific schema extension by its **id**. +- Sign in to an API client such as [Graph Explorer](https://aka.ms/ge). +- Grant the app the *Group.ReadWrite.All* and *Application.ReadWrite.All* delegated permissions for the signed-in user. +- Be the owner of an application that you assign ownership of the schema extension definition in this tutorial. In this tutorial, the application is named *extensions-application* and has **appId** `d1e6f196-fca3-48ad-8cd3-1a98e3bd46d2`. -Notice that the extension returned in the response has **Available** as the **status** value, which indicates that any app that has permission to the resources in the **targetTypes** property can use and update the extension -with additive changes. In general, this operation returns any schema extensions that satisfy the specified filter regardless of **status**, so do check the extension status before using it. +## Step 1. View available schema extensions + +First, as a developer, you might want the app to reuse any existing schema extension definitions if they're fit for purpose. In the following example, you query schema extensions that are named (by the **id**) `bellowscollege_courses`. Assume that the response shows there are no schema extensions that are named `bellowscollege_courses` in your tenant. ### Request @@ -45,7 +51,7 @@ with additive changes. In general, this operation returns any schema extensions "name": "schemaextensions-groups-get" }--> ```msgraph-interactive -GET https://graph.microsoft.com/v1.0/schemaExtensions?$filter=id eq 'graphlearn_test' +GET https://graph.microsoft.com/v1.0/schemaExtensions?$filter=id eq 'bellowscollege_courses' ``` # [C#](#tab/csharp) @@ -94,36 +100,27 @@ HTTP/1.1 200 OK Content-Type: application/json { - "value": [ - { - "id":"graphlearn_test", - "description": "Yet another test schema", - "targetTypes": [ - "User", "Group" - ], - "status": "Available", - "owner": "24d3b144-21ae-4080-943f-7067b395b913", - "properties": [ - { - "name": "testName", - "type": "String" - } - ] - } - ] + "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#schemaExtensions", + "@microsoft.graph.tips": "Use $select to choose only the properties your app needs, as this can lead to performance improvements. For example: GET schemaExtensions?$select=description,owner", + "value": [] } ``` -## 2. Register a schema extension definition that describes a training course +You can also query by the **id** as a path parameter as follows: `GET https://graph.microsoft.com/v1.0/schemaExtensions/bellowscollege_courses`. If there are no schema extensions that match the ID, the response is `404 Not Found`. -If you can't find a schema extension that is appropriate for your needs, you can create and register a new extension definition for training courses on the **group** resource. +## Step 2. Register a schema extension definition -When creating a schema extension definition, you should provide a string for the **id** property. Assuming you've verified your vanity domain `graphlearn.com` with your tenant, you'll concatenate the verified domain name (`graphlearn`) with a name -for the schema extension (`courses`), and assign **id** with the resultant string, `graphlearn_courses`. This **id** becomes the name of the schema extension property on a group. See an [example of the other way to assign **id** in the request](/graph/api/schemaextension-post-schemaextensions#request-2) that requires you to provide only a schema name. +You want to create and register a new extension definition for training courses on the **group** resource. Specify the following properties: -Then, specify a description, target resources this extension applies to, and the custom properties that make up the schema. In this example, specify the `courseId`, `courseName` and `courseType` custom properties and their types. +- **id**: Provide a string for this property following one of two ways: + - Option 1: Concatenate a *verified* vanity domain name for your tenant with a name for the schema extension. For example, if the domain is `bellowscollege.com`, and the name of the schema extension is `courses`, then you can use the **id** `bellowscollege_courses`. + - Option 2: An alternative way is to provide only a schema name, such as `courses`, and let Microsoft Graph automatically generate the **id** for you by prefixing the provided name with a random alphanumeric string. -Notice that when you initially create a schema extension, its status is **InDevelopment**. While you're developing the extension, you can keep it in this status, during which only the app that created it can update it with additive changes or delete it. When you're ready to share the extension for use by other apps, set **status** to **Available**. + This **id** becomes the name of the schema extension property on a group. +- **description** +- **targetTypes**: Specify the resource types that the schema extension can be applied to. In this example, the resource type is `Group`. You can add more resource types by updating the schema extension definition later. +- **properties**: Specify the custom properties that make up the schema. In this example, specify the `courseId`, `courseName` and `courseType` custom properties and their types. Only additive changes are permitted after you create the schema extension definition. +- **owner**: Specify the application that owns the schema extension definition. If you're running this example from an app that you're not assigned as owner, specify the **appId** of the application that you're assigned in the **owner** property. ### Request @@ -137,11 +134,12 @@ POST https://graph.microsoft.com/v1.0/schemaExtensions Content-type: application/json { - "id":"graphlearn_courses", - "description": "Graph Learn training courses extensions", + "id": "bellowscollege_courses", + "description": "Bellows College training courses extensions", "targetTypes": [ "Group" ], + "owner": "d1e6f196-fca3-48ad-8cd3-1a98e3bd46d2", "properties": [ { "name": "courseId", @@ -195,6 +193,10 @@ Content-type: application/json ### Response +The following example shows the response. + +In the response, the default initial status of the schema extension is `InDevelopment`. While you're developing the extension, you can keep it in this status, during which only the app that created it can update it with additive changes or delete it. When you're ready to share the extension for use by other apps, set **status** to **Available**. + -```http -HTTP/1.1 204 No Content -``` +The following request updates the **courseType** property in the `bellowscollege_courses` extension for the group to `Hybrid`. Though you want to update only the **courseType** property, you must include the other properties and their existing values in the request body as well. Otherwise, Microsoft Graph sets them to `null` and removes their data. -If you want to update the values of the extension data, put the entire extension complex type in the body of a `PATCH` request (similar to adding custom data to an existing resource). +The following request returns a `204 No Content` response. -To remove custom data added to a resource instance, but keep the schema extension property on the resource instance, set the corresponding extension property to `null`. - -To remove a schema extension from a resource instance, set the extension complex type in that instance to `null`. + +```http +PATCH https://graph.microsoft.com/v1.0/groups/dfc8016f-db97-4c47-a582-49cb8f849355 +Content-type: application/json -## 5. Get a group and its extension data +{ + "bellowscollege_courses": { + "courseId": "123", + "courseName": "New Managers", + "courseType": "Hybrid" + } +} +``` -A handy way to look for a group (or groups) is to use `$filter` to match for specific extension property values, -such as an extension name or ID. +## Step 5. Get a group and its extension data -Then, to get the custom data in a group, use `$select` to include the extension by name (in this case by `graphlearn_courses`). +To get the custom data in a group, use `$select` to include the extension by name. -The following example looks for the group that has the `graphlearn_courses` extension with a `courseId` property value matching `123`, and gets the group properties **displayName**, **id**, and **description**, and the custom data in the `graphlearn_courses` extension. +Apart from filtering by the **id** of the schema extension, you can also filter by the extension property values. The following example looks for the group that has the `bellowscollege_courses` extension with a `courseId` property value matching `123`, and gets the extension data and the **displayName**, **id**, and **description** properties of the group. ### Request @@ -417,7 +426,7 @@ The following example looks for the group that has the `graphlearn_courses` exte "name": "schemaextensions-groups-getGroupSelectExtension" }--> ```msgraph-interactive -GET https://graph.microsoft.com/v1.0/groups?$filter=graphlearn_courses/courseId eq '123'&$select=displayName,id,description,graphlearn_courses +GET https://graph.microsoft.com/v1.0/groups?$filter=bellowscollege_courses/courseId eq '123'&$select=displayName,id,description,bellowscollege_courses ``` # [C#](#tab/csharp) @@ -466,23 +475,52 @@ HTTP/1.1 200 OK Content-Type: application/json { + "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#groups(displayName,id,description,bellowscollege_courses)", "value": [ { - "displayName": "New Managers March 2017", - "id": "14429ae5-3e74-41a2-9fa8-028fbb984637", - "description": "New Managers training course for March 2017", - "graphlearn_courses": { + "displayName": "New Managers March 2024", + "id": "8fb45944-4085-449f-b95d-f7dd74a1b081", + "description": "New Managers training course for March 2024", + "bellowscollege_courses": { "@odata.type": "#microsoft.graph.ComplexExtensionValue", - "courseId": "123", + "courseType": "Hybrid", "courseName": "New Managers", - "courseType": "Online" + "courseId": 123 } } ] } ``` -## See also +## Step 6: Delete extension data and schema extension definition + +You can delete a schema extension definition if you no longer need it. If resource instances have the extension property applied, deleting the schema extension definition doesn't delete the extension data in the resource instances. Instead, the extension data is available but no longer accessible. You can recreate the schema extension definition with the same configuration - if you used the verified domain for the schema extension **id** - to be able to delete the extension data. + +The following request deletes the `bellowscollege_courses` schema extension property and its associated data from the group. The request returns a `204 No Content` response. + + +```http +PATCH https://graph.microsoft.com/v1.0/groups/8fb45944-4085-449f-b95d-f7dd74a1b081 + +{ + "bellowscollege_courses": null +} +``` + +The following request deletes the `bellowscollege_courses` schema extension definition. The request returns a `204 No Content` response. + + +```http +DELETE https://graph.microsoft.com/v1.0/schemaExtensions/bellowscollege_courses +``` + +## Related content - [Add custom data to resources using extensions](extensibility-overview.md) - [Add custom data to users using open extensions (preview)](extensibility-open-users.md) diff --git a/concepts/filter-query-parameter.md b/concepts/filter-query-parameter.md index 315e0d9c37d..86aee50339b 100644 --- a/concepts/filter-query-parameter.md +++ b/concepts/filter-query-parameter.md @@ -43,7 +43,7 @@ OData defines the `any` and `all` operators to evaluate matches on multi-valued ### `any` operator The `any` operator iteratively applies a Boolean expression to each item of a collection and returns `true` if the expression is `true` for *at least one item* of the collection, otherwise it returns `false`. -The following is the syntax of the `any` operator: +The following query string shows the syntax for the `any` operator: ```http $filter=collection/any(property:property/subProperty eq 'value-to-match') @@ -56,7 +56,7 @@ Where + *subProperty* is required when the query applies to a collection of entities. It represents the property of the complex type whose value you're matching against. + *value-to-match* represents the member of the collection against which you're matching. -If you are familiar with `C#` and `LINQ`, this would be the equivalent of the above syntax: +The equivalent syntax in `C#` and `LINQ` is as follows: ```csharp collection.Any(property => property.subProperty == "value-to-match") @@ -204,7 +204,7 @@ ConsistencyLevel: eventual ### `all` operator -The `all` operator applies a Boolean expression to each member of a collection and returns `true` if the expression is `true` for *all the items* of the collection, otherwise it returns `false`. It isn't supported by any property. +The `all` operator applies a Boolean expression to each member of a collection and returns `true` if the expression is `true` for *all the items* of the collection, otherwise it returns `false`. Currently, no property supports it. ## Examples using the filter query operator @@ -212,24 +212,24 @@ The following table shows some examples that use the `$filter` query parameter. > [!NOTE] > -> + Examples marked with * are only supported with [advanced query capabilities](/graph/aad-advanced-queries). +> + Examples marked with ** are only supported with [advanced query capabilities](/graph/aad-advanced-queries). > + Click the examples to try them in [Graph Explorer][graph-explorer]. | Description | Example | | :------------------------------------------------------------------------------------------------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Get all users with the name Mary across multiple properties. | [GET](https://developer.microsoft.com/graph/graph-explorer?request=users?$filter=startswith(displayName,'mary')+or+startswith(givenName,'mary')+or+startswith(surname,'mary')+or+startswith(mail,'mary')+or+startswith(userPrincipalName,'mary')&method=GET&version=v1.0) `~/users?$filter=startswith(displayName,'mary') or startswith(givenName,'mary') or startswith(surname,'mary') or startswith(mail,'mary') or startswith(userPrincipalName,'mary')` | -| Get all users with mail domain equal to 'hotmail.com' | [GET](https://developer.microsoft.com/graph/graph-explorer?request=users%3F%24count%3Dtrue%26%24filter%3DendsWith(mail%2C'%40hotmail.com')%26%24select%3Did%2CdisplayName%2Cmail&method=GET&version=v1.0&GraphUrl=https://graph.microsoft.com&headers=W3sibmFtZSI6IkNvbnNpc3RlbmN5TGV2ZWwiLCJ2YWx1ZSI6ImV2ZW50dWFsIn1d) `~/users?$count=true&$filter=endsWith(mail,'@hotmail.com')`* | -| Get all users without assigned licenses | [GET](https://developer.microsoft.com/graph/graph-explorer?request=users%3F%24filter%3DassignedLicenses%2F%24count%2Bne%2B0%26%24count%3Dtrue&method=GET&version=v1.0&GraphUrl=https://graph.microsoft.com&headers=W3sibmFtZSI6IkNvbnNpc3RlbmN5TGV2ZWwiLCJ2YWx1ZSI6ImV2ZW50dWFsIn1d) `~/users?$filter=assignedLicenses/$count eq 0&$count=true`* | +| Get all users with mail domain equal to 'hotmail.com' | [GET](https://developer.microsoft.com/graph/graph-explorer?request=users%3F%24count%3Dtrue%26%24filter%3DendsWith(mail%2C'%40hotmail.com')%26%24select%3Did%2CdisplayName%2Cmail&method=GET&version=v1.0&GraphUrl=https://graph.microsoft.com&headers=W3sibmFtZSI6IkNvbnNpc3RlbmN5TGV2ZWwiLCJ2YWx1ZSI6ImV2ZW50dWFsIn1d) `~/users?$count=true&$filter=endsWith(mail,'@hotmail.com')` [ ** ](#**) | +| Get all users without assigned licenses | [GET](https://developer.microsoft.com/graph/graph-explorer?request=users%3F%24filter%3DassignedLicenses%2F%24count%2Bne%2B0%26%24count%3Dtrue&method=GET&version=v1.0&GraphUrl=https://graph.microsoft.com&headers=W3sibmFtZSI6IkNvbnNpc3RlbmN5TGV2ZWwiLCJ2YWx1ZSI6ImV2ZW50dWFsIn1d) `~/users?$filter=assignedLicenses/$count eq 0&$count=true` [ ** ](#**) | | Get all the signed-in user's events that start after 7/1/2017. | [GET](https://developer.microsoft.com/graph/graph-explorer?request=me/events?$filter=start/dateTime+ge+'2017-07-01T08:00'&method=GET&version=v1.0) `~/me/events?$filter=start/dateTime ge '2017-07-01T08:00'`.
**NOTE:** The **dateTime** property of the event entity is a String type. | | Get all emails from a specific address received by the signed-in user. | [GET](https://developer.microsoft.com/graph/graph-explorer?request=me/messages?$filter=from/emailAddress/address+eq+'someuser@.com'&method=GET&version=v1.0) `~/me/messages?$filter=from/emailAddress/address eq 'someuser@example.com'` | | Get all emails received by the signed-in user in April 2017. | [GET](https://developer.microsoft.com/graph/graph-explorer?request=me/mailFolders/inbox/messages?$filter=ReceivedDateTime+ge+2017-04-01+and+receivedDateTime+lt+2017-05-01&method=GET&version=v1.0) `~/me/mailFolders/inbox/messages?$filter=ReceivedDateTime ge 2017-04-01 and receivedDateTime lt 2017-05-01` | | Get all unread mail in the signed-in user's Inbox. | [GET](https://developer.microsoft.com/graph/graph-explorer?request=me/mailFolders/inbox/messages?$filter=isRead+eq+false&method=GET&version=v1.0) `~/me/mailFolders/inbox/messages?$filter=isRead eq false` | | Get all users in the Retail and Sales departments. | [GET](https://developer.microsoft.com/graph/graph-explorer?request=users%3F%24filter%3Ddepartment%20in%20('Retail'%2C%20'Sales')&method=GET&version=v1.0&GraphUrl=https://graph.microsoft.com) `~/users?$filter=department in ('Retail', 'Sales')` | -| List users with a particular service plan that is in a suspended state. | [GET](https://developer.microsoft.com/graph/graph-explorer?request=users%3F%24filter%3DassignedPlans%2Fany(a%3Aa%2FservicePlanId%20eq%202e2ddb96-6af9-4b1d-a3f0-d6ecfd22edb2%20and%20a%2FcapabilityStatus%20eq%20'Suspended')%26%24count%3Dtrue&method=GET&version=v1.0&GraphUrl=https://graph.microsoft.com&headers=W3sibmFtZSI6IkNvbnNpc3RlbmN5TGV2ZWwiLCJ2YWx1ZSI6ImV2ZW50dWFsIn1d) `~/users?$filter=assignedPlans/any(a:a/servicePlanId eq 2e2ddb96-6af9-4b1d-a3f0-d6ecfd22edb2 and a/capabilityStatus eq 'Suspended')&$count=true`* | -| List all non-Microsoft 365 groups in an organization. | [GET](https://developer.microsoft.com/graph/graph-explorer?request=groups%3F%24filter%3DNOT%20groupTypes%2Fany(c%3Ac%20eq%20'Unified')%26%24count%3Dtrue&method=GET&version=v1.0&GraphUrl=https://graph.microsoft.com&headers=W3sibmFtZSI6IkNvbnNpc3RlbmN5TGV2ZWwiLCJ2YWx1ZSI6ImV2ZW50dWFsIn1d) `~/groups?$filter=NOT groupTypes/any(c:c eq 'Unified')&$count=true`* | -| List all users whose company name isn't undefined (that is, not a `null` value) or Microsoft. | [GET](https://developer.microsoft.com/graph/graph-explorer?request=users%3F%24filter%3DcompanyName%20ne%20null%20and%20NOT(companyName%20eq%20'Microsoft')%26%24count%3Dtrue&method=GET&version=v1.0&GraphUrl=https://graph.microsoft.com&headers=W3sibmFtZSI6IkNvbnNpc3RlbmN5TGV2ZWwiLCJ2YWx1ZSI6ImV2ZW50dWFsIn1d) `~/users?$filter=companyName ne null and NOT(companyName eq 'Microsoft')&$count=true`* | -| List all users whose company name is either undefined or Microsoft. | [GET](https://developer.microsoft.com/graph/graph-explorer?request=users%3F%24filter%3DcompanyName%20in%20(null%2C%20'Microsoft')%26%24count%3Dtrue&method=GET&version=v1.0&GraphUrl=https://graph.microsoft.com&headers=W3sibmFtZSI6IkNvbnNpc3RlbmN5TGV2ZWwiLCJ2YWx1ZSI6ImV2ZW50dWFsIn1d) `~/users?$filter=companyName in (null, 'Microsoft')&$count=true`* | -| Use OData cast to get transitive membership in groups with a display name that starts with 'a' including a count of returned objects. | [GET](https://developer.microsoft.com/graph/graph-explorer?request=me%2FtransitiveMemberOf%2Fmicrosoft.graph.group%3F%24count%3Dtrue&method=GET&version=v1.0&GraphUrl=https://graph.microsoft.com&headers=W3sibmFtZSI6IkNvbnNpc3RlbmN5TGV2ZWwiLCJ2YWx1ZSI6ImV2ZW50dWFsIn1d) `~/me/transitiveMemberOf/microsoft.graph.group?$count=true&$filter=startswith(displayName, 'a')`* | +| List users with a particular service plan that is in a suspended state. | [GET](https://developer.microsoft.com/graph/graph-explorer?request=users%3F%24filter%3DassignedPlans%2Fany(a%3Aa%2FservicePlanId%20eq%202e2ddb96-6af9-4b1d-a3f0-d6ecfd22edb2%20and%20a%2FcapabilityStatus%20eq%20'Suspended')%26%24count%3Dtrue&method=GET&version=v1.0&GraphUrl=https://graph.microsoft.com&headers=W3sibmFtZSI6IkNvbnNpc3RlbmN5TGV2ZWwiLCJ2YWx1ZSI6ImV2ZW50dWFsIn1d) `~/users?$filter=assignedPlans/any(a:a/servicePlanId eq 2e2ddb96-6af9-4b1d-a3f0-d6ecfd22edb2 and a/capabilityStatus eq 'Suspended')&$count=true` [ ** ](#**) | +| List all non-Microsoft 365 groups in an organization. | [GET](https://developer.microsoft.com/graph/graph-explorer?request=groups%3F%24filter%3DNOT%20groupTypes%2Fany(c%3Ac%20eq%20'Unified')%26%24count%3Dtrue&method=GET&version=v1.0&GraphUrl=https://graph.microsoft.com&headers=W3sibmFtZSI6IkNvbnNpc3RlbmN5TGV2ZWwiLCJ2YWx1ZSI6ImV2ZW50dWFsIn1d) `~/groups?$filter=NOT groupTypes/any(c:c eq 'Unified')&$count=true` [ ** ](#**) | +| List all users whose company name isn't undefined (that is, not a `null` value) or Microsoft. | [GET](https://developer.microsoft.com/graph/graph-explorer?request=users%3F%24filter%3DcompanyName%20ne%20null%20and%20NOT(companyName%20eq%20'Microsoft')%26%24count%3Dtrue&method=GET&version=v1.0&GraphUrl=https://graph.microsoft.com&headers=W3sibmFtZSI6IkNvbnNpc3RlbmN5TGV2ZWwiLCJ2YWx1ZSI6ImV2ZW50dWFsIn1d) `~/users?$filter=companyName ne null and NOT(companyName eq 'Microsoft')&$count=true` [ ** ](#**) | +| List all users whose company name is either undefined or Microsoft. | [GET](https://developer.microsoft.com/graph/graph-explorer?request=users%3F%24filter%3DcompanyName%20in%20(null%2C%20'Microsoft')%26%24count%3Dtrue&method=GET&version=v1.0&GraphUrl=https://graph.microsoft.com&headers=W3sibmFtZSI6IkNvbnNpc3RlbmN5TGV2ZWwiLCJ2YWx1ZSI6ImV2ZW50dWFsIn1d) `~/users?$filter=companyName in (null, 'Microsoft')&$count=true` [ ** ](#**) | +| Use OData cast to get transitive membership in groups with a display name that starts with 'a' including a count of returned objects. | [GET](https://developer.microsoft.com/graph/graph-explorer?request=me%2FtransitiveMemberOf%2Fmicrosoft.graph.group%3F%24count%3Dtrue&method=GET&version=v1.0&GraphUrl=https://graph.microsoft.com&headers=W3sibmFtZSI6IkNvbnNpc3RlbmN5TGV2ZWwiLCJ2YWx1ZSI6ImV2ZW50dWFsIn1d) `~/me/transitiveMemberOf/microsoft.graph.group?$count=true&$filter=startswith(displayName, 'a')` [ ** ](#**) | ## Syntax for using the filter OData query parameter @@ -239,26 +239,26 @@ These examples show how to use `$filter` to match against supported properties a > [!NOTE] > -> + Examples marked with * are only supported with [advanced query capabilities](/graph/aad-advanced-queries). -> > + GUID and DateTimeOffset values aren't enclosed in quotes in `$filter` expressions. + ** : This example is only supported with [advanced query capabilities](/graph/aad-advanced-queries). + ### For single primitive types like String, Int, and dates | Operator | Syntax | |-------------------------|-------------------------------------------------------------------------------------------------------------------------------------| | `eq` | `~/users?$filter=userType eq 'Member'` | -| `not` | `~/users?$filter=not(userType eq 'Member')`* | -| `ne` | `~/users?$filter=companyName ne null`* | +| `not` | `~/users?$filter=not(userType eq 'Member')` [ ** ](#**) | +| `ne` | `~/users?$filter=companyName ne null` [ ** ](#**) | | `startsWith` | `~/users?$filter=startsWith(userPrincipalName, 'admin')` | -| `endsWith` | `~/users?$filter=endsWith(mail,'@outlook.com')`* | -| `in` | `~/users?$filter=mail in ('mail1@domain.com', 'mail2@domain.com')`

**Note:** When using the `in` operator, the request is limited to 15 expressions in the filter clause by default or a URL length of 2,048 characters when using [advanced query capabilities](./aad-advanced-queries.md). | -| `le` | `~/devices?$filter=registrationDateTime le 2021-01-02T12:00:00Z`* | -| `ge` | `~/devices?$filter=registrationDateTime ge 2021-01-02T12:00:00Z`* | -| `not` and `endsWith` | `~/users?$filter=not(endsWith(mail, 'OnMicrosoft.com'))`* | -| `not` and `startsWith` | `~/users?$filter=not(startsWith(mail, 'A'))`* | -| `not` and `eq` | `~/users?$filter=not(companyName eq 'Contoso E.A.')`* | -| `not` and `in` | `~/users?$filter=not(userType in ('Member'))`* | +| `endsWith` | `~/users?$filter=endsWith(mail,'@outlook.com')` [ ** ](#**) | +| `in` | `~/users?$filter=mail in ('mail1@domain.com', 'mail2@domain.com')`

**Note:** For query strings using `in` operator, the request is limited to 15 expressions in the filter clause by default or a URL length of 2,048 characters when using [advanced query capabilities](./aad-advanced-queries.md). | +| `le` | `~/devices?$filter=registrationDateTime le 2021-01-02T12:00:00Z` [ ** ](#**) | +| `ge` | `~/devices?$filter=registrationDateTime ge 2021-01-02T12:00:00Z` [ ** ](#**) | +| `not` and `endsWith` | `~/users?$filter=not(endsWith(mail, 'OnMicrosoft.com'))` [ ** ](#**) | +| `not` and `startsWith` | `~/users?$filter=not(startsWith(mail, 'A'))` [ ** ](#**) | +| `not` and `eq` | `~/users?$filter=not(companyName eq 'Contoso E.A.')` [ ** ](#**) | +| `not` and `in` | `~/users?$filter=not(userType in ('Member'))` [ ** ](#**) | | `contains` | `~/identityGovernance/accessReviews/definitions?$filter=contains(scope/microsoft.graph.accessReviewQueryScope/query, './members')` | | `has` | `~/identity/conditionalAccess/templates?$filter=scenarios has 'secureFoundation'` | @@ -267,17 +267,17 @@ These examples show how to use `$filter` to match against supported properties a | Operator (s) | Syntax | |-------------------------------------------|---------------------------------------------------------------------| | `eq` | `~/groups?$filter=groupTypes/any(c:c eq 'Unified')` | -| `not` | `~/groups?$filter=not(groupTypes/any(c:c eq 'Unified'))`* | -| `ne` | `~/users?$filter=companyName ne null`* | -| `startsWith` | `~/users?$filter=businessPhones/any(p:startsWith(p, '44'))`* | -| `endsWith` | `~/users?$filter=endsWith(mail,'@outlook.com')`* | -| `not` and `endsWith` | `~/groups?$filter=not(endsWith(mail,'OnMicrosoft.com'))`* | -| `not` and `startsWith` | `~/groups?$filter=not(startsWith(mail,'Pineview'))`* | -| `not` and `eq` | `~/groups?$filter=not(mail eq 'PineviewSchoolStaff@Contoso.com')`* | -| `eq` and `$count` for empty collections | `~/users?$filter=assignedLicenses/$count eq 0`* | -| `ne` and `$count` for empty collections | `~/users?$filter=assignedLicenses/$count ne 0`* | -| `not` and `$count` for empty collections | `~/users?$filter=not(assignedLicenses/$count eq 0)`* | -| `$count` for collections with one object | `~/servicePrincipals?$filter=owners/$count eq 1`* | +| `not` | `~/groups?$filter=not(groupTypes/any(c:c eq 'Unified'))` [ ** ](#**) | +| `ne` | `~/users?$filter=companyName ne null` [ ** ](#**) | +| `startsWith` | `~/users?$filter=businessPhones/any(p:startsWith(p, '44'))` [ ** ](#**) | +| `endsWith` | `~/users?$filter=endsWith(mail,'@outlook.com')` [ ** ](#**) | +| `not` and `endsWith` | `~/groups?$filter=not(endsWith(mail,'OnMicrosoft.com'))` [ ** ](#**) | +| `not` and `startsWith` | `~/groups?$filter=not(startsWith(mail,'Pineview'))` [ ** ](#**) | +| `not` and `eq` | `~/groups?$filter=not(mail eq 'PineviewSchoolStaff@Contoso.com')` [ ** ](#**) | +| `eq` and `$count` for empty collections | `~/users?$filter=assignedLicenses/$count eq 0` [ ** ](#**) | +| `ne` and `$count` for empty collections | `~/users?$filter=assignedLicenses/$count ne 0` [ ** ](#**) | +| `not` and `$count` for empty collections | `~/users?$filter=not(assignedLicenses/$count eq 0)` [ ** ](#**) | +| `$count` for collections with one object | `~/servicePrincipals?$filter=owners/$count eq 1` [ ** ](#**) | For the list of all properties of directory objects that support count of a collection in a filter expression, see [Count of a collection in a filter expression](/graph/aad-advanced-queries#count-of-a-collection-in-a-filter-expression). @@ -286,12 +286,13 @@ For the list of all properties of directory objects that support count of a coll no examples available for ge and le --> + ### For GUID types | Operator (s) | Syntax | |---------------|-----------------------------------------------------------------------------------------------------------------| -| `eq` | `~/servicePrincipals?$filter=appOwnerOrganizationId eq 72f988bf-86f1-41af-91ab-2d7cd011db47`* | -| `not` | `~/servicePrincipals?$filter=not(appOwnerOrganizationId eq 72f988bf-86f1-41af-91ab-2d7cd011db47)`* | +| `eq` | `~/servicePrincipals?$filter=appOwnerOrganizationId eq 72f988bf-86f1-41af-91ab-2d7cd011db47` [ ** ](#**) | +| `not` | `~/servicePrincipals?$filter=not(appOwnerOrganizationId eq 72f988bf-86f1-41af-91ab-2d7cd011db47)` [ ** ](#**) | + ### For a collection of GUID types | Operator (s) | Syntax | |---------------|-----------------------------------------------------------------| -| `eq` | `~/devices?$filter=alternativeSecurityIds/any(a:a/type eq 2)`* | -| `le` | `~/devices?$filter=alternativeSecurityIds/any(a:a/type le 2)`* | -| `ge` | `~/devices?$filter=alternativeSecurityIds/any(a:a/type ge 2)`* | +| `eq` | `~/devices?$filter=alternativeSecurityIds/any(a:a/type eq 2)` [ ** ](#**) | +| `le` | `~/devices?$filter=alternativeSecurityIds/any(a:a/type le 2)` [ ** ](#**) | +| `ge` | `~/devices?$filter=alternativeSecurityIds/any(a:a/type ge 2)` [ ** ](#**) | + ### For a collection of complex types | Operator (s) | Syntax | |-----------------|--------------------------------------------------------------------------------------------| -| `eq` | `~/users?$filter=authorizationInfo/certificateUserIds/any(x:x eq '9876543210@mil')`* | -| `not` and `eq` | `~/users?$filter=not(authorizationInfo/certificateUserIds/any(x:x eq '9876543210@mil'))`* | -| `startsWith` | `~/users?$filter=authorizationInfo/certificateUserIds/any(x:startswith(x,'987654321'))`* | -| `endsWith` | `~/users?$filter=proxyAddresses/any(p:endsWith(p,'OnMicrosoft.com'))`* | +| `eq` | `~/users?$filter=authorizationInfo/certificateUserIds/any(x:x eq '9876543210@mil')` [ ** ](#**) | +| `not` and `eq` | `~/users?$filter=not(authorizationInfo/certificateUserIds/any(x:x eq '9876543210@mil'))` [ ** ](#**) | +| `startsWith` | `~/users?$filter=authorizationInfo/certificateUserIds/any(x:startswith(x,'987654321'))` [ ** ](#**) | +| `endsWith` | `~/users?$filter=proxyAddresses/any(p:endsWith(p,'OnMicrosoft.com'))` [ ** ](#**) | + ## See also diff --git a/concepts/permissions-grant-via-msgraph.md b/concepts/permissions-grant-via-msgraph.md index 20cc2cea365..231645cb9db 100644 --- a/concepts/permissions-grant-via-msgraph.md +++ b/concepts/permissions-grant-via-msgraph.md @@ -32,7 +32,7 @@ To complete these instructions, you need the following resources and privileges: - You'll run the requests in this article as a user. You must complete the following steps: - Sign in to an app such as [Graph Explorer](https://developer.microsoft.com/graph/graph-explorer) or [Postman](/graph/use-postman) as a user with privileges to create applications in the tenant. - In the app you've signed in to, consent to the *Application.Read.All* and *AppRoleAssignment.ReadWrite.All* delegated permissions on behalf of the signed-in user. You don't need to consent on behalf of your organization. - - Get the object ID of the client service principal to which you'll grant app roles. In this article, the client service principal is identified by ID `b0d9b9e3-0ecf-4bfd-8dab-9273dd055a94`. + - Get the object ID of the client service principal to which you'll grant app roles. In this article, the client service principal is identified by ID `b0d9b9e3-0ecf-4bfd-8dab-9273dd055a94`. In the Microsoft Entra admin center, go to **Identity** > **Applications** > **Enterprise applications** > **App applications** to find the client service principal. Select it and on the **Overview** page, copy the Object ID value.