====== Microsoft Graph API connector ======

This connector is developed for managing cloud services via [[https://developer.microsoft.com/en-us/graph|MS Graph API]] You can follow this project on [[https://redmine.czechidm.com/projects/ms-graph-api-connector/| Redmine]] or [[https://github.com/bcvsolutions/ms-graph-api-connector| GitHub]]

This connector is using Microsoft Graph API for communication. For more information about the API capabilities see [[https://docs.microsoft.com/en-us/graph/overview?view=graph-rest-1.0|https://docs.microsoft.com/en-us/graph/overview?view=graph-rest-1.0]]

**Supported operations for USER (Member, Guest types)**

   * GET detail of user
  * GET all users
  * CREATE new user
  * UPDATE existing user
  * DELETE user

If you creating Guest user only email and displayName can be set to the invitation. For this reason connector will perform update operation right after the invitation is send. This can end as failed operation in IdM, because update could not find the new user. Don't worry, thanks to provisioning queue and retry mechanism IdM will try to repeat the operation after some time and the update will end successfully.

**Supported operations for LICENCE **

  * ASSIGN new licence to user
  * REMOVE licence from user

Assigning/removing of licence is done via UUID. If you need to know the UUID of specific licence, see [[https://docs.microsoft.com/en-us/azure/active-directory/enterprise-users/licensing-service-plan-reference|https://docs.microsoft.com/en-us/azure/active-directory/enterprise-users/licensing-service-plan-reference]] other option is to display licence detail in Azure portal and you will see UUID in the URL bar in the end.

**Supported operations for AD GROUP, AZURE ROLE**

  * GET detail of group/role
  * GET all groups/roles
  * ASSIGN group/role to user
  * REMOVE group/role to user

Assigning/removing of groups/roles is done via UUID. UUID is used as indetifier in conenctor, so you will get this info during synchronization.

**Permissions**  All permission are assigned to the Application(See Configuration section below for more info about App). This permissions are tested, but if you want only to read data from AAD for example, you should be good to go only with read permissions. For complete info about permissions check official API documentation, where each endpoind has section with required permissions.

  * Managing basic users attributes and CRUD - Directory.ReadWrite.All and User.ReadWrite.All
  * If you want to be able to change password to users via connector you need to assign role "Password administrator" to app.
  * Manage AD group membership GroupMember.ReadWrite.All and for Azure roles RoleManagement.ReadWrite.Directory
  * Manage groups Group.ReadWrite.All

**Configuration **  If you change some configuration you need to perform Test operation so the new config will load into connector and new grapClient instance is created.

  * Client ID - UUID of application which you need to create in Azure portal. See [[https://docs.microsoft.com/en-us/graph/auth-register-app-v2?view=graph-rest-1.0|https://docs.microsoft.com/en-us/graph/auth-register-app-v2?view=graph-rest-1.0]] Created app need these permission Directory.ReadWrite.All and User.ReadWrite.All If you want to be able to change password via connector you need to assign role "Password administrator" to app.
  * Scopes - Use this value: [[https://graph.microsoft.com/.default|https://graph.microsoft.com/.default]]
  * Client secret - On app detail in Azure portal, tab "Certificates & secrets" create new secret.

If you want secret with longer expiration then 2 years use this powershell.
<code>

$startDate = Get-Date
$endDate = $startDate.AddYears(10)
$Credential = Get-Credential
Connect-AzureAD -Credential $Credential
$aadAppsecret01 = New-AzureADApplicationPasswordCredential -ObjectId "Object ID na overwiew apliakce" -CustomKeyIdentifier "idm-key" -StartDate $startDate -EndDate $endDate
Write-Host $aadAppsecret01

</code>

You will see something like this in console. Use the value from field "Value:"

<code>
class PasswordCredential {
  CustomKeyIdentifier: System.Byte[]
  EndDate: 06.05.2031 7:38:47
  KeyId:
  StartDate: 06.05.2021 7:38:47
  Value: VALUE OF YOUR SECRET KEY
}

</code>

  * Tenant - Tenant UUID
  * National cloud - In which cloud is you tenant located (Global, China, Germany, UsGovernment)
  * Disable password change after login - User will be forced to change his password again after he logged in to cloud when he just changed password from IdM. Use this option to disable the forced change.
  * Proxy port - If you want to use some proxy set the port otherwise leave the default value (0) and proxy will be ignored
  * Proxy hostname - Proxy hostname
  * Proxy username - Proxy username - fill this if your proxy need authentication
  * Proxy password - Proxy password - fill this if your proxy need authentication
  * Get Azure roles - Default is false. You can enable support for Azure roles. So you can synchronize AD roles together with Azure roles
  * Type of user which should be managed - Default value is empty = Member AND Guest types are managed. If you want to manage only one type use Member or Guest value. This config has effect only for "get all" operation (synchronization)
  * Send invitation email for Guest via Azure - Default is false. If you want to send invitation email to Guest via Azure, use this option
  * Redirect URL after accepting invitation - If you are managing Guest users, fill this with some URL to which the user will be redirected, after he accept the invitation.

**Schema **  Connector will generate default schema for object class __ACCOUNT__ Currently we are supporting "basic" (String, Integer, Boolean) attributes such as firstname, lastname, … Other supported attributes are password object and licence object

Connector will generate default schema for object class __GROUP__ Currently we are supporting "basic" (String, Integer, Boolean) attributes such as displayName, … Other supported attributes are members, memberOf, owners

===== Some notes: =====

  * Identifier in IdM is UPN which need to be in format somemeail_domain.com#EXT#@bcvcz.onmicrosoft.com
  * Attribute mail must be send, because value from this attributes is used to sending the invite
  * Guest is created only with email and display name other attributes are not used. Can be updated later e.g firstname, lastname