Note: Microsoft recommends using PSGraph module for Azure, as described in the documentat by this link.

General information

Azure connector allows OpenIAM to manage objects inside Azure AD - users, groups, memberships, licenses assignment.

Microsoft Azure provides various services in cloud that are analogue to on-premise ones. If you need to manage identities of some particular service - please refer to appropriate connector. For example, for managing Exchange mailboxes either on-premise or online you have to use Exchange connector.

Service account information:

Azure AD connector can work using 2 types of authentication:

• Username/password authentication
• Service principal authentication

Service account or a service principal that you use should have rights to create users in Azure, modify their properties and perform any actions that you would like connector to do.

To use username/password authentication you just need to specify username and password of the service account on the managed systam configuration page. No additional actions required.

If you would like to use service principal authentication you would need to do create a service principal first. The process of creating is described in Microsoft documentation here: https://docs.microsoft.com/en-us/powershell/azure/active-directory/signing-in-service-principal?view=azureadps-2.0

After having created a service principal you would have a certificate that should be installed on the connector machine. Depending on the service account of the system service (service run as), the certificate could be installed either in user storage or a machine one (if connector runes using Local System, which is by default).

Now you can proceed with Managed system credentials configuration on the OpenIAM side. You should use service principal's ObjectID as Username and certificate thumbprint as Password. Additionally, authentication using service principals requires knowing TenantID. You should create 'TenantID' parameter in your ManagedSystem configuration (not the Policy map) and set it to ID of your tenan, where you've created service principal.

Requirements

• .NET 4.7.2 or above
• PowerShell PowerShell 5.1 For Windows 8.1, Windows 8, Windows 7 Service Pack 1 (SP1), Windows Server 2012 R2, Windows Server 2012, and Windows Server 2008 R2 SP1, download and install the Windows Management Framework 5.1.

In addition to general connector requirements described in "PowerShell connector usage" document Azure connector relies on following modules:

• AzureAD

To verify if you have AzureAD module installed, please start PowerShell console (please make sure that you are running x64 console) and run following command:

Import-Module AzureAD

If you do not see any errors and you receive empty output - you already have AzureAD module installed and you can proceed. However, if this module is not installed, you would see errors, indicating that you need to install this module by running (using x64 PowerShell console):

Install-Module AzureAD

You will need to agree on the installation by pressing 'Y' as a confirmation.

Note. If installation using command above causes errors, most probably you are not using TLS 1.2. Microsoft enforced it to be default protocol for downloading NuGet packages, however, it does not go by default in some of PowerShell sessions. To switch to TLS 1.2 you should run first:

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12

Installation and connection to OpenIAM

All PowerShell connectors are installed in the same way, which is described in the document: PowerShell connector installation

General usage

All PowerShell connectors are used in the same way, which is described in the document: PowerShell connector usage

Define attribute provisioning rules

Azure AD PowerShell connector supports working with following identities:

• Users
• Groups (non-mail enabled ones, which is Azure PowersHell module limitation. If you would like to work with that kind of groups - you should use Azure/O365 OpenIAM connector of the previous version)

User provisioning

Principal - UserPrincipalName

You can specify following attributes inside the policy map.

Working with license parameters

Connector is capable of setting any subset of licenses inside the global plan. For example:

Connector can assign whole license pack (like E1, E3 etc.) and also supports partial licensing (for example, assigning E1 with some features disabled).

Handling license assignment - OpenIAM sends licenses information in 'Licenses'. This is multi-value attribute (like Groups), so one user could be assigned multiple licenses. License record format:

{"LicenseSku":"O365_BUSINESS_PREMIUM","DisabledFeatures":"YAMMER_ENTERPRISE,MYANALYTICS_P2,BPOS_S_TODO_1"}

In example above we will assign user O365_BUSINESS_PREMIUM license, however, YAMMER_ENTERPRISE, MYANALYTICS_P2 and BPOS_S_TODO_1 services would be disabled for this user.

To get LicenseSku, you can run following command

Connect-AzureAD
Get-AzureADSubscribedSku

Additional information about LicenseSku could be found here: https://docs.microsoft.com/ru-ru/azure/active-directory/enterprise-users/licensing-service-plan-reference

Synchronization

Working with reconcilation and synchronization is describeed in a separate document. In addition to specifying appropriate groovy scripts for transformation/validation rules, you should also set search string that should be set at 'SQL Query / Directory Filter' parameter of your sycnhroniztion page (Webconsole -> Top menu 'Provisioning' -> Synchronization -> Edit your synchronization profile). That string is actual request that will be executed by connector to find/filter users or groups from Azure.

Users synchronization

For running Azure users synchronization you can use variations of Get-MSOLUser query. Some usage examples are below.

This query gets all users with all properties that are availavble.

Get-AzureADUser -All:$true | Select-Object *

Below query selects all data about one particular user by sign in name, let's call this user 'someUser@openiam.com'. You can use either UPN or ObjectID format here - both would work:

Get-AzureADUser -ObjectID 'someUser@openiam.com' | Select-Object *

Below query gets one first user (usually useful for tests):

Get-AzureADUser | Select-Object -First 1

Sometimes you may neeed to get information about several users. In example below we get data about users whose UPNs start with 'a':

Get-AzureADUser -Filter "startswith(UserPrincipalName,'a')" | Select-Object *

Below are typical properties that you can get using queries like above - when you specify | Select-Object * :

• ObjectId
• ObjectType
• AccountEnabled
• AgeGroup
• City
• CompanyName
• ConsentProvidedForMinor
• Country * Department
• DirSyncEnabled
• DisplayName
• FacsimileTelephoneNumber
• GivenName
• IsCompromised
• ImmutableId
• JobTitle
• LastDirSyncTime
• LegalAgeGroupClassification
• Mail
• MailNickName
• Mobile
• OnPremisesSecurityIdentifier
• OtherMails
• PhysicalDeliveryOfficeName
• PostalCode
• PreferredLanguage
• ProvisioningErrors
• ProxyAddresses
• RefreshTokensValidFromDateTime
• ShowInAddressList
• SignInNames
• SipProxyAddress
• State
• StreetAddress
• Surname
• TelephoneNumber
• UsageLocation
• UserPrincipalName
• UserState
• UserStateChangedOn
• UserType

If you don't specify | Select-Object * in your query, you will be able to get basic properties like:

• ObjectId
• DisplayName
• UserPrincipalName
• UserType

Sometimes it is useful to get the list of groups, which current user is a member of. This is possible to do within user synchronization request. To do this you should add 'MemberOf' attribute to 'Lookup Attribute Names' parameter of your synchronization configuration on OpenIAM side. MemberOf is not returned by default using Get-MSOLUser command. Also, it relies on additional module - Azure AD. So, adding 'MemberOf' attribute to 'Lookup Attribute Names' will result +1 request for each of found user. If you have a lot of users in your Azure AD it may have notable impact on sync speed, so, please make sure that you request 'MemberOf' only in case when you really need this.

Groups synchronization

For running Azure groups synchronization you can use variations of Get-MSOLGroup query. Some usage examples are below.

This query gets all groups with all properties that are availavble.

Get-AzureADGroup -All:$true | Select-Object *

Below query selects all data about one particular group by group name:

Get-AzureADGroup -SearchString 'group_name' | Select-Object *

Below query selects one random group (usually useful for tests):

Get-AzureADGroup | Select-Object -First 1

Below are typical properties that you can get using queries like above - when you specify | Select-Object * :

• ObjectId
• ObjectType
• Description
• DirSyncEnabled
• DisplayName
• LastDirSyncTime
• Mail
• MailEnabled
• MailNickName
• OnPremisesSecurityIdentifier
• ProxyAddresses
• SecurityEnabled
• *Membership (detailed explanation is given below)

If you don't specify | Select-Object * in your query, you will be able to get basic properties like:

• ObjectId
• DisplayName
• Description

Sometimes it is useful to get the list of members of synced group(s). This is possible to do within group synchronization request. To do this you should add 'Membership' attribute to 'Lookup Attribute Names' parameter of your synchronization configuration on OpenIAM side. Membership is not returned by default using Get-MSOLGroup command. So, if you include this attribute - it would result +1 request for each of found groups. If you have a lot of groups in your Azure AD it may have notable impact on sync speed, so, please make sure that you request 'Membership' only in case when you really need this.

Service principals synchronization

For running Azure service principals synchronization you can use variations of Get-AzureADServicePrincipal query. Some usage examples are below.

This query gets all service principals with all properties that are availavble.

 Get-AzureADServicePrincipal -All:$true | Select-Object *

Below query selects all data about one particular service principal selecting by ObjectId:

  Get-AzureADServicePrincipal -ObjectId 'ba8078c7-e75d-40df-b10b-53c01cf18846' | Select-Object * 

Below query selects all data about one random first service principal:

 Get-AzureADServicePrincipal -All:$true | Select-Object * -First 1 

Below are typical properties that you can get using queries like above - when you specify | Select-Object * :

• ObjectId
• ObjectType
• DisplayName
• AccountEnabled
• ServicePrincipalType
• AppDisplayName
• AppId
• AppOwnerTenantId
• AppRoleAssignmentRequired
• Homepage
• PublisherName

If you don't specify | Select-Object * in your query, you will be able to get basic properties like:

• ObjectID
• AppID
• DisplayName

Azure permissions synchronization

For running Azure permissions synchronization you can use Get-oiAzurePermissionAssignments request. It supports single parameter: SubscriptionIDs where you can set the list of subscriptions separated by comma. Examples are given below.

This query gets all permissions within given 2 subscriptions.

Get-oiAzurePermissionAssignments -SubscriptionIDs '11111111-fb94-4db4-93f3-ae4defd93cb9', '22222222-fb94-4db4-93f3-ae4defd93cb9'

Below query gets a single subscription record from specified subscription. This could be used for testing.

Get-oiAzurePermissionAssignments -SubscriptionIDs '11111111-fb94-4db4-93f3-ae4defd93cb9' | Select-Object -First 1

Get-oiAzurePermissionAssignments can grab following properties for each permission assignment:

• RoleAssignmentId
• Scope
• DisplayName
• SignInName
• RoleDefinitionName
• RoleDefinitionId
• ObjectId
• ObjectType
• CanDelegate
• Description
• ConditionVersion
• Condition

Azure resources report usage

Azure connector can generate reports about Azure resources usage inside given Resource group, Subscription or tenant. To be able to generate such report service account should possess, at least, 'Reader' role on a given level.

Assuming that Azure services catalog is huge, and connector is just a default template, it supports reporting the limited set of resources out of the box. However, it is possible to extend it without issues by customizing default connector.

Out of the box connector can generate report about usage of following resources:

• Microsoft.Compute/disks
• Microsoft.Network/networkInterfaces
• Microsoft.Network/networkSecurityGroups
• Microsoft.Network/networkWatchers
• Microsoft.Network/publicIPAddresses
• Microsoft.RecoveryServices/vaults
• Microsoft.Storage/storageAccounts
• Microsoft.Sql/servers/databases Microsoft.Sql/servers*
• Microsoft.Network/virtualNetworks
• Microsoft.Compute/virtualMachines
• Microsoft.Web/sites
• Microsoft.Logic/workflows

To pull Azure resource usage report you can use synchronization queries in a PowerShell style that look like using 'Get-oiAzureAccessReport' cmdlet. It support following parameters:

• PrincipalProperty - specifies principal property of assignees objects that will be returned. Allowed values: 'SignInName' an 'ObjectID'. Cannot be used with -SignInNames or -ObjectIDs as those parameters belong to different parameter set. Is used when you query all assignees, without limiting your search for given set of sign in names or object ids.
• ObjectIDs - limits the search scope to given ObjectIDs. It is possible to specify several values as multiple strings separated by comma. Cannot be used togetherwith PrincipalProperty argument
• SignInNames - limits the search scope to given SignInNames, exactly how above paremter does.
• Scope - either 'Tenant' or 'Subscription'. Specifies the level of extraction. If you have Reader access on lower level, for example single Resource group of one of subscriptions - you need to specify Subscription level and your search will be limited only to objects that you are allowed to access within your subscription.
• ScopeID - identifier of your Subscription or Tenant - depending on what you use in parameter above
• AllowedAttributes - optional parameter that allows you to limit your report to given resource types. Should be one of supported resources list that were mentioned above.

Below are some practical examples of queries:

Get-oiAzureAccessReport -PrincipalProperty 'SignInName' -Scope 'Tenant' -ScopeID '90b27a81-12e5-499d-b7b8-b23274b10331'

Above query gets reports for all resources available at Tenant 90b27a81-12e5-499d-b7b8-b23274b10331 selecting SignInName as primary property.

Get-oiAzureAccessReport -SignInNames 'user1@openiam.com','user2@openiam.com' -Scope 'Tenant' -ScopeID '90b27a81-12e5-499d-b7b8-b23274b10331'

Above query gets reports for all resources available for user1@openiam.com and user2@openiam.com at Tenant 90b27a81-12e5-499d-b7b8-b23274b10331.

Get-oiAzureAccessReport -ObjectIDs 'c4b14ca1-82ae-4ba1-81d9-375da19bad51', '2094b9f1-878c-4c38-9972-a2b2a9f62d31' -Scope 'Tenant' -ScopeID '90b27a81-12e5-499d-b7b8-b23274b10331'

Above query gets reports for all resources available for objects with Id c4b14ca1-82ae-4ba1-81d9-375da19bad51 and 2094b9f1-878c-4c38-9972-a2b2a9f62d31 at Tenant 90b27a81-12e5-499d-b7b8-b23274b10331.

Get-oiAzureAccessReport -PrincipalProperty 'SignInName' -Scope 'Subscription' -ScopeID '90b27a81-12e5-499d-b7b8-b23274b10331'

Gets all resources usage report for all users inside available resources of Subsctiption 90b27a81-12e5-499d-b7b8-b23274b10331. The primary property will be a SignInName.

Get-oiAzureAccessReport -PrincipalProperty 'SignInName' -Scope 'Subscription' -ScopeID '90b27a81-12e5-499d-b7b8-b23274b1033b' -AllowedAttributes 'Microsoft.Network/networkSecurityGroups','Microsoft.Compute/virtualMachines'

The same as query above, but report scope is limiteed to virtual machines and network security groups only.

Result of this request will be the set of identities identified by ObjectID or SignInName. Each of those identities will have the set of resources by each type (described above). Each of resources will have JSON payload that describes what permissions does this identity have. For example, identity A has some permissions to 3 virtual machines. So 'Microsoft.Compute/disks' attribute will contain 3 permissions sets for each of those VMs and each would contain following properties:

• ResourceName - Name of resource to which this permission was granted. In our case it will be the name of current VM
• ResourceGroupName - Name of Azure resource group that contains current VM
• ResourceId - ID of current VM
• ResourceType - type of resource. In our case - 'Microsoft.Compute/disks'
• SubscriptionId - ID of subscription that contains current VM
• RoleDefinitionId - ID of role definition below
• RoleDefinitionName - Name of role (like 'Reader', 'Owner' etc.)
• AssigneeType - Type of identity that has this permission. For example, User or ServicePrincipal
• AssigneeDisplayName - Display name of identity that was given permission for current object
• AssigneeSignInName - if this assignee has a sign in name (like user) - it will contain it. Otherwise it will be empty (like for service principals)
• AssigneeObjectId - ObjectID of identity that has this permission.
• AssigneeCanDelegate - true or false, indicates if assignee can delegate permission to some other identities
• RoleAssignmentId - Identifier of current role assignment

Connector Troubleshooting and Tips

Connector troubleshooting is covered in the document that describes all .NET/PowerShell connector usage. Troubleshooting steps are the same for all connectors of this type. Following information is sprcific for this connector.