NOTE (Sept. 16, 2016): I need to update the solution file to work with VS 2015 and test the code again.<\/p>\n
A while back someone asked a question about how to use the API to add licensed users to a VSTS account and change licenses for existing users (instead of the web UI to invite and assign licenses to users<\/a>). Abhijeet, a dev on my team, gave me some code to get me started, as the identity APIs are not easy to figure out.<\/p>\n Licensing is different on VSTS than it is with Team Foundation Server. With VSTS, every user who is added to an account must have a license assigned. We need to be able to add a new user and also to change the license for an existing user. Let\u2019s take a look at how the code to do this works.<\/p>\n Shared Platform Services<\/strong><\/p>\n The first thing to notice is that the code is operating on the account that is stored in what we call Shared Platform Services (SPS). SPS is a core set of services, such as identity, account, and profile, that are used by every service in VSTS. The notion of a collection, which is a concept that was introduced in TFS 2010, doesn\u2019t exist in SPS. That\u2019s because not every service in VSTS has to have the notion of a collection. Collection is a TFS concept that is used by version control, work item tracking, etc.<\/p>\n Since we need to make a change to the account, we are going to be talking to SPS. Rather than making calls to https:\/\/MyAccount.visualstudio.com<\/a> as you are used to seeing, we are going to be calling https:\/\/MyAccount.vssps.visualstudio.com<\/a>. The \u201cvssps\u201d part of the URL takes us to SPS, and the account name in the URL gives SPS the context.<\/p>\n You can see SPS in some scenarios if you watch the address bar in your browser. For example, go to http:\/\/visualstudio.com<\/a> and sign in. Then click on your name to go to your profile page. You will see that the URL is https:\/\/app.vssps.visualstudio.com\/profile\/view?mkt=en-us<\/a> (or you can directly click that URL). In that context, you are asking SPS for your profile and the list of accounts that you have across the system. SPS is responsible for that information.<\/p>\n Once we\u2019ve connected to SPS using the same credentials that you normally use as administrator of your account, we get the client representations of the identity and account services in SPS that we\u2019ll use. The next thing we do is to determine if the user is new or an existing user.<\/p>\n Adding a New User with a License<\/strong><\/p>\n New users have to be added to the system. We call that process \u201cbind pending.\u201d What we mean by that is that we will add a reference to a user \u2013 nothing but the email address. That email address is not bound to anything. Once a user logs into VSTS with an email address that matches a bind-pending entry, we\u2019ll create a full Identity object that references the unique identifier of that user. We\u2019ll also have enter basic info for a profile (e.g., display name) and link that to the identity.<\/p>\n The Identity API calls for this operation are not at all obvious, and this is something we need to improve. I\u2019ve added a lot of comments to the code to help explain what\u2019s going on. At a high level, we first have to construct a descriptor for this bind pending identity. Each account in VSTS is either an MSA-backed account (i.e., it only uses MSAs, also known as LiveIDs) or AAD-backed (i.e., all identities reside in an Azure Active Directory tenant). We make that determination using the properties of the administrative user. Then we first have to add a new user to a group in order for the user to be part of the system \u2013 for there to be a reference to the identity. Since every user must have a license, we add the user to the licensed users group.<\/p>\n Changing the License for an Existing User<\/strong><\/p>\n This case is much simpler. If the user is already in the account, the code just makes a call to set the license with licensingClient.AssignEntitlementAsync<\/span>.<\/p>\n Notes on Licensing<\/strong><\/p>\n The names for the licenses match what you\u2019ll find in our documentation for pricing levels except AccountLicense.Express<\/span>. That\u2019s the name that the code uses for Basic (at one time it was going to be called Express, and the code didn\u2019t get updated). If you look at the AccountLicense<\/span> enum, you\u2019ll also find AccountLicense.EarlyAdopter<\/span>. That was only valid until VSTS became GA, so it can no longer be used.<\/p>\n The MSDN benefits license is different than the other licenses because it is dependent upon a user\u2019s MSDN license level. While you could explicitly set the license to a particular MSDN benefits level, you\u2019d only cause yourself problems. Setting it to MsdnLicense.Eligible<\/span> as the code does below means that the service will handle setting the user\u2019s MSDN benefits level properly upon logging in.<\/p>\n The licensing API right now uses an enum rather than a string for the licenses. The result is that AccountLicense.Stakeholder <\/span>doesn\u2019t exist in the client API prior to Update 4. You\u2019ll see in the code that I commented out Stakeholder<\/span> so that it builds with Update 3, which is the latest RTM update at the time this post is being written. In the future the API will allow for a string so that as new license types are added the API will still be able to use them.<\/p>\n There are limits for licenses based on what you have purchased. For example, if you try to add a sixth user licensed for Basic, you will get an error message. Here\u2019s how to add licenses to your VSTS account<\/a>.<\/p>\n One other thing that I\u2019ll mention is that you may have to search around for the credential dialog prompt. That dialog ends up parented to the desktop, so it\u2019s easy for it to get hidden by another window.<\/p>\n I\u2019ve attached the VS solution to this blog post, in addition to including the code in the post. I recommend downloading the solution, which will build with VS 2013 Update 3 or newer (it may work with earlier versions of 2013, but I didn\u2019t try it).<\/p>\n Enjoy!<\/p>\n