Azure DevOps connector

General information

Azure DevOps connector allows to synchronize users, groups and group memberships from Azure DevOps environment to OpenIAM. Dynamics365 connector is open sourced and is shipped with basic functionality that could be extended according to your needs.

Installation and connection to OpenIAM

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

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

Configuring managed system

While configuring managed system you should have following properties set:

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

Organization name is the name that can be used in your organization to access Azure DevOps endpoint. Endpoint base addresses of Azure DevOps are different, but all 'well known' and each of this address could be built using your unique organization name. Just as example, to make it more clear let's show API endpoint for pulling 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. And connector will build each request using 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 token along with granting permissions.

Generating access token

Synchronization

For running synchronization you need to specify query that you are going to run towards connector. Connector can run synchronization of users, groups and group memberships.

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

Synchronizing users

You can run following query to synchronize users:

Get-oiDevOpsUsers

Request does not support parameters. You can control attributes that are returned - you can get following attributes back from connector response:

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

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

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

Synchronizing groups

To run synchronization of groups you can run following request:

Get-oiDevOpsGroups

Request does not support parameters. You can control attributes that are returned - you can get following attributes back from connector response:

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

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

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

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

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

Most common examples are given below. Query below will get all Azure DevOps groups that have display names either 'Build Administrators' or 'Project Administrators' but regardless to which project they belong. So,s there can be the list of groups with such names, but belonging to different projects.

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

Below request returns all Azure DevOps groups that belong to TestProject.

Get-oiDevOpsGroups -AllowedProjects 'TestProject'

Below request returns only 'Build Administrators' group from TestProject. Narrowing 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. 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 -ExcludeDeleted boolean parameter to your request. For example:

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

Query above gets all groups from 'TestProject' that were not deleted.

Synchronizing users access levels

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

To grab all available users & access levels mappings you should use 'Get-oiDevOpsUserAccessLevel' request, which returns 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 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'
  • licenseDisplayName - the name of the license
  • status - license status, for example 'active', 'pending'
  • assignmentSource - the source of assignment, for example 'groupRule'. If source is not defiled - 'unknown'

To get all data about users and licensing association you can use request like 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, below request will try to get data about access levels of only following users 'user1@openiamtest.com' and 'user2@openiamtest.com':

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

In the similar way like we can filter by principalNames we can do filtering by originIDs. In this case request would look like below:

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

You can filter both using principal names or originIDs if you need to.