General information

The Azure DevOps connector allows us to synchronize users, groups and group memberships from the Azure DevOps environment to OpenIAM.

Installation and connection to OpenIAM

Before installing the connector, you need to make sure that your system contains at least PowerShell 5.1. If not, you need to upgrade PowerShell prior to installation.

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

General usage

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

Configuring the managed system

While configuring the managed system you should have following properties set:

• Login Id - should contain the organization name (example is given below)
• Password - should contain the token for accessing API of Azure DevOps

The organization name is the name that can be used in your organization to access the Azure DevOps endpoint. The endpoint base addresses of Azure DevOps are different, but are 'well known' and each of these addresses could be built using your unique organization name. Just as example, to make it more clear let's show an API endpoint for pulling the Azure DevOps groups:

https://vssps.dev.azure.com/{{OrganizationName}}/_apis/graph/groups

From this example it is clear that we need to have OrganizationName in each request. The connector will build each request using the login id that you provide.

To get your personal token that is required for 'Password' you need to log in to your Azure DevOps account and generate the token along with granting permissions.

Synchronization

For running synchronization you need to specify the query that you are going to use with the connector. The connector can run synchronization of users, groups and group memberships.

Because group memberships are stored inside the groups objects it is common practice to synchronize users first and groups and memberships after that to be able to match users inside the group memberships.

Synchronizing users

You can run the following query to synchronize users:

Get-oiDevOpsUsers

The request does not support parameters. You can control attributes that are returned, and you can get following attributes from the connector's response:

• originId
• origin
• displayName
• mailAddress
• principalName
• description
• domain
• directoryAlias
• metaType
• subjectKind

Sometimes it is useful to grab information only about the list of users and ignoring the rest. In this case you can specify the list of user descriptors in -Descriptors parameter. A sample query would look like:

Get-oiDevOpsUsers -Descriptors 'vssgp.Uz0xLTktMTU1MTM3NDI0NS05MTM1MjY2ODMtODE4MDAzMjY0LTIyODA4NjYzMDUtOTA3OTI2NDgxLTAtMC0wLXAtMg', 'vssgp.Zz0xLTktMTU1MTM3NDI0NS05MTM1MjY2ODMtODE4MDAzMjY0LTIyODA4NjYzMDUtOTA3OTI2NDgxLTAtMC0wLXAtMe'

Synchronizing groups

To run synchronization of groups you can run the following request:

Get-oiDevOpsGroups

The request does not support parameters. You can control attributes that are returned, and you can get the following attributes back from the connector response:

• originId
• displayName
• mailAddress
• principalName
• description
• members

Warning The Azure DevOps API does not return group membership in a single request. Therefore, to collect group memberships the connector runs additional requests per each group (if the 'members' parameter was requested). Because of this, synchronization execution may take up to several minutes depending on how many groups you have inside your environment.

Sometimes it is useful to grab information only about the list of groups while ignoring the rest. In this case you can specify the list of storage id's (objectID) in the -OriginIDs parameter. A sample query would look like:

Get-oiDevOpsGroups -OriginIDs '70d1fcf4-ebb5-4164-98e2-111111111111', '70d1fcf4-ebb5-4164-98e2-222222222222'

Filtering by projects and names. The OpenIAM connector can filter groups by projects to which they belong. Projects are calculated by principal name, which includes the project name at the beginning. It acts in the same way as the popular PowerShell module for Azure DevOps VSTeam does. For example, if the principalName of the group is '[Infrastructure]\Build Administrators', it means that the group with the displayName 'Build Administrators' belong to the 'Infrastructure' projects. The OpenIAM connector can filter results by both project names and display names. To include only some groups by project names you should use the -AllowedProjects attribute that takes an array of strings. To include only groups that have a definite displayName you should use the-AllowedDisplayNames attribute that takes an array of strings.

The query below will get all Azure DevOps groups that have the display names 'Build Administrators' or 'Project Administrators' but without regard to which project they belong. There can be a list of groups with such names but belonging to different projects.

Get-oiDevOpsGroups -AllowedDisplayNames 'Build Administrators', 'Project Administrators'

The below request returns all Azure DevOps groups that belong to TestProject.

Get-oiDevOpsGroups -AllowedProjects 'TestProject'

The below request returns only the 'Build Administrators' group from TestProject. Narrowing the search scope like this could be useful in use cases like getting group members of definite groups.

Get-oiDevOpsGroups -AllowedProjects 'TestProject' -AllowedDisplayNames 'Build Administrators'

Deleted groups. The Azure DevOps API returns all groups by default even if those groups were deleted. In most cases it is useful to get only those groups that were not deleted. To do this you should include the -ExcludeDeleted boolean parameter in your request. For example:

Get-oiDevOpsGroups -AllowedProjects 'TestProject' -ExcludeDeleted:$true

The query above gets all the groups from 'TestProject' that were not deleted.

Synchronizing users' access levels

The Azure DevOps connector can synchronize 'Access level' or license assignments for given users. Azure DevOps has a predefined set of access levels that is described in the official documentation.

To grab all available users & access level mappings you should use the 'Get-oiDevOpsUserAccessLevel' request which returns an array of objects. Each of them contains following properties:

• originId - originID of the user
• principalName - princpalName of the user
• mailAddress - email address of the user
• origin - identifies where this user comes from, for example 'aad' means that this is an Azure Active Directory user
• displayName - display name of the user
• subjectKind - 'user' means this is a user object
• licensingSource - identifies what is the source of the license. For example, 'account', 'msdn', etc.
• licenseDisplayName - the name of the license
• status - license status. For example, 'active' or 'pending'.
• assignmentSource - the source of assignment -- for example, 'groupRule'. If the source is not defined, it would be 'unknown'

To get all data about users and licensing associations you can use a request such as the one below:

Get-oiDevOpsUserAccessLevel

It is possible to narrow your search scope by specifying the list of principal names that will be looked up. For example, the request below will get data about access levels of only the following users 'user1@openiamtest.com' and 'user2@openiamtest.com':

Get-oiDevOpsUserAccessLevel -AllowedPrincipalNames 'user1@openiamtest.com','user2@openiamtest.com'

In the similar way, we can filter by originIDs. In this case the request would look as such:

Get-oiDevOpsUserAccessLevel - AllowedOriginIDs '70d1fcf4-ebb5-4164-98e2-111111111111', '70d1fcf4-ebb5-4164-98e2-222222222222'

You can filter using principal names or originIDs as needed.