<protocol-specific-path><\/span> ::= \u201c\/oauth2\/authorize?api-version=1.0\u201d<\/em> | \u201c\/oauth2\/token?api-version=1.0\u201d<\/em> | \u201c\/federationmetadata\/2007-06\/federationmetadata.xml\u201d <\/em>| \u2026<\/span><\/p>\n <tenant><\/span> ::=\u00a0 <tenant-id> | <domain><\/span><\/p>\n <tenant-id> ::= <GUID><\/span><\/p>\n <domain> ::<\/span> = <hostname><\/p>\n <instance><\/span> ::= \u201chttps:\/\/login.windows.net\/\u201d<\/em> | \u2026<\/span><\/p>\n If you prefer things a tad less formal, we can think of some examples. For instance, if I want to obtain the OAuth2 authorization endpoint of my test tenant developertenant I can simply write:<\/p>\n https:\/\/login.windows.net\/developertenant.onmicrosoft.com<\/span>\/oauth2\/authorize?api-version=1.0<\/span><\/a><\/p>\n Another way I can refer to the exact same endpoint is the following:<\/p>\n https:\/\/login.windows.net\/6c3d51dd-f0e5-4959-b4ea-a80c4e36fe5e<\/span>\/oauth2\/authorize?api-version=1.0<\/span><\/a><\/p>\n This is the exact same endpoint \u2013 I am simply choosing a different way to identify the corresponding tenant. The advantage of using the domain is mostly that it\u2019s human readable and easier to remember than a GUID. The tenantID, on the other hand, has good properties like immutability (a domain can be discarded, a tenantID is forever), is non-reassignable (discarded domains might get bought by other orgs, messing with your endpoints) and provides a single identifier to construct a stable endpoint no matter how many domains you registered.<\/p>\n Where do I find the tenantID? There are various places to pick it up from. The easy one is via the Azure portal: all endpoints are listed via the view endpoints button on the bottom common bar in the AAD\/tenant\/applications page. Those endpoints are expressed via the tenantID.<\/p>\n Another way of retrieving that, which I favor because it does not require me to sign in, is to hit the public ws-federation metadata endpoint of the tenant \u2013 which is public. You can build that URL using the domain (which I usually remember), but the content of the metadata will always refer the tenantID. For example, if I follow<\/p>\n https:\/\/login.windows.net\/developertenant.onmicrosoft.com\/federationmetadata\/2007-06\/federationmetadata.xml<\/a><\/p>\n I\u2019ll land on the following document:<\/p>\n Et voila\u2019, the highlighted text is the tenantID. Also note the entityID, which is in itself a URI parametric in respect to the tenantID: it will come in handy later.<\/p>\n Anyway: once you have your endpoints, you can plug them in your favorite development stack and use them to your heart\u2019s content (usually to request tokens).<\/p>\n The above is all fine and dandy if you are writing a line of business app, where the organization you want to authenticate with is known at development time.<\/p>\n However, that does leave out a very large class of important applications: SaaS and multitenant applications. My recent favorite example is Org Navigator<\/a>, the little app I wrote few weeks ago that allows you to search for users in an Azure AD tenant<\/a>.<\/p>\n While it sleeps its dreamless sleep in its cell up in the Windows Store cloud, Org Navigator does not know which AAD tenant it will need to search. When you download and install it, Org Navigator still<\/em> does not know which tenant it should work with. However, when you first launch the app and you try your first query \u2013 BAM: it presents you the usual AAD credential experience. You sign in with one user from the tenant you want to target, and you\u2019re in: from that moment on, Org Navigator knows which AAD tenant to query (and knows how to get the tokens needed to do so).<\/p>\n How did I achieve this behavior when developing Org Navigator? What endpoint rendered the AAD credential experience, given that at that point the app did not know which domain or tenantID to use? The BNF I provided earlier wasn\u2019t really complete: the <tenant> entry should have been<\/p>\n <tenant><\/span> ::=\u00a0 <tenant-id> | <domain> | \u201ccommon\u201d<\/em><\/span><\/p>\n In a nutshell, common<\/em> is a convention used to tell AAD \u201cI don\u2019t yet know which tenant should be used. Please render a generic credential gathering experience, and we\u2019ll figure out the tenant depending on what account the user enters\u201d.<\/p>\n That is precisely what I did in Org Navigator. I arranged for the very first authentication operation to go against the authority (in ADAL parlance) https:\/\/login.windows.net\/common<\/a>, and that afforded me the behavior described above (for a more detailed walkthrough see Org Navigator\u2019s help page<\/a> \u2013 or download the app and try it on your own tenant or the graph test tenant<\/a>!). That is pretty handy! The user does the work for you, effectively late binding the tenant. However, there are a couple of things to keep an eye on.<\/p>\n That said, let\u2019s take a look at some practicalities of using common with web apps (via our OWIN middleware) and via ADAL.<\/p>\n As the post title says, common is NOT a tenant: rather, it is a convention that is used in place of a tenant for driving the real tenant identification process. Let\u2019s make a practical example. Let\u2019s say that we want to write a multi tenant web app secured via OpenId Connect which can sign users from any tenant. In order to late bind the tenant, we could write the following OWIN auth middleware init:<\/p>\n This would indeed cause the desired behavior\u2026 almost. If you\u2019d run the app you\u2019d be able to sign in with any user from any tenant, but upon authentication with AAD, the app would reject the call. Why? Whereas in a real tenant you\u2019d find actual tenantid values, the common endpoint cannot offer that given that the actual tenant that will be used is undefined. The \u201c{tenantid}\u201d string is clearly a placeholder rather than a real value. If we\u2019d be working with WS-Federation, the music would be the same. This is common\u2019s ws-fed metadata:<\/p>\n <\/p>\n What to do? The only way around this is to override the default issuer validation<\/strong>, which is meant to work with fixed-tenant line of business apps, with your own validation logic.<\/strong><\/p>\n The OWIN middleware makes it exceedingly easy. For example, in our multitenant web app sample we have a sign up experience which dynamically adds new tenants (or even individuals from arbitrary tenants). There, we turn off the default validation (via TokenValidationParameters\/ValidateIssuer=false) and we inject custom logic in the SecurityTokenValidated notification, late in the pipeline because in this case we need to have the user info available. Code here<\/a>. That\u2019s pretty much what there is to know about the common endpoint and web apps.<\/p>\n The common endpoint is easy to use with ADAL: you just pass it to your AuthenticationContext as the authority, and the authentication experience will follow the behavior described. However common is not a real tenant, and ADAL needs to perform some extra steps here. Namely: once the authentication takes place and a tenant from a real tenant is returned, the AuthenticationContext\u2019s authority is automatically reassigned to that real tenant<\/strong>.<\/p>\n Below you can see an example in which the authority starts as common, but as I sign in with a user from developertenant the authority changes accordingly.<\/p>\n![\"image\"](\"https:\/\/www.cloudidentity.com\/blog\/wp-content\/uploads\/2014\/08\/image_thumb.png\" "\\"image\\"")
<\/a><\/p>\n![\"image\"](\"https:\/\/www.cloudidentity.com\/blog\/wp-content\/uploads\/2014\/08\/image_thumb1.png\" "\\"image\\"")
<\/a><\/p>\nLate Binding a Tenant<\/h2>\n
\nIf your short term memory is not as bad as mine these days, you already guessed what made this possible: the common endpoint.<\/p>\n
\nOther canonical uses can be observed in our multitenant Web samples<\/a> \u2013 in particular, the sign in and sign up links. More details later.<\/p>\n\n
OWIN Middleware and the Common Endpoint<\/h2>\n
\nGiven its placement in the endpoints URI template, however, it is very hard not to think about it as a tenant and just use it everywhere one would use a real AAD tenant. In fact, that\u2019s largely the way in which we use it: however we do need to perform some extra steps to accommodate for common\u2019s peculiar behavior.<\/p>\npublic<\/span> void<\/span> ConfigureAuth(IAppBuilder app) { \r\n string<\/span> ClientId = ConfigurationManager.AppSettings[\"ida:ClientID\"<\/span>]; \r\n string<\/span> Authority = \"https:\/\/login.windows.net\/common\/\"<\/span>; \r\n \/\/ ...<\/span>\r\n\r\n app.UseOpenIdConnectAuthentication( \r\n new<\/span> OpenIdConnectAuthenticationOptions \r\n { \r\n ClientId = ClientId, \r\n Authority = Authority, \r\n }\r\n\/\/ ...<\/pre>\n
\nRecall how we managed to keep the object model of the OWIN authentication middleware so compact? That\u2019s right, we use the tenant coordinates to read from metadata documents the extra info we need to validate tokens. Now, the common endpoint does expose metadata as well \u2013 but they are somewhat incomplete. For example, if I open the OpenId Connect discovery doc I see the following:<\/p>\n![\"image\"](\"https:\/\/www.cloudidentity.com\/blog\/wp-content\/uploads\/2014\/08\/image_thumb2.png\" "\\"image\\"")
<\/a><\/p>\n
\nThe \u201cissuer\u201d value in that doc is the string that the OWIN middleware will use in its default validation logic to validate the \u201cissuer\u201d value of incoming tokens . Clearly that cannot work, given that once the user enters an account from a specific tenant the issuer value will be something like \u201chttps:\/\/sts.windows.net\/6c3d51dd-f0e5-4959-b4ea-a80c4e36fe5e<\/a>\/\u201d which clearly does not match \u201chttps:\/\/sts.windows.net\/{tenantid}\/<\/a>\u201d.<\/p>\n![\"image\"](\"https:\/\/www.cloudidentity.com\/blog\/wp-content\/uploads\/2014\/08\/image_thumb3.png\" "\\"image\\"")
<\/a><\/p>\n
\nIf in your heuristic you are only interested in the issuer, you can directly inject your own validation logic in the IssuerValidator notification of the TokenValidationParameters.
\nOr even further, if for some reason you are not interested in restricting access to your app per tenant you can simply turn off issuer validation and not provide any extra validation logic (if you think you\u2019re in this case, think long and hard about it to ensure that\u2019s truly OK for your scenario to skip that validation!).<\/p>\nADAL and the Common Endpoint<\/h2>\n
![\"image\"](\"https:\/\/www.cloudidentity.com\/blog\/wp-content\/uploads\/2014\/08\/image_thumb4.png\" "\\"image\\"")
<\/a><\/p>\n