From 2c168f099dc8c61ffd8a1fe70ecdeae0c5a3affe Mon Sep 17 00:00:00 2001 From: ytognder <60838829+ytognder@users.noreply.github.com> Date: Fri, 18 Sep 2020 00:13:10 +0300 Subject: [PATCH] Azure ad IP (#449) * update new action * [timeghost] usability improvements (#402) * [timeghost] Certified connector publishing * add x-function-key * add x-function key * usability improvements * add policyTemplateInstances * publisher and stackOwner added * validator fixes * validator fixes * contact and x-ms-connector-metadata added * x-ms-connector-metadata Categories changed * remove invalid characters * remove umlauts Co-authored-by: Marc Hochleutner * AzureAdIP * fix_pr_error Co-authored-by: Marc Co-authored-by: Marc Hochleutner --- .../AzureAdIp/apiDefinition.swagger.json | 502 ++++++++++++++++++ .../AzureAdIp/apiProperties.json | 56 ++ custom-connectors/AzureAdIp/readme.md | 14 + 3 files changed, 572 insertions(+) create mode 100644 custom-connectors/AzureAdIp/apiDefinition.swagger.json create mode 100644 custom-connectors/AzureAdIp/apiProperties.json create mode 100644 custom-connectors/AzureAdIp/readme.md diff --git a/custom-connectors/AzureAdIp/apiDefinition.swagger.json b/custom-connectors/AzureAdIp/apiDefinition.swagger.json new file mode 100644 index 000000000..6b2ebfbe1 --- /dev/null +++ b/custom-connectors/AzureAdIp/apiDefinition.swagger.json @@ -0,0 +1,502 @@ +{ + "swagger": "2.0", + "info": { + "version": "1.0.0", + "title": "Azure AD Identity Protection", + "description": "Identity Protection is a tool that allows organizations to discover, investigate, and remediate identity-based risks in their environment.", + "x-ms-deployment-version": "1.0.0", + "x-ms-api-annotation": { + "status": "Preview" + }, + "contact": { + "name": "Microsoft", + "url": "https://azure.microsoft.com/", + "email": "azuresentinel@microsoft.com" + } + }, + "host": "graph.microsoft.com", + "basePath": "/", + "schemes": [ + "https" + ], + "consumes": [], + "produces": [ + "application/json" + ], + "paths": { + "/beta/riskyUsers/{Id}": { + "get": { + "summary": "Get risky user", + "description": "Get a specific risky user and its properties", + "operationId": "GetRiskUser", + "parameters": [ + { + "name": "Id", + "in": "path", + "required": true, + "description": "User Id or user Principal name", + "type": "string", + "x-ms-summary": "Get Risk User", + "x-ms-url-encoding": "single" + } + ], + "responses": { + "201": { + "description": "201", + "schema": { + "$ref": "#/definitions/Get_Risk_User_Result" + } + } + }, + "x-ms-no-generic-test": true, + "deprecated": false + } + }, + "/beta/riskyUsers/confirmCompromised": { + "post": { + "summary": "Confirm a risky user as compromised", + "description": "Confirm a risky user as compromised", + "operationId": "ConfirmRiskUser", + "x-ms-summary": "confirmCompromised user", + "parameters": [ + { + "name": "body", + "in": "body", + "schema": { + "type": "object", + "properties": { + "userIds": { + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + ], + "responses": { + "201": { + "description": "OK" + } + } + } + }, + "/beta/riskDetections/{Id}": { + "get": { + "summary": "Get risk detections", + "description": "Get riskDetections ", + "operationId": "riskDetections", + "parameters": [ + { + "name": "Id", + "in": "path", + "required": true, + "description": "User Id or user Principal Name", + "type": "string", + "x-ms-summary": "Get risk detections", + "x-ms-url-encoding": "single" + } + ], + "responses": { + "201": { + "description": "201", + "schema": { + "$ref": "#/definitions/Get_riskDetection" + } + } + }, + "x-ms-no-generic-test": true, + "deprecated": false + } + }, + "/beta/riskyUsers/dismiss": { + "post": { + "summary": "Dismiss a risky user", + "description": "Dismiss a risky user", + "operationId": "DismissRiskUser", + "x-ms-summary": "Dismiss a risky user", + "parameters": [ + { + "name": "body", + "in": "body", + "schema": { + "type": "object", + "properties": { + "userIds": { + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + ], + "responses": { + "201": { + "description": "OK" + } + } + } + }, + "/beta/riskyUsers/{Id}/history": { + "get": { + "summary": "Get the risk history of a risky user", + "description": "Get the risk history", + "operationId": "GetRiskUserHistory", + "x-ms-summary": "History user Data", + "parameters": [ + { + "name": "Id", + "in": "path", + "required": true, + "description": "User Id or user Principal Name", + "type": "string", + "x-ms-summary": "Get history risk for user " + } + ], + "responses": { + "201": { + "description": "201", + "schema": { + "$ref": "#/definitions/Get_risk_history" + } + } + } + } + } + }, + "definitions": { + "Get_Risk_User_Result": { + "description": "Get risk user result", + "type": "object", + "properties": { + "@@odata.context": { + "type": "string" + }, + "id": { + "type": "string", + "description": "Unique ID of the user at risk" + }, + "isDeleted": { + "type": "boolean", + "description": "Indicates whether the user is deleted. Possible values are: true, false" + }, + "isProcessing": { + "type": "boolean", + "description": "Indicates whether a user's risky state is being processed by the backend" + }, + "riskLevel": { + "type": "string", + "description": "Level of the detected risky user" + }, + "riskState": { + "type": "string", + "description": "The date and time that the risky user was last updated" + }, + "riskDetail": { + "type": "string", + "description": "Details of the detected risk" + }, + "riskLastUpdatedDateTime": { + "type": "string", + "description": "The date and time that the risky user was last updated." + }, + "userDisplayName": { + "type": "string", + "description": "Risky user display name" + }, + "userPrincipalName": { + "type": "string", + "description": "Risky user principal name" + } + } + }, + "Get_History": { + "description": "Get History Data", + "type": "object", + "properties": { + "@@odata.context": { + "type": "string" + }, + "value": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "isDeleted": { + "type": "boolean" + }, + "isProcessing": { + "type": "boolean" + }, + "riskLevel": { + "type": "string" + }, + "riskState": { + "type": "string" + }, + "riskDetail": { + "type": "string" + }, + "riskLastUpdatedDateTime": { + "type": "string" + }, + "userDisplayName": { + "type": "string" + }, + "userPrincipalName": { + "type": "string" + }, + "userId": { + "type": "string" + }, + "initiatedBy": {}, + "activity": { + "type": "object", + "properties": { + "eventTypes": { + "type": "array", + "items": { + "type": "string" + } + }, + "riskEventTypes": { + "type": "array", + "items": { + "type": "string" + } + }, + "detail": {} + } + } + }, + "required": [ + "id", + "isDeleted", + "isProcessing", + "riskLevel", + "riskState", + "riskDetail", + "riskLastUpdatedDateTime", + "userDisplayName", + "userPrincipalName", + "userId", + "initiatedBy", + "activity" + ] + } + } + } + }, + "Get_riskDetection": { + "description": "This API provides programmatic access to all risk detections in your Azure AD environment", + "type": "object", + "properties": { + "@@odata.type": { + "type": "string" + }, + "id": { + "type": "string", + "description": "Unique ID of the risk detection. Inherited from entity" + }, + "requestId": { + "type": "string", + "description": "Request ID of the sign-in associated with the risk detection. This property is null if the risk detection is not associated with a sign-in" + }, + "correlationId": { + "type": "string", + "description": "Correlation ID of the sign-in associated with the risk detection. This property is null if the risk detection is not associated with a sign-in" + }, + "riskEventType": { + "type": "string", + "description": "The type of risk event detected" + }, + "riskState": { + "type": "string", + "description": "The state of a detected risky user or sign-in" + }, + "riskLevel": { + "type": "string", + "description": "Level of the detected risk" + }, + "riskDetail": { + "type": "string", + "description": "Details of the detected risk" + }, + "source": { + "type": "string", + "description": "Source of the risk detection" + }, + "detectionTimingType": { + "type": "string", + "description": "Date and time that the risk was detected" + }, + "activity": { + "type": "string", + "description": "Indicates the activity type the detected risk is linked to" + }, + "tokenIssuerType": { + "type": "string", + "description": "Indicates the type of token issuer for the detected sign-in risk" + }, + "ipAddress": { + "type": "string", + "description": "Provides the IP address of the client from where the risk occurred." + }, + "location": { + "type": "object", + "description": "Location of the sign-in", + "properties": { + "@@odata.type": { + "type": "string" + } + } + }, + "activityDateTime": { + "type": "string", + "description": "Date and time that the risky activity occurred" + }, + "detectedDateTime": { + "type": "string", + "description": "Date and time that the risk was detected" + }, + "lastUpdatedDateTime": { + "type": "string", + "description": "Date and time that the risk detection was last updated" + }, + "userId": { + "type": "string", + "description": "Unique ID of the user" + }, + "userDisplayName": { + "type": "string", + "description": "The user principal name (UPN) of the user" + }, + "userPrincipalName": { + "type": "string", + "description": "The user principal name (UPN) of the user." + }, + "additionalInfo": { + "type": "string", + "description": "Additional information associated with the risk detection in JSON format." + } + } + }, + "Get_risk_history": { + "description": "Represents the risk history of an Azure AD user as determined by Azure AD Identity Protection", + "type": "object", + "properties": { + "@@odata.type": { + "type": "string" + }, + "id": { + "type": "string", + "description": "Inherited from entity" + }, + "isDeleted": { + "type": "string", + "description": "Inherited from riskyUser" + }, + "isProcessing": { + "type": "string", + "description": "Inherited from riskyUser" + }, + "riskLastUpdatedDateTime": { + "type": "string", + "description": "Inherited from riskyUser" + }, + "riskLevel": { + "type": "string", + "description": "Inherited from riskyUser" + }, + "riskState": { + "type": "string", + "description": "Inherited from riskyUser" + }, + "riskDetail": { + "type": "string", + "description": "Inherited from riskyUser" + }, + "userDisplayName": { + "type": "string", + "description": "Inherited from riskyUser" + }, + "userPrincipalName": { + "type": "string", + "description": "Risky user principal name" + }, + "userId": { + "type": "string", + "description": "The id of the user" + }, + "initiatedBy": { + "type": "string", + "description": "The id of actor that does the operation" + }, + "activity": { + "type": "object", + "description": "The activity related to user risk level change", + "properties": { + "@@odata.type": { + "type": "string" + } + } + } + } + } + }, + "parameters": {}, + "responses": {}, + "securityDefinitions": { + "oauth2_auth": { + "type": "oauth2", + "flow": "accessCode", + "authorizationUrl": "https://login.windows.net/common/oauth2/authorize", + "tokenUrl": "https://login.windows.net/common/oauth2/authorize", + "scopes": { + "Directory.ReadWrite.All": "Directory.ReadWrite.All", + "Group.ReadWrite.All": "Group.ReadWrite.All", + "User.ReadWrite.All": "User.ReadWrite.All", + "offline_access": "offline_access", + "IdentityRiskEvent.Read.All": "IdentityRiskEvent.Read.All", + "IdentityRiskEvent.ReadWrite.All": "IdentityRiskEvent.ReadWrite.All", + "IdentityRiskyUser.Read.All": "IdentityRiskyUser.Read.All", + "IdentityRiskyUser.ReadWrite.All": "IdentityRiskyUser.ReadWrite.All" + } + } + }, + "security": [ + { + "oauth2_auth": [ + "Directory.ReadWrite.All", + "Group.ReadWrite.All", + "User.ReadWrite.All", + "offline_access", + "IdentityRiskEvent.Read.All", + "IdentityRiskEvent.ReadWrite.All", + "IdentityRiskyUser.Read.All", + "IdentityRiskyUser.ReadWrite.All" + ] + } + ], + "tags": [], + "x-ms-connector-metadata": [ + { + "propertyName": "Website", + "propertyValue": "https://www.microsoft.com" + }, + { + "propertyName": "Privacy policy", + "propertyValue": "https://privacy.microsoft.com/en-us/privacystatement" + }, + { + "propertyName": "Categories", + "propertyValue": "Website" + } + ] +} \ No newline at end of file diff --git a/custom-connectors/AzureAdIp/apiProperties.json b/custom-connectors/AzureAdIp/apiProperties.json new file mode 100644 index 000000000..4a682c206 --- /dev/null +++ b/custom-connectors/AzureAdIp/apiProperties.json @@ -0,0 +1,56 @@ +{ + "properties": { + "connectionParameters": { + "token": { + "type": "oauthSetting", + "oAuthSettings": { + "identityProvider": "aad", + "clientId": "b37216c7-2651-4ee5-9c5d-617a30978148", + "scopes": [ + "Directory.ReadWrite.All", + "Group.ReadWrite.All", + "User.ReadWrite.All", + "offline_access", + "IdentityRiskEvent.Read.All", + "IdentityRiskEvent.ReadWrite.All", + "IdentityRiskyUser.Read.All", + "IdentityRiskyUser.ReadWrite.All" + ], + "redirectMode": "Global", + "redirectUrl": "https://global.consent.azure-apim.net/redirect", + "properties": { + "IsFirstParty": "False", + "AzureActiveDirectoryResourceId": "https://graph.microsoft.com/" + }, + "customParameters": { + "loginUri": { + "value": "https://login.windows.net" + }, + "tenantId": { + "value": "5b5a146c-eba8-46af-96f8-e31b50d15a3f" + }, + "resourceUri": { + "value": "https://graph.microsoft.com/" + } + } + } + }, + "token:TenantId": { + "type": "string", + "metadata": { + "sourceType": "AzureActiveDirectoryTenant" + }, + "uiDefinition": { + "constraints": { + "required": "false", + "hidden": "true" + } + } + } + }, + "iconBrandColor": "#2C75D5", + "capabilities": [], + "publisher":"Microsoft", + "stackOwner":"Microsoft" + } +} \ No newline at end of file diff --git a/custom-connectors/AzureAdIp/readme.md b/custom-connectors/AzureAdIp/readme.md new file mode 100644 index 000000000..e2ce98c15 --- /dev/null +++ b/custom-connectors/AzureAdIp/readme.md @@ -0,0 +1,14 @@ + +Identity Protection is a tool that allows organizations to discover, investigate, and remediate identity-based risks in their environment. +This connector will leverage the riskyUsers, riskDetections, and signIns APIs. + + +## Pre-requisites + +Azure AD Identity Protection is a premium feature. You need an Azure AD Premium P1 or P2 license to access the riskDetection API (note: P1 licenses receive limited risk information). The riskyUsers API is only available to Azure AD Premium P2 licenses only. + + +## API documentation + +https://docs.microsoft.com/en-us/graph/api/resources/identityprotectionroot?view=graph-rest-1.0 +