First published on MSDN on Jan 31, 2017
Most Microsoft-oriented techies have probably been exposed to Azure by now, and seen the breadth of services on offer. If you've landed on this blog you have probably gone through the basics of getting a piece of code running in the cloud already. (If not - what are you waiting for?) Furthermore, regardless of whether you use App Services, Service Fabric, Docker Containers or what not, there are certain odds that identity is something your application needs to care about one way or the other.
Yes, the admin persona is getting a lot of focus, and yes, many features make the most sense for such a role. But I certainly wouldn't say the developer is entirely out of the picture. When working with regular Active Directory as a developer the interface for dealing with the data is often based on LDAP, and in general that isn't all that fun to use in my opinion. (Not to mention a protocol not designed to work across the Internet.) Ever tried making Kerberos work outside your own little network segment? The fact that Azure AD presents a nice RESTful API for the data, and OAuth for "getting to know you" should be enough by itself to make you take a second look. But I get ahead of myself - let's take a step back.
Why should I, as a developer, care about AAD? Well, not many solutions other than fairly plain websites work without a user database or some set of an identity concept. And what have we all learned in school about identity management? Never build it yourself. (Unless you happen to be really good at it of course. And happen to be Microsoft, or Google, or a similar outfit. And happen to be prepared for the experience of you coming up with a working solution, that is rejected by some security architect, requiring you to rewrite the whole thing.)
I'm not saying it's not doable to create a simple user database where you hash the passwords, but while that works for a basic website, what if you need to have a client authenticating itself and requesting data from a back-end API? Not to mention that you suddenly need multi-factor authentication for higher valued data. Ever tried implementing that using text messages, and having to troubleshoot why one specific operator, in a different country than your own, isn't routing the message to the receiving phone? Oh, using push notifications instead to get around this you say? Ever had a customer where the necessary ports for push weren't opened on the corporate Wi-Fi?
Point being - even if you are a great developer you will end up spending a lot of effort on things that aren't making your app any more magic. And if it isn't magic, it isn't going to sell.
Which is why a solution that deals with all of this for you is quite compelling. I'm not saying Azure AD will solve every identity problem you have, or that you don't have to learn any protocols or identity concepts on a detailed level. And there's still parts of the identity puzzle where you might have to either employ third-party solutions or roll your own. It does take away a lot of the hassle involved though, and it provides a good feature set for the price.
"Yeah, yeah, I know all this already. Why are you bothering me with this newbie stuff?" I'm trying to be ambitious here, (possibly over-ambitious), by targeting both AAD newcomers, and the more seasoned crowd. Maybe you know all of this already, and are way ahead of me, but I am hoping to provide at least some value for everyone. Just skip the pieces not needed, and feel free to chime in with corrections or suggestions if you have any. I suffixed the title with a part number because I see this as a multi-part "experience".
So, where to start? Surely Microsoft has come up with some documentation right?
Azure Active Directory developer's guide is a good starting point:
https://aka.ms/aaddev
Now, I'm not going to try to bring your spirit down, but from this point on to full production usage of AAD there might be a bump or two in the road that you're not aware of yet. Like so many other developer snags they have a tendency to show up when you least expect them. I don't have all the answers to these bumps, but I have hit a few challenges myself, so I'll try and highlight some of them. And at least try to delve into some of the specifics. In some areas I can probably only provide a starting point; let's see how it turns out as we go along.
This isn't going to be a re-hash of a "Getting Started with Azure AD"- guide. If you haven't attempted logging into an app of yours before using AAD credentials I'm not going to show you that here. (Don't worry; I have code samples I can point to for demonstrating specific tasks.) But whether you have done this before or not I believe you should still finish this post before moving on to better things :)
One of the first things you need to do before using AAD in an app is to register an entry in your Azure AD tenant. Unfortunately this is also one of those things that can trip you up before you're even out of the gate. You see, there's more than one way to skin this cat. We'll leave out the programmatic approaches of creating an app, because most people don't start there, and find it more natural to click through the UI to perform the task. There are however three main places where you can register apps, and to make matters more complicated, where you register it is not irrelevant. (Technically speaking there are also the wizards in Visual Studio, but personally I tend to stick to the portals.)
Old Azure Portal
If you go to https://manage.windowsazure.com you will find the legacy portal, which coincidentally has Azure AD as one of its hold-outs. It is probably the go-to place in most cases still though.
New Azure Portal
Heading over to https://portal.azure.com is the more snazzy-looking, (and confusing depending on who you ask), portal for registering apps. This will be the place to go going forward, but it does not do things in the same way as the old one.
Apps Portal
Coming in from the sideline we have https://apps.dev.microsoft.com which is yet another place to register your app. The main difference between this option and the two other ones is that this doesn't require you to have an AAD tenant, or Azure subscription. You can for instance login with a Microsoft account, (formerly LiveId, Hotmail, something), and leverage both corporate and personal accounts for login.
So which one should you use?
If you want to go the "it just works" route, and you want to go live as quickly as you can the old portal is the tried and tested approach.
If you have a more relaxed time line, want to experiment, and can live with the occasional UI snag go with the new one. Note that AAD management in the new portal is at the writing of this in preview, so it's basically acknowledged that there might be bugs.
The dedicated apps portal…so far mainly for very specific use cases where you need both AAD and MSFT accounts. For doing social authentication (like MSFT account) I would generally lean towards Azure AD B2C instead. More on that topic later.
There are instances where you don't have a choice as to which one to use. If you have an Office 365 subscription provided through a CSP, as opposed to buying directly from Microsoft, you can only use the new portal. (You should add an Azure subscription.) And if you are not the service/global admin your access role could be setup so you don't have access where you expected to. These are issues you might need to address internally in your organization.
So, what are the differences then?
Naming
In the old portal you add a new app , in the new one you register a new app if you develop it yourself, but add third-party apps. Not a big thing, but it's easy to get your terminology mixed up with minor things like this. And when communicating with other people it's kind of useful to be on the same page as to what one is doing.
Different Wizards
Ok, no-one expected the wizards to be identical between two distinctly different portals. But for instance in the old one you always start by clicking "Add", and then branch into either first-party, third-party or on-prem. In the new you start on the AAD blade, and either go to Enterprise applications or App registrations . Which may or may not make sense. (In my opinion an "Enterprise App" could be both something someone else made, and something you make in-house.)
Configuration options
The UI might not expose all the same settings. Take the very basic task of adding a new client secret/key. In the new portal you get to type in a description, (which is hugely useful if you handle multiple keys), but in the old one you don't get this luxury.
[caption id="attachment_3035" align="alignnone" width="824"]
Client Secret in old portal[/caption]
[caption id="attachment_3025" align="alignnone" width="836"]
Client Secret in new portal.[/caption]
In the apps portal they call it Application Secrets . No description here either, but you do get to see the first characters to give you a hint.
[caption id="attachment_3015" align="alignnone" width="430"]
Client Secret in Apps portal.[/caption]
As long as you stick to one portal and do all your configuration there you should have no worries. Things shouldn't automatically break if you switch portals along the way, but you can see how things might be confusing to keep track of.
Behind the scenes
Ah, this is where the plot thickens. We can get over things having different names in different places. It's when the things you don't see, does things you don't know about, it can quickly lead to "why is this not working?". For instance I have a curious issue with a test app I created only being visible in the old and the apps portal, and not in the new one. Why? I don't know, (granted I didn't research it in detail because it didn't matter), but certainly it indicates something weird going on.
Application vs servicePrincipal
We need to take a short detour here and get into what an "app" actually is in the AAD database. Every object in AAD has an objectId (in the form of a guid). For a user object the attribute you care about is something like the UPN , but you still need it to be a unique object, which is why you often deal with its objectId when working on the object. For an app there are plenty of attributes, but when you publish an app it is the appId you care about. This looks similar to the objectId , but it's not the same. Every app you publish will have an appId in the AAD tenant you registerered it.
[caption id="attachment_3045" align="alignnone" width="517"]
An
application
Object.[/caption]
You would think that having this appId means that it's all ready to go, but not so fast. If I park a nice car in front of your house it's not going to do you much good just standing there. Even if it is in plain sight you need the keys to the car to actually drive it. Not a perfect analogy, I'll give you that, but you need something to drive the app as well. In the case of AAD this would be a servicePrincipal .
The servicePrincipal has its own id (because it is a separate object), but will include a reference to an appId .
[caption id="attachment_3055" align="alignnone" width="542"]
A
servicePrincipal
object[/caption]
Much like the Highlander there can be only one appId , but there can be multiple servicePrincipals . (You should get used to bad jokes and references.) If you publish a SaaS app that will be used by a number of customers, their AAD tenants will not have an app object; they will have a servicePrincipal object referring to your appId . If your app is not enabled for other tenants, they will not be able to add it to their tenant. (In the screenshot above this can be seen as the availableToOtherOrganizations attribute.)
This all ties in to the Consent Framework which we will get back to later, since it's a topic that warrants a little more than a paragraph to explain.
Makes sense right? So how does this apply to the portals? Thing is that it's not just your customers who need that reference object. You need it too. When you test the app you are developing, in your AAD tenant, with a user from the same tenant, you still need this to exist. And if you registered your app in the new portal this will be an issue. The old portal creates a servicePrincipal for you, the new one does not. Luckily there is an easy way to fix this, but if you're not aware of it I can sympathize with the ensuing troubleshooting headaches:
http://www.cloudidentity.com/blog/2016/10/04/provision-an-app-created-on-portal-azure-com-in-your-own-tenant/
Authorization endpoints
Another not so transparent thing is what happens when using the apps portal versus the other two portals. The apps portal registers the app with the AAD v2 endpoint. If you're using the helper libraries in your app this isn't necessarily something you notice since it's all being abstracted away from you. But if you are very specific as to which protocols you use for acquiring tokens, (AAD supports a number of them), this might be relevant as v2 is all about OAuth and Open ID Connect.
For a reference - Should I use the v2.0 endpoint? :
https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-v2-limitations
We will get back to this when we start churning out some demo code. As for this being a dev blog post without code, what's up with that? It makes me feel queasy too, but that's just the way it had to work out since (surprisingly) not all challenges are best illustrated through code :)
Wrapping up these introductory tips
And then there is getting the permissions right, getting the aforementioned consent, etc. If you are unsure of what is happening in the background be ready for going straight to the source in the form of GraphExplorer , or doing REST calls manually. Yes, those things are on my list for future topics already :)
I'll proceed with banging on the keyboard to work on the next part in this series, but I have a tip for something you can do while waiting. If you (like me) believe Azure AD is the best thing since sliced bread - buy Vittorio's book:
https://www.amazon.com/Authentication-Directory-Applications-Developer-Reference/dp/0735696942
He knows more about Azure AD than I ever will, and odds are you'll learn a thing or twenty if you take the time to read through the book. (Don't worry, it's not as scary as it sounds, and it reads mostly easily.) Since it focuses on Web-based applications it doesn't cover everything you can do with AAD, but it takes you a long way. It's unfortunately not a free resource, but it's so good I had to include it anyways.
Requests for more things AAD to cover? Useful so far? Let me know in the comments below, and I'll see you soon for more.
Authored by Andreas Helland
Preamble
Most Microsoft-oriented techies have probably been exposed to Azure by now, and seen the breadth of services on offer. If you've landed on this blog you have probably gone through the basics of getting a piece of code running in the cloud already. (If not - what are you waiting for?) Furthermore, regardless of whether you use App Services, Service Fabric, Docker Containers or what not, there are certain odds that identity is something your application needs to care about one way or the other.
Enter Azure Active Directory (AAD). Why should I care about Azure Active Directory (AAD) as a developer? Isn't it basically a clouded version of an on-premises Active Directory (AD)? Which is usually more of an admin thing than something for developers. I hear you, but it's not that simple.
Yes, the admin persona is getting a lot of focus, and yes, many features make the most sense for such a role. But I certainly wouldn't say the developer is entirely out of the picture. When working with regular Active Directory as a developer the interface for dealing with the data is often based on LDAP, and in general that isn't all that fun to use in my opinion. (Not to mention a protocol not designed to work across the Internet.) Ever tried making Kerberos work outside your own little network segment? The fact that Azure AD presents a nice RESTful API for the data, and OAuth for "getting to know you" should be enough by itself to make you take a second look. But I get ahead of myself - let's take a step back.
Why should I, as a developer, care about AAD? Well, not many solutions other than fairly plain websites work without a user database or some set of an identity concept. And what have we all learned in school about identity management? Never build it yourself. (Unless you happen to be really good at it of course. And happen to be Microsoft, or Google, or a similar outfit. And happen to be prepared for the experience of you coming up with a working solution, that is rejected by some security architect, requiring you to rewrite the whole thing.)
I'm not saying it's not doable to create a simple user database where you hash the passwords, but while that works for a basic website, what if you need to have a client authenticating itself and requesting data from a back-end API? Not to mention that you suddenly need multi-factor authentication for higher valued data. Ever tried implementing that using text messages, and having to troubleshoot why one specific operator, in a different country than your own, isn't routing the message to the receiving phone? Oh, using push notifications instead to get around this you say? Ever had a customer where the necessary ports for push weren't opened on the corporate Wi-Fi?
Point being - even if you are a great developer you will end up spending a lot of effort on things that aren't making your app any more magic. And if it isn't magic, it isn't going to sell.
Which is why a solution that deals with all of this for you is quite compelling. I'm not saying Azure AD will solve every identity problem you have, or that you don't have to learn any protocols or identity concepts on a detailed level. And there's still parts of the identity puzzle where you might have to either employ third-party solutions or roll your own. It does take away a lot of the hassle involved though, and it provides a good feature set for the price.
"Yeah, yeah, I know all this already. Why are you bothering me with this newbie stuff?" I'm trying to be ambitious here, (possibly over-ambitious), by targeting both AAD newcomers, and the more seasoned crowd. Maybe you know all of this already, and are way ahead of me, but I am hoping to provide at least some value for everyone. Just skip the pieces not needed, and feel free to chime in with corrections or suggestions if you have any. I suffixed the title with a part number because I see this as a multi-part "experience".
So, where to start? Surely Microsoft has come up with some documentation right?
Azure Active Directory developer's guide is a good starting point:
https://aka.ms/aaddev
You can skim through the intro parts, and quickly get a feel for things. Afterwards, you can read more of the manuals or just dive straight into the samples. "Hey, there's an MVC web app. Let's pull down the repo, build and hit F5 in Visual Studio… It works! Great!"
If you haven't done the exercise before I encourage you to do this, because even if you don't understand all the code after the first five minutes it will hopefully give you a good feeling of accomplishment to propel yourself onwards.
Now, I'm not going to try to bring your spirit down, but from this point on to full production usage of AAD there might be a bump or two in the road that you're not aware of yet. Like so many other developer snags they have a tendency to show up when you least expect them. I don't have all the answers to these bumps, but I have hit a few challenges myself, so I'll try and highlight some of them. And at least try to delve into some of the specifics. In some areas I can probably only provide a starting point; let's see how it turns out as we go along.
This isn't going to be a re-hash of a "Getting Started with Azure AD"- guide. If you haven't attempted logging into an app of yours before using AAD credentials I'm not going to show you that here. (Don't worry; I have code samples I can point to for demonstrating specific tasks.) But whether you have done this before or not I believe you should still finish this post before moving on to better things :)
Azure Portals and Acquiring ids for your Apps
One of the first things you need to do before using AAD in an app is to register an entry in your Azure AD tenant. Unfortunately this is also one of those things that can trip you up before you're even out of the gate. You see, there's more than one way to skin this cat. We'll leave out the programmatic approaches of creating an app, because most people don't start there, and find it more natural to click through the UI to perform the task. There are however three main places where you can register apps, and to make matters more complicated, where you register it is not irrelevant. (Technically speaking there are also the wizards in Visual Studio, but personally I tend to stick to the portals.)
Old Azure Portal
If you go to https://manage.windowsazure.com you will find the legacy portal, which coincidentally has Azure AD as one of its hold-outs. It is probably the go-to place in most cases still though.
New Azure Portal
Heading over to https://portal.azure.com is the more snazzy-looking, (and confusing depending on who you ask), portal for registering apps. This will be the place to go going forward, but it does not do things in the same way as the old one.
Apps Portal
Coming in from the sideline we have https://apps.dev.microsoft.com which is yet another place to register your app. The main difference between this option and the two other ones is that this doesn't require you to have an AAD tenant, or Azure subscription. You can for instance login with a Microsoft account, (formerly LiveId, Hotmail, something), and leverage both corporate and personal accounts for login.
Pro tip
Use the same portal you used for registering the app for configuring it afterwards. Yes, you should be able to switch between the old and new Azure portal, but that doesn't mean everything is identical on the back-end. Maybe there is a bug giving the appearance of being correctly configured, but it isn't actually so.
So which one should you use?
If you want to go the "it just works" route, and you want to go live as quickly as you can the old portal is the tried and tested approach.
If you have a more relaxed time line, want to experiment, and can live with the occasional UI snag go with the new one. Note that AAD management in the new portal is at the writing of this in preview, so it's basically acknowledged that there might be bugs.
The dedicated apps portal…so far mainly for very specific use cases where you need both AAD and MSFT accounts. For doing social authentication (like MSFT account) I would generally lean towards Azure AD B2C instead. More on that topic later.
There are instances where you don't have a choice as to which one to use. If you have an Office 365 subscription provided through a CSP, as opposed to buying directly from Microsoft, you can only use the new portal. (You should add an Azure subscription.) And if you are not the service/global admin your access role could be setup so you don't have access where you expected to. These are issues you might need to address internally in your organization.
So, what are the differences then?
Naming
In the old portal you add a new app , in the new one you register a new app if you develop it yourself, but add third-party apps. Not a big thing, but it's easy to get your terminology mixed up with minor things like this. And when communicating with other people it's kind of useful to be on the same page as to what one is doing.
Different Wizards
Ok, no-one expected the wizards to be identical between two distinctly different portals. But for instance in the old one you always start by clicking "Add", and then branch into either first-party, third-party or on-prem. In the new you start on the AAD blade, and either go to Enterprise applications or App registrations . Which may or may not make sense. (In my opinion an "Enterprise App" could be both something someone else made, and something you make in-house.)
Configuration options
The UI might not expose all the same settings. Take the very basic task of adding a new client secret/key. In the new portal you get to type in a description, (which is hugely useful if you handle multiple keys), but in the old one you don't get this luxury.
[caption id="attachment_3035" align="alignnone" width="824"]
Client Secret in old portal[/caption]
[caption id="attachment_3025" align="alignnone" width="836"]
Client Secret in new portal.[/caption]
In the apps portal they call it Application Secrets . No description here either, but you do get to see the first characters to give you a hint.
[caption id="attachment_3015" align="alignnone" width="430"]
Client Secret in Apps portal.[/caption]
As long as you stick to one portal and do all your configuration there you should have no worries. Things shouldn't automatically break if you switch portals along the way, but you can see how things might be confusing to keep track of.
Behind the scenes
Ah, this is where the plot thickens. We can get over things having different names in different places. It's when the things you don't see, does things you don't know about, it can quickly lead to "why is this not working?". For instance I have a curious issue with a test app I created only being visible in the old and the apps portal, and not in the new one. Why? I don't know, (granted I didn't research it in detail because it didn't matter), but certainly it indicates something weird going on.
Application vs servicePrincipal
We need to take a short detour here and get into what an "app" actually is in the AAD database. Every object in AAD has an objectId (in the form of a guid). For a user object the attribute you care about is something like the UPN , but you still need it to be a unique object, which is why you often deal with its objectId when working on the object. For an app there are plenty of attributes, but when you publish an app it is the appId you care about. This looks similar to the objectId , but it's not the same. Every app you publish will have an appId in the AAD tenant you registerered it.
[caption id="attachment_3045" align="alignnone" width="517"]
An
application
Object.[/caption]
You would think that having this appId means that it's all ready to go, but not so fast. If I park a nice car in front of your house it's not going to do you much good just standing there. Even if it is in plain sight you need the keys to the car to actually drive it. Not a perfect analogy, I'll give you that, but you need something to drive the app as well. In the case of AAD this would be a servicePrincipal .
The servicePrincipal has its own id (because it is a separate object), but will include a reference to an appId .
[caption id="attachment_3055" align="alignnone" width="542"]
A
servicePrincipal
object[/caption]
Much like the Highlander there can be only one appId , but there can be multiple servicePrincipals . (You should get used to bad jokes and references.) If you publish a SaaS app that will be used by a number of customers, their AAD tenants will not have an app object; they will have a servicePrincipal object referring to your appId . If your app is not enabled for other tenants, they will not be able to add it to their tenant. (In the screenshot above this can be seen as the availableToOtherOrganizations attribute.)
This all ties in to the Consent Framework which we will get back to later, since it's a topic that warrants a little more than a paragraph to explain.
Makes sense right? So how does this apply to the portals? Thing is that it's not just your customers who need that reference object. You need it too. When you test the app you are developing, in your AAD tenant, with a user from the same tenant, you still need this to exist. And if you registered your app in the new portal this will be an issue. The old portal creates a servicePrincipal for you, the new one does not. Luckily there is an easy way to fix this, but if you're not aware of it I can sympathize with the ensuing troubleshooting headaches:
http://www.cloudidentity.com/blog/2016/10/04/provision-an-app-created-on-portal-azure-com-in-your-own-tenant/
Authorization endpoints
Another not so transparent thing is what happens when using the apps portal versus the other two portals. The apps portal registers the app with the AAD v2 endpoint. If you're using the helper libraries in your app this isn't necessarily something you notice since it's all being abstracted away from you. But if you are very specific as to which protocols you use for acquiring tokens, (AAD supports a number of them), this might be relevant as v2 is all about OAuth and Open ID Connect.
For a reference - Should I use the v2.0 endpoint? :
https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-v2-limitations
We will get back to this when we start churning out some demo code. As for this being a dev blog post without code, what's up with that? It makes me feel queasy too, but that's just the way it had to work out since (surprisingly) not all challenges are best illustrated through code :)
Wrapping up these introductory tips
And then there is getting the permissions right, getting the aforementioned consent, etc. If you are unsure of what is happening in the background be ready for going straight to the source in the form of GraphExplorer , or doing REST calls manually. Yes, those things are on my list for future topics already :)
I'll proceed with banging on the keyboard to work on the next part in this series, but I have a tip for something you can do while waiting. If you (like me) believe Azure AD is the best thing since sliced bread - buy Vittorio's book:
https://www.amazon.com/Authentication-Directory-Applications-Developer-Reference/dp/0735696942
He knows more about Azure AD than I ever will, and odds are you'll learn a thing or twenty if you take the time to read through the book. (Don't worry, it's not as scary as it sounds, and it reads mostly easily.) Since it focuses on Web-based applications it doesn't cover everything you can do with AAD, but it takes you a long way. It's unfortunately not a free resource, but it's so good I had to include it anyways.
Requests for more things AAD to cover? Useful so far? Let me know in the comments below, and I'll see you soon for more.
Published Feb 12, 2019
Version 1.0
