Today we’re announcing a new feature at Office365Mon that our customers have been asking about for quite some time.  We’ve added the ability to monitor the Search service in your SharePoint Online tenant using our well-established health probe architecture.  This has been frequently requested because Search in SharePoint plays such a pivotal role in content delivery.  There are many out of the box web parts that depend on successfully executing queries to generate the content for the page.  On top of that there are many, many custom applications that are dependent upon the Search service working correctly.  From a developer perspective this has been an approach advocated by Microsoft for several years (including myself when I was in that role) because of the reduction in load it puts on the SharePoint farm as well the ability to pull data from a variety of sources.

When we were first designing this feature it primarily focused on the query aspect of the Search service.  However, after giving a sneak peek at what we were planning with several of my former colleagues at Microsoft, they felt just as passionate (if not more so) that we should also see what we could do about monitoring crawl performance.  Apparently quite a few of them have had customers frustrated about not seeing the content they expected when using Search and in many cases found out that their content had not actually been crawled yet.  There were some challenges in managing this request, but we found a solution that we’re happy with and causes a minimal amount of friction for our customers.  Best of all, like all our other features, I think you’ll find this extremely easy to set up and use.

What Does It Do?

Here’s a screenshot of the configuration page for the Office 365 Search Monitoring feature so you can see just how easy it is to configure what it does for you:

The Office 365 Search Monitoring feature allows you to provide a custom Keyword Query Language (KQL) query that we will execute against the site we’re monitoring for you with Office365Mon.  We have a link to the KQL guide when you go in and configure Search monitoring, and it can be something as simple asquerytext=’sharepoint’.  As you’ll see if you look at the KQL reference though, the beauty of this is that you can actually get quite sophisticated in your KQL.  You can do things like control how many search results are returned, select a set of properties to return, use different ranking models, enable stemming, enable phonetics, etc.  One of the big reasons why we chose to use KQL directly is because so many of you have written us about custom applications you have built on Search and you want some means to monitor them.  By letting you use KQL, you can use any query that’s relevant to what your app does, and we’ll use that as the basis for monitoring.

Once you have your KQL, we take over from there.  We really monitor three things around the KQL query you’ve provided, based on the feedback and requests we’ve received the last several months:

1. Query latency – you define a maximum query time, and if it takes longer than that for us to get results back from running your KQL, we send out a notification to all of your configured notification options. That includes emails, text messages, and of course – now – webhooks.  If you have apps that are based on the Search service it can be critically important to know when queries are running slowly – based on a latency you decide is needed – so you know whether there are issues with your app, or issues with the Search service that your app is using.
2. Search results change – you can receive notifications when search results change. What this means is that if the set of results changes from the last time we ran your KQL, we’ll send out notifications.  If the only thing that changes is the raw rank value of the items in the search results, we will NOT send out notifications.  However, if all of the search results are the same, but the order of them changes, we DO send out notifications.  It’s also important to underscore that this reflects only on the search results themselves – it has nothing directly to do with the underlying items in the search results.  What that means is that if you change a document that’s included in the search results, we don’t detect and notify for that.  However, if that change caused a change in the search results – either the document no longer shows up, it shows up higher or lower in the search results, etc. – then we would send out notifications.

There are a couple of other things worth noting here as well.  First, we don’t store your actual search results.  This is consistent with how we do things here at Office365Mon – we don’t store usernames and passwords, and we don’t store your data.  What we DO store is a one-way hash of the search results.  When we do another search, we create the hash on the latest results and compare it to the hash we had before, and if they’re different we know the search results have changed.  It’s a one-way hash which means that it cannot be “reverse engineered” or otherwise tampered with to rehydrate the actual search results.

The second thing worth noting here is that in our experience, you may see the search results change quite frequently, even if there have not been any changes to the site content.  This is not a bug or issue with the Office365Mon Search Monitor feature.  We find that there may be hours and sometimes days when the search results come back exactly the same.  Then there are times when you may get different search results on five or six queries in a row.  Again – using the same KQL and the site content has not changed – but the search results ordering changes.  This is something you should be aware of when developing your applications based on the Search service.  If you need to know when it happens, now you can use our Search monitor feature to be alerted to it.  To help you parse through the changes, you can also elect to check the box to Include results in notifications when results change.  When that option is selected, you’ll get the actual search results we received in both emails and webhooks – just not text messages.  Again – these results are not saved anywhere, we are simply forwarding to you what we received.

3. No search results – the other option you have is to get notified when no search results are returned from your KQL. Again, whether you’re using out of the box web parts or a custom application, if you have content in your site that’s dependent upon getting search results, this can be a critical notification to have.

Finally, as described above, the other thing we monitor is content indexing.  With a simple checkbox, you can have us monitor your search index to see how long it is taking to crawl new content.

With all of the features described above, there are several reports that you can also use to stay on top of how things are doing.  More details regarding the reports are described below.  Also, if you want detailed step-by-step instructions for configuring Search monitoring you can get them from our site athttps://www.office365mon.com/configuresearchmon.pdf.  One final point worth making – you can also do all of the configuration programmatically using our Subscription Management API.  See our latest API documentation for details and code samples.

How Does It Do It

The Office 365 Search Monitor uses the same super-scale health probe infrastructure that Office365Mon has been using since Day One.  That enables us to issue and track query responses to your tenant.  To support crawl monitoring though, we had to come up with something a little different, and here’s why.  The monitoring applications we use are all defined in Azure Active Directory, and as part of that definition we describe what rights our applications need.  We always use the least invasive permissions possible to get the job done, so all of our apps are configured with the smallest amount of Read Only rights that we can get away with.  To do crawl monitoring though, we needed a way to determine how long it takes to get new content indexed – so how do we do that?  Well, we need to write a small amount of data to the site we’re monitoring, and then start issuing queries for that content.  We look at when we wrote the content into the site, and how long it takes until it starts showing up in search results, and that’s how we calculate the time it takes to index the content.

As described above though, all of our applications are configure to only have Read rights, so how can we write content to a site?  That’s where we had to add a new item to our toolbox to make it happen, and what we decided to do is to write a SharePoint App.  Yes, the same SharePoint Apps many of you develop to bring your site to life, we built one as well.  We wanted to limit our scope as much as possible, so the app only has rights in the current site it’s installed in – not any other site (i.e. SPWeb) in the site collection, nor any other site collection in the tenant.  When you first configure the Office 365 Search Monitoring feature, if you elect to Monitor search index freshness, the first check we do is to ensure the application is installed in the site being monitored.  If it’s not, we let you know so you can go install the app and try saving your Search monitoring configuration changes again.

The SharePoint App is in (or soon will be in) the Office Store under the name Office365Mon Search Monitor.  You can install it from there into the site being monitored.  In addition to that, since some folks turn off access to the Office Store, when you go to our Configure Office 365 Search Monitor page, we have a link you can use to download a zip file containing the SharePoint App.  If you go that route you’ll need extract the .app file out the zip file, upload it to the App Catalog in your tenant, and then you can install it in the monitored site.

When the app is installed and you save your search monitoring configuration, we’ll look for a custom list we use to store the data used for monitoring the search index freshness.  If it doesn’t exist, we’ll create it.  After that we use the app to create new content in the list so we can monitor how quickly it’s being indexed.

Reporting on Search Monitoring

We’ve built a half-dozen new reports based on the Office 365 Search Monitoring feature.  We have a very full list of Advanced Reports now with your Office365Mon subscription, as you can see in the Report Gallery here:

You can get recent data (i.e. from the last few hours) on query and crawl latency.  Here’s an example of the recent crawl latency report:

You can get daily stats on query and crawl latency – here’s an example of the daily query latency report:

Don’t be fooled by the numbers either – they show exactly why you want to monitor your query latency.  You can look at the graph and see overall the queries are returning data in sub second time.  However, it’s not uncommon to see this, yet still get notifications about queries that have taken 15 or 20 seconds or longer.  That’s what you want to know – your queries normally perform one way, but when they are significantly different it may be impacting the content and performance in your site.

We also have reports that show your monthly query and crawl latency averages, and they are overlaid on top of our service-wide averages so you can see how your performance is compared to your peers that are being monitored by Office365Mon.  In addition to that, in the Basic Reports you can see data just on the average crawl and query latency across our entire service:

In addition to our out of the box reports, you can also use our Report Data API to programmatically retrieve this data via our REST endpoints.  For those of you using our Power BI integration, you will also automatically see monthly crawl and query freshness data show up in Power BI after you refresh your data in there.

How Do I Get It

All existing Office365Mon customers always get all new features free to try for 90 days; everyone has had the feature turned on.  In addition, all new customers also always get ALL our features free to try for 90 days.  The feature is currently in beta, but rolled out now so everyone can begin using it.

That’s it – a quick run-down on a feature that we believe many of you will find extremely useful.  It has great value whether you are using out of the box web parts, or you’ve developed your own custom applications built on Office 365.  As always, if you have suggestions or ideas on how to improve this or any other feature at Office365Mon, please just drop me a note at support@office365mon.com.

From Sunny Phoenix,

Steve

At Office365Mon we love, love, love developers, so we continue to invest in growing the APIs we provide.  As we noted last month, we added support for webhooks to our notification pipeline.  That allows you to receive a JSON payload in your own web site and kick off your own workflow when outages occur or an Office 365 service changes status.  It’s this second scenario where we’ve done a little more work with our REST API this month.

To briefly recap what we mean by an Office 365 service changing status – at Office365Mon you can choose to monitor for service status changes.  That means a service – like Exchange Online – has several sub-services or features, such as “Sign-in”, “E-mail and calendar access”, “Voice mail”, etc.  Each of those sub-services has a service status.  The status can be one of these values:

• Investigating
• RestoringService
• VerifyingService
• ServiceRestored
• PostIncidentReviewPublished
• ServiceDegradation
• ServiceInterruption
• ExtendedRecovery
• Scheduled
• InProgress
• Completed
• Canceled
• ServiceOperational

So being able to monitor a change in the service status means that you can get notified when a sub-service enters the “Investigating” state, or “ServiceInterruption” state, etc.  This has in fact been an extremely popular Office365Mon feature for our Enterprise Premium customers.  Until now though, you had to manage the statuses that we monitor in the browser.  What we’ve just released are some additions to our Subscription Management API to allow you to manage this programmatically as well.  Given the popularity of this feature, as well as the desire of most of our Partners to be able to script everything, this was a natural fit to add to our API.

Here’s a brief rundown on the new APIs we’ve added in support of this:

• Get Service Status Values – Use this method to get a list of all of the possible service statuses that can be monitored.  You can use this to allow your users to select the service statuses they want to monitor, or as values to send to the Subscription Management API to set the statuses that are being monitored for a subscription.
• Get the Monitored Service Statuses – Use this method to get the service statuses that are being monitored for a subscription.
• Set the Monitored Service Statuses – Use this method to set the service statuses that are being monitored for a subscription.

All of these new APIs have been fully documented in our SDK, which you can download from here. We’ve also added code samples for each of these new APIs to our Subscription Management API sample code that you can download from here.  We hope you’ll find this APIs a nice addition to your developer tool belt at Office365Mon.

From Sunny Phoenix,

Steve

From day one Office365Mon has made short work of letting you set up monitoring for your Office 365 tenant in a couple of minutes and notifying you by text and email when an outage occurs. Today we’re happy to announce that we’re taking the next step forward in keeping you in the know by releasing support for webhook notifications. Now you can decide exactly what processes you want to kick off whenever your Office 365 tenant experiences an outage, or even when the status of one of the Office 365 features change.

For those of you who aren’t familiar with what a webhook is, it’s worth a short explanation. A webhook consists of a web site that you host, and that site includes a “place” where another application can send it data. You can then configure another application – in this case Office365Mon – to send data there so that you can process it. With the Office365Mon webhook that’s exactly what we do – when there’s an outage starting for example, we send over a JSON payload that describes what Office365Mon subscription is being impacted, what type of webhook it is, and what resource is being impacted; for example, your SharePoint Online site.

As noted above though, we do this for more than just those times when an outage starts. We send notifications to your webhook under the following conditions:

• When an outage starts
• When an outage ends
• When an Office 365 feature enters one of the following states (NOTE: you control which of these states you want monitored when you configure your Office365Mon subscription):
  • Investigating
  • RestoringService
  • VerifyingService
  • ServiceRestored
  • PostIncidentReviewPublished
  • ServiceDegradation
  • ServiceInterruption
  • ExtendedRecovery
  • Scheduled
  • InProgress
  • Completed
  • Canceled
  • ServiceOperational

If you compare this to how notifications are handled today, you can quickly see the power of the webhook. When an outage starts you get an email and/or a text message; then what do you do? You pull up a laptop or get on your phone and start emailing people, start updating your service status on internal sites, let your help desk know there’s an issue, maybe check in with your Technical Account Manager (TAM) at Microsoft, etc. You probably have a whole checklist of things to do.

Now imagine this same scenario with a webhook. You automate everything. You’re no longer manually working through a checklist of tasks. You can create your own workflows that take different actions depending on the information you get in your webhook. For example, you can have it automatically update an internal Help Desk portal with an alert status that SharePoint Online is currently experiencing an outage. That informs users, reduces Help Desk phone calls, and keeps your team focused on fixing issues. Your workflows can automatically send out an email to your Help Desk organization letting them know an outage is occurring. It can fire off an email to your TAM letting him or her know that you have an outage going on so they should be prepared in case you need to open or escalate a support case. You can kick off a triage process with your engineering teams to start assessing the impact. You get the idea – you can do whatever you want – because now its notifications the way you want them.

To get started creating your webhook you should download our developer documentation for our Subscription Management API from here: https://www.office365mon.com/DeveloperInfo/subapi. It explains the particulars around what data is sent to your webhook, the requirements that your webhook needs to support, how to process the webhook data that is sent to you, etc. We’ve added support for webhooks in both our website and through our Subscription Management API. That means that you can add and remove a webhook, as well as test a webhook entirely using our Subscription Management API. You can also do the same thing when you go to configure your Office365Mon subscription in our site. In the Notification Info section you can add or remove a webhook, as well as send a test webhook right from that page:

As a developer, I love the possibilities that a feature like this opens up. I hope that you’ll find many useful ways to take advantage of this for your own organizations. This is also a good time to point out that this is yet another example of a feature that we added based on suggestions and feedback from you, our customers. Please keep them coming, we love hearing them.

From sunny Phoenix,

Steve

We just released a mini-feature that our long and loyal customer base will appreciate.  For those of you not following closely, we opened the doors to our service just about a year ago.  One of the things that means is that for customers who have been with us since the beginning, you will be able to take advantage of new Year-over-Year data in your My Info reporting.

For those of you not familiar with the My Info page at Office365Mon.Com, it’s what we call the 360° view of your tenant.  You get the basic info we know about you, the absolute latest status for your tenant resources that we are monitoring for you, the recent status of all of your features and feature services as reported by Microsoft, the latest messages that Microsoft has sent to your Office 365 Service Health Dashboard, a chart with your availability info for the month, and a Tweet link to share with the world exactly how you’re doing.

What we’ve done is to update the charting feature on the My Info page so that you can compare your up-time data for the current month with what it was one year ago.  It’s always interesting to see how things compare over time, and this is a really nice quick snapshot of what things look like side-by-side.  Here’s an example of how your chart will look once you’ve been a customer for a year:

As you see, if you really only want to see the data for the current month then it’s easy enough to click the box and turn off the data for the prior year.  We thought it was kind of a neat feature though, and a nice little reminder of how far we’ve come.  We hope you’ll enjoy this little feature, but remember – you can always get:

• LOADS of reports in the Basic Reports and Advanced Reports options
• Download raw report data as a CSV file so you can open it in Excel and create your own reports like this or anything else you want
• Programmatically retrieve data with our Report Data REST API endpoints and create your own dashboards or pull the data into your own reporting systems
• Use Power BI in Office 365 for the ultimate in reporting power and customization

That’s all for now.  We’re busy working on some great new features as we speak, but as always, please send any ideas, suggestions and feedback to support@office365mon.com.  We love to hear from you!

From Sunny Phoenix,

Steve

Microsoft is currently working on a new authentication and authorization model that is simply referred to as “v2” in the docs that they have available right now. I decided to spend some time taking a look around this model and in the process have been writing up some tips and other useful information and code samples to help you out as you start making your way through it. Just like I did with other reviews of the new Azure B2B and B2C features, I’m not going to try and explain to you exactly what they are because Microsoft already has a team of humans doing that for you. Instead I’ll work on highlighting other things you might want to know when you actually go about implementing this.

One other point worth noting – this stuff is still pre-release and will change, so I’m going to “version” my blog post here and I will update as I can. Here we go.

Version History

1.0 – Feb. 3, 2016

What it Does and Doesn’t Do

One of the things you should know first and foremost before you jump in is exactly what it does today, and more importantly, what it does not. I’ll boil it down for you like this – it does basic Office 365: email, calendar and contacts. That’s pretty much it today; you can’t even query Azure AD as it stands today. So if you’re building an Office app, you’re good to go.

In addition to giving you access to these Microsoft services, you can secure your own site using this new model. One of the other terms you will see used to describe the model (besides “v2”) is the “converged model”. It’s called the converged model really for two reasons:

• You no longer need to distinguish between “Work and School Accounts” (i.e. fred@contoso.com) and “Microsoft Accounts” (i.e. fred@hotmail.com). This is probably the biggest achievement in the new model. Either type of account can authenticate and access your applications.
• You have a single URL starting point to use for accessing Microsoft cloud services like email, calendar and contacts. That’s nice, but not exactly enough to make you run out and change your code up.

Support for different account types may be enough to get you looking at this. You will find a great article on how to configure your web application using the new model here: https://azure.microsoft.com/en-us/documentation/articles/active-directory-v2-devquickstarts-dotnet-web/. There is a corresponding article on securing Web API here: https://azure.microsoft.com/en-us/documentation/articles/active-directory-devquickstarts-webapi-dotnet/.

Once you have that set up, you can see here what it looks like to have both types of accounts available for sign in:

The accounts with the faux blue badges are “Work or School Accounts” and the Microsoft logo account is the “Microsoft Account”. Equally interesting is the fact that you can remain signed in with multiple accounts at the same time. Yes! Bravo, Microsoft – well done.  :-)

Tips

Knowing now what it does and doesn’t do, it’s a good time to talk about some tips that will come in handy as you start building applications with it. A lot of what I have below is based on the fact that I found different sites and pages with different information as I was working through building my app. Some pages are in direct contradiction with each other, some are typos, and some are just already out of date. This is why I added the “version” info to my post, so you’ll have an idea about whether / when this post has been obsoleted.

Tip #1 – Use the Correct Permission Scope Prefix

You will see information about using permission scopes, which is something new to the v2 model. In short, instead of defining the permissions your application requires in the application definition itself as you do with the current model, you tell Azure what permissions you require when you go through the process of acquiring an access token. A permission scope looks something like this: https://outlook.office.com/Mail.Read. This is the essence of the first tip – make sure you are using the correct prefix for your permission scope. In this case the permission prefix is “https://outlook.office.com/”. There are still multiple documents out there though that say for the v2 model you should use the prefix “https://graph.microsoft.com/”. Do not do this. You will get an access token if you do this. However, when you try and use it to access a v2 service endpoint you will get a 401 unauthorized response.

Also…I found in one or more places where it used a prefix of “https://outlook.office.com/”; note that it is missing the “s” after “http”. This is another example of a typo, so just double check if you are copying and pasting code from somewhere.

Tip #2 – Not All Permission Scopes Require a Prefix

After all the talk in the previous tip about scope prefixes, it’s important to note that not all permission scopes require a prefix. There are a handful that work today without a prefix: “openid”, “email”, “profile”, and “offline_access”. To learn what each of these permission scopes grants you can see this page: https://azure.microsoft.com/en-us/documentation/articles/active-directory-v2-compare/#scopes-not-resources.  One of the more annoying things in reviewing the documentation is that I didn’t see a simple example that demonstrated exactly what these scopes should look like. So…here’s an example of the scopes and how they’re used to request a code, which you can use to get an access token (and refresh token if you include the “offline_access” permission – see, I snuck that explanation in there). Note that they are “delimited” with a space between each one:

string mailScopePrefix = “https://outlook.office.com/”;

string scopes =
“openid email profile offline_access ” +
mailScopePrefix + “Mail.Read ” + mailScopePrefix + “Contacts.Read ” +
mailScopePrefix + “Calendars.Read “;

string authorizationRequest = String.Format(             “https://login.microsoftonline.com/common/oauth2/v2.0/authorize?response_type=code+id_token&client_id={0}&scope={1}&redirect_uri={2}&state={3}&response_mode=form_post&nonce={4}”,
Uri.EscapeDataString(APP_CLIENT_ID),
Uri.EscapeDataString(scopes),
Uri.EscapeDataString(redirUri),
Uri.EscapeDataString(“Index;” + scopes + “;” + redirUri),
Uri.EscapeDataString(Guid.NewGuid().ToString()));

//return a redirect response
return new RedirectResult(authorizationRequest);

Also worth noting is that the response_type in the example above is “code+id_token”; if you don’t include the “openid” permission then Azure will return an error when it redirects back to your application after authentication.

When you log in you see the standard sort of Azure consent screen that models the permission scopes you asked for:

Again, worth noting, the consent screen actually will look different based on what kind of account you’ve authenticated with. The image above is from a “Work or School Account”. Here’s what it looks like when you use a “Microsoft Account” (NOTE: it includes a few more permission scopes than the image above):

For completeness, since I’m sure most folks today use ADAL to get an access token from a code, here’s an example of how you can take the code that was returned and do a POST yourself to get back a JWT token that includes the access token:

public ActionResult ProcessCode(string code, string error, string error_description, string resource, string state)

{
string viewName = “Index”;

if (!string.IsNullOrEmpty(code))
{

string[] stateVals = state.Split(“;”.ToCharArray(),

StringSplitOptions.RemoveEmptyEntries);

viewName = stateVals[0];
string scopes = stateVals[1];
string redirUri = stateVals[2];

//create the collection of values to send to the POST
List<KeyValuePair<string, string>> vals =
new List<KeyValuePair<string, string>>();

vals.Add(new KeyValuePair<string, string>(“grant_type”, “authorization_code”));
vals.Add(new KeyValuePair<string, string>(“code”, code));
vals.Add(new KeyValuePair<string, string>(“client_id”, APP_CLIENT_ID));
vals.Add(new KeyValuePair<string, string>(“client_secret”, APP_CLIENT_SECRET));
vals.Add(new KeyValuePair<string, string>(“scope”, scopes));
vals.Add(new KeyValuePair<string, string>(“redirect_uri”, redirUri));

string loginUrl = “https://login.microsoftonline.com/common/oauth2/v2.0/token&#8221;;

//make the request
HttpClient hc = new HttpClient();

//form encode the data we’re going to POST
HttpContent content = new FormUrlEncodedContent(vals)

//plug in the post body
HttpResponseMessage hrm = hc.PostAsync(loginUrl, content).Result;

if (hrm.IsSuccessStatusCode)
{
//get the raw token
string rawToken = hrm.Content.ReadAsStringAsync().Result;

//deserialize it into this custom class I created
//for working with the token contents
AzureJsonToken ajt =
JsonConvert.DeserializeObject<AzureJsonToken>(rawToken);
}
else
{
//some error handling here
}
}
else
{
//some error handling here
}

return View(viewName);

}

One note – I’ll explain more about the custom AzureJsonToken class below.

Tip #3 – Use the Correct Service Endpoint

Similar to the first tip, I saw examples of articles that talked about using the v2 app model, but then pointed to service endpoints that use the v1 app model. So again, to be clear, your single service endpoint for v2 apps is https://outlook.office.com/api/v2.0/me/. If you see code examples that use https://graph.microsoft.com/v1.0/me/, that is the old endpoint. If you get a v2 token and try to use it against a v1 endpoint, then mostly bad things will happen.

Tip #4 – Be Aware that Microsoft Has Pulled Out Basic User Info from Claims

One of the changes that Microsoft made in v2 of the app model is that they have arbitrarily decided to pull out most meaningful information about the user from the token that is returned to you. They describe this here – https://azure.microsoft.com/en-us/documentation/articles/active-directory-v2-compare/:

In the original Azure Active Directory service, the most basic OpenID Connect sign-in flow would provide a wealth of information about the user in the resulting id_token. The claims in an id_token can include the user’s name, preferred username, email address, object ID, and more.

We are now restricting the information that the openid scope affords your app access to. The openid scope will only allow your app to sign the user in, and receive an app-specific identifier for the user. If you want to obtain personally identifiable information (PII) about the user in your app, your app will need to request additional permissions from the user.

This is sadly classic Microsoft behavior – we know what’s good for you better then you know what’s good for you – and this horse has already left the barn; you can get this info today using the v1 model. Never one to be deterred by logic however, they are pressing forward with this plan. That means more work on you, the developer. What you’ll want to do in order to get basic user info is a couple of things:

1. Include the “email” and “profile” scopes when you are obtaining your code / token.
2. Ask for both a code and id_token when you redirect to Azure asking for a code (as shown in the C# example above).
3. Extract out the id_token results into a useable set of claims after you exchange your code for a token.

On the last point, the Microsoft documents say that they provide a library for doing this, but did not include any further detail about what it is or how you use it, so that was only marginally helpful. But hey, this is a tip, so here’s a little more. Here’s how you can extract out the contents of the id_token:

1. Add the Security.IdentityModel.Tokens.Jwt NuGet package to your application.
2. Create a new JwtSecurityToken instance from the id_token. Here’s a sample from my code:

JwtSecurityToken token = new JwtSecurityToken(ajt.IdToken);

1. Use the Payload property of the token to find the individual user attributes that were included. Here’s a quick look at the most useful ones:

token.Payload[“name”] //display name
token.Payload[“oid”] //object ID
token.Payload[“preferred_username”] //upn usually
token.Payload[“tid”] //tenant ID

As noted above though in my description of the converged model, remember that not every account type will have every value. You need to account for circumstances when the Payload contents are different based on the type of account.

Tip #5 – Feel Free to Use the Classes I Created for Deserialization

I created some classes for deserializing the JSON returned from various service calls into objects that can be used for referring to things like the access token, refresh token, id_token, messages, events, contacts, etc. Feel free to take the examples attached to this posting and use them as needed.

Microsoft is updating its helper libraries to use Office 365 objects with v2 of the app model so you can use them as well; there is also a pre-release version of ADAL that you can use to work with access tokens, etc. For those of you rolling your own however (or who aren’t ready to fully jump onto the pre-release bandwagon) here are some code snippets from how I used them:

//to get the access token, refresh token, and id_token
AzureJsonToken ajt =
JsonConvert.DeserializeObject<AzureJsonToken>(rawToken);

This next set is from some REST endpoints I created to test everything out:

//to get emails
Emails theMail = JsonConvert.DeserializeObject<Emails>(data);

//to get events
Events theEvent = JsonConvert.DeserializeObject<Events>(data);

//to get contacts
Contacts theContact = JsonConvert.DeserializeObject<Contacts>(data);

You end up with a nice little dataset on the client this way. Here’s an example of the basic email details that comes down to my client side script:

Finally, here’s it all pulled together, in a UI that only a Steve could love – using the v2 app model, some custom REST endpoints and a combination of jQuery and Angular to show the results (yes, I really did combine jQuery and Angular, which I know Angular people hate):

Emails

Events

Contacts

Summary

The new model is out and available for testing now, but it’s not production ready. There’s actually a good amount of documentation out there – hats off to dstrockis at Microsoft, the writer who’s been pushing all the very good content out. There’s also a lot of mixed and conflicting documents though so try and follow some of the tips included here. The attachment to this posting includes sample classes and code so you can give it a spin yourself, but make sure you start out by at least reading about how to set up your new v2 applications here: https://azure.microsoft.com/en-us/documentation/articles/active-directory-v2-app-registration/. You can also see all the Getting Started tutorials here: https://azure.microsoft.com/en-us/documentation/articles/active-directory-appmodel-v2-overview/#getting-started. Finally, one last article that I recommend reading (short but useful): https://msdn.microsoft.com/en-us/office/office365/howto/authenticate-Office-365-APIs-using-v2.
You can download the attachment here:

As those of you who are familiar with Office365Mon know, we heavily leverage the Office 365 APIs in our solution.  It’s been a key player in being able to issue now over 100 million health probes against Office 365.  I know and have talked to lots of you as well that are starting to build apps that leverage this same infrastructure for your own solutions.  As you develop these solutions based on the Office 365 APIs, it’s pretty important that you understand the scenarios where the Azure access token you get will and will not work to access Office 365 resources.

First, a couple of basics.  When you get an access token, for purposes of our conversation here today, the token represents your identity that is going to be used to access a resource in some way.  There are exceptions to this, i.e. app only tokens, but this post is about user identities and Office 365.  When you try and access a resource, you say here is my access token, I want do this with the content – for example, I am Steve, I want to read the email in my inbox.

The problem is this – what I just described is a common scenario, and it works well today with the Office 365 APIs.  But there are actually at least four scenarios, and you may be surprised to learn that the Office 365 APIs only work with one of them.  Part of the reason in writing this blog post is to make sure you all are aware of that, but also to hopefully drive a discussion with the folks that own the service so that they can give some consideration to expanding their support of these other scenarios in the future.  Here’s a quick run down on the scenarios that I’ve looked at so far; there may be others.

1. I own or otherwise have direct rights to a resource – WORKS!  This is the first scenario I described above – for example, when I want to access the email in my inbox, or if I’m part of a SharePoint group in my Office 365 tenant and I want to access content in that site.
2. I have been granted delegate rights to a mailbox – DOESN’T WORK!  In this scenario, I’ve been granted rights to another mailbox.  Now if open up Outlook for example I can read the mail in that mailbox no problem.  If I’m using the Exchange Web Services (EWS), I can access the mail in that mailbox.  But if I’m using the Office 365 APIs, it doesn’t work.
3. I have been invited to a SharePoint Online site – DOESN’T WORK!  In this scenario I’ve been invited as an external user to a SharePoint Online site.  I use my Azure AD credentials to accept the invitation and I can connect to the site in the browser.  However if I try and use an Azure access token against that resource it fails with an access denied error.
4. I have been added to an Azure tenant using the Azure B2B feature – DOESN’T WORK!  This is similar to #3 – after being added to the Azure tenant with the B2B feature I can be added to a SharePoint Online site and access it just fine in the browser.  However my Azure access token will only get me an access denied error if I try and use it on that site with the Office 365 APIs.

The key and common thread in all of these scenarios is that I am using my Azure AD identity.  It is a durable, immutable identity containing an immutable identifier known to Azure AD.  Even though I’m using that immutable identity, there is still a disconnect between it and all of the ways in which it has been granted access to resources in Office 365.  That is to say, there is a disconnect in the Office 365 APIs; in the browser applications they have this figured out.  Make sure you know these limitations, and let your favorite Microsoft human if you would like to these disconnects eliminated for a comprehensive and integrated identity and resource solution.

Back to my old nemesis…the long very long blog post title.  :-)   I ran across this problem myself recently, and had seen someone else experience but not had the time to dig into it.  In short the problem goes something like this – you create a new ASP.NET web application in Visual Studio 2015.  You configure it to be secured with Azure AD (i.e. Work and School accounts).  You do your thing, you build your web site, you test it locally, you can authenticate and everything works fine – great!

Now you want to deploy the app to your Azure web site.  You go through the publishing wizard, which pushes the content up to your web site.  It launches the browser for you to log in and check out your site but – boom – your app blows up.  After you authenticate it redirects you back to your site and you get the dreaded yellow page of death (i.e. an unhandled exception).  When you turn customErrors to Off in web.config you can see the error is “invalid client secret”.  You know it works fine when you run it on your local machine, so how can it be invalid?

This is the question that plagued me for a couple of days before I finally had the time to completely unwind it.  This post is partially “here’s how you fix it” and partially “this is why I think it happens”.  In the two cases where I’ve seen this happen so far, the project started out targeting .NET 4.52, then was subsequently changed to 4.61.  I noticed that the publishing wizard changes the UI slightly when you do that.

When targeting 4.52 the wizard includes a checkbox that says “Enable Organizational Accounts”.  The default behavior is to have that box checked.  I always uncheck it because my “organizational account” configuration is completed when I’m building and testing the application.  When targeting 4.61 I no longer see this option in the UI.

So here’s the fix and here’s the guess at what’s wrong.  If you look in the Properties folder in your project you will find one or more .pubxml files, which represent your publishing profiles.  In this case, the .pubxml file contained a completely different ClientId and ClientSecret value than my web.config did.  It was that client ID and secret that was getting pushed up to the Azure web site, and that’s why my application blew up once it was published to Azure.  To fix it, I just manually copied the ID and secret from my web.config into my .pubxml file.

Now…my guess as to why I think it happens (I deleted some stuff before I could actually verify this), I think when you have that box checked in the wizard when targeting 4.5.2, Visual Studio creates a new application definition in Azure AD, and then pulls in the client ID and secret from it into the publishing wizard.  That would explain how the wrong client ID and secret gets published and “stuff breaks”.

Anyways, if you run across this problem hopefully you’ll find this post.  Good luck!

We’re very happy today to announce the release of new integration between the Office365Mon reporting data and Power BI in Office 365. Office365Mon is used to monitor your SharePoint Online and Exchange Online tenants. Along the way it captures quite a bit of data related to outages in your tenants as well as performance data. There are several basic and advanced reports supplied with your Office365Mon subscription, but we wanted to dial things up a notch and give you even more flexibility to create the reports you want for your business.

To support that vision we partnered with Microsoft recently to build a Power BI content pack for your Office365Mon report data. The content pack has just been published and now is available for all Power BI users in Office 365. Here’s a screenshot of the dashboard:

This of course just serves as the starting point. You can customize the dashboard and reports as much as you like. You can also drill into these dashboard reports for greater detail, like you see here with the performance data:

The Power BI team published a great blog on the integration with Office365Mon so check it out for additional details and instructions for getting it set up for yourself: https://blogs.msdn.com/b/powerbi/archive/2015/12/11/analyze-your-office365mon-data-in-power-bi.aspx. To generate the data for the content pack you just need to create an Office365Mon subscription. When you do, you’ll be an admin for the subscription, and then when you sign into Power BI using that same account you used to create your Office365Mon subscription you can create your dashboard.

We hope you find this new level of reporting and integration provides you a great view and insight into the quality of your Office 365 services.

From sunny Phoenix,

Steve

As we’ve had more and more interest from customers wanting to monitor multiple mailboxes and sites with Office365Mon, I decided it was time to both make it easier to do and to explain some of the facts you need to keep in mind when monitoring multiple resources.

If you look at our pricing page you’ll see that with the Basic monitoring package you can monitor up to 10 sites and mailboxes. When you go into Configure your Office365Mon subscription though, you only see a place to add one mailbox and one site. That’s because we purposefully created Office365Mon to support one mailbox and one site per subscription. The reason for that is simple – based on our many years of working with Office 365, we found that in most cases, when you have a problem with one resource, you have a problem with them all. For example, it’s very rare that you have one SharePoint site down and the rest of the sites in the tenant up and working. Generally then, if you monitor a single mailbox or site in your tenant you’ll have a pretty good idea that if it’s down, so are your other resources and vice versa.

There are exceptions to that of course, and other reasons why you may want to monitor multiple resources – that’s why we give you up to 10 with Basic monitoring. In order to do that then, you just need to create multiple subscriptions. Each subscription monitors a different site and mailbox, so if you create 10 subscriptions that’s how you can monitor 10 mailboxes and sites. We’ve made the process of creating new subscriptions much easier so I wanted to cover that first.

Creating a New Subscription

If you go to the Configure Office365Mon page, you will see a button in the General Subscription Info section called Copy Subscription.

If you click that button, it creates a new subscription for you. When it does so it creates it with this configuration:

• The Company Name is the same as the current subscription but has the date and time appended to it
• The Contact Email is the same
• All of the subscription admins are the same
• All of the notification addresses (email addresses and text phone numbers) are the same
• The outage duration to wait before sending notifications is the same (as shown in the picture below)

Here’s an example of a what the General Subscription Info looks like for a subscription that was copied:

After you copy your subscription, you will see a dropdown list of subscriptions near the top of the page:

It contains a list of all of your subscriptions so you can easily switch between the different subscriptions, whether you are configuring them, looking at reports, features, the My Info page, etc.

Adding More Mailboxes and Sites

From what I described at the beginning of this post, you know that you can now just navigate to each subscription and configure a mailbox and site for each one, and that’s how you’ll set up monitoring for multiple resources. You may notice then from the previous section, the only thing we don’t copy for you when duplicating a subscription are the resources being monitored. There’s also a simple reason for that – when you configure a resource for Office365Mon to monitor, you have to do so by logging in to the Office365Mon site with an account that has rights to that resource. For example, if you are adding a mailbox to monitor, you need to log in as an account that has rights to read the contents of the mailbox. If you are adding a site to monitor, you have to log in as an account that has at least Read rights to the site. So, if you want monitor 10 mailboxes and 10 sites for example, that means you have a few options:

1. You can create one account and grant it rights to read every mailbox and every site you want to monitor.
2. You can create a different account (or use existing ones) for each mailbox you want to monitor.  You can grant each account rights to a site that each one can monitor.
3. Some combination of 1 and 2 – for example, use different accounts for each mailbox, but just use one account and grant it Read rights to different sites for monitoring SharePoint.

Account management is another reason that we start out with one subscription, site and mailbox. Most organizations do not want to create one account that has rights to multiple mailboxes. At Office365Mon we provide you the flexibility to go forward with whatever security model works best for you.

Once you’ve settled on your security model you need to add the account(s) as an Office365Mon admin to each subscription that they are configuring. For example, assume you create an account for monitoring called “mon1”, you create a mailbox for it and you grant it rights to a SharePoint site. Please note that “mon1” will also need an Office 365 license in order to get the mailbox and have rights to the site! After you’ve completed that configuration in Office 365, you need to log into Office365Mon using an account that is already a subscription admin. Then go to the Subscription Admins section for the subscription and add the “mon1” account, like this:

After you’ve done that you need to close the browser, then open a new browser window and log into the Configure Office365Mon page using the account you just added as an admin. Once you do that you can scroll down to the Cloud Resources section and add the mailbox UPN and SharePoint site Url to monitor as you would normally. Just repeat that process for each mailbox and site you want to monitor.

Hopefully the process makes sense now. As always though, if you have questions or just feedback or feature request for the product, please email us at support@office365mon.com.

From sunny Phoenix,

Steve

This is a companion piece to the Azure B2C First Look I published last week. This post is some first thoughts around the new Azure B2B features that were recently announced. The goal of Azure B2B is to reduce the complexity and rigidity of managing business to business relationships and sharing data. The announcement around the B2B feature correctly characterizes this problem as typically being solved either by federating between two companies, or creating a directory (or OU or whatever) in your own internal directory for external users. Both solutions have pros and cons to them. The Azure B2B solution is what I would consider something of a hybrid approach between the two. External users continue to use their one and only external account for authentication so they don’t have to remember multiple account names and passwords. However, they also get added (maybe “linked” is a better way to describe it) within the Azure AD tenant into which they are “added” (a process I’ll explain below). Overall though, even in preview it’s a pretty painless and easy way to connect people up from different organizations.

As with the Azure B2C post, I’m not going to try and explain every bit of the feature and how to configure it – Microsoft has a team of writers tasked with just that. Instead I’ll give you a few links to get started and then share some real world experience now with how it looks and works. So…to get started I would recommend taking a look at this content:

• Blog post announcing and describing the B2B feature:  https://blogs.technet.com/b/ad/archive/2015/09/15/learn-all-about-the-azure-ad-b2b-collaboration-preview.aspx
• Short article describing CSV file format and sample:  https://azure.microsoft.com/en-us/documentation/articles/active-directory-b2b-collaboration-overview/
• Short video with lead PM for the feature describing and demoing it (only about 11 minutes long):  https://channel9.msdn.com/Series/Azure-AD-Identity/AzureADB2B

Getting Started

The process for getting started is a little peculiar, but there is a certain logic to it. In short, when you want to allow users from other companies to access your resources, you have to create a CSV file with information about them and import that into Azure AD, which you can do via the portal. In fact PowerShell support for doing this is not there at this time, but I’ll be a little surprised if it doesn’t show up by RTM. This is where the second link above will be useful to you – it explains the format of the CSV file you need to create and provides an example of what it looks like.

In my case, for my first test I started with my SamlMan.Com tenant and built out a simple ASP.NET MVC application secured with Azure AD. I got that all working and then invited my Office365Mon.Com account. The CSV for it looked something like this:

Email,DisplayName,InviteAppID,InviteReplyUrl,InviteAppResources,InviteGroupResources,InviteContactUsUrl

speschka@office365mon.com,Office365Mon Steve,FFEAF5BD-528B-4B53-8324-E4A94C1F0F06,,65b11ba2-50f7-4ed2-876d-6a29515904b2,,https://azure.microsoft.com/services/active-directory/

The main things worth pointing out in this simple CSV is the display name I gave – Office365Mon Steve – because that’s how it’s going to show up in the SamlMan.Com AD tenant. Also the GUID that starts with 65b11… is the Client ID of my MVC application that I described above. Once you import the CSV file Azure sends an email to everyone in it, and then each person has to open the email, click a link and accept the invitation. You can see a report in Azure of the status of each person you invited.

Here’s what the report looks like:

When you get your invitation email it looks something like this (some additional customization options are available, but for testing I’m waaaaay to lazy to make it look pretty):

You’ll notice the email is addressed to the display name I put into the CSV file. I’ll show the invite pages in Azure a little later. Now, once that the person has accepted the invitation, as I noted above, they show up in the Azure AD tenant from which the invitation was sent. Here’s what my SamlMan.Com directory looks like after the invite was accepted:

Now with the invitation accepted I can log into the ASP.NET application as speschka@office365mon.com and it works just perfectly. Here’s yet another screenshot of my favorite home page, with all of the current user’s claims enumerated on the page:

You can see again that display name of “Office365Mon Steve” getting carried throughout, so make sure you use something that won’t require constant tinkering.

Using it with Other Cloud Applications

One of the things I thought was nice was the integration with other cloud applications. Obviously the images above illustrate integrating with my own custom apps, but what about the apps people frequently use in the cloud, like Office 365? Well, it works pretty slick for that as well. To work through this scenario I flipped things around and used my Office365Mon tenant and invited my account at SamlMan.Com. In the SharePoint spirit of things…I started out by creating a new group in my Azure AD tenant, like this:

Next I went to my SharePoint Online site and added this Azure AD group to the SharePoint Viewers group:

Next I got the object ID of the Azure AD group by running this bit of PoweShell: Get-MsolGroup | fl DisplayName, ObjectId. With that in hand, I created a new CSV file to invite my SamlMan.Com user. The CSV file looked like this:

Email,DisplayName,InviteAppID,InviteReplyUrl,InviteAppResources,InviteGroupResources,InviteContactUsUrl

steve@samlman.com,SamlMan Steve,6787E4D5-0159-4B74-B56D-AA7C36715C0E,,,95419596-ff8a-4db1-c406-ed4ad13fd272,https://www.office365mon.com

The most interesting part of this CSV is the GUID that starts with 95419… It’s the object ID of my SharePoint Readers group. Now when my invited user accepts his invitation he or she will get added to that group. I get the standard email invite that I showed above. When I click on the link to accept it, I am treated to a page in Azure that looks like this (you can also customize the appearance of this, which I chose not to do):

Now after I go through the process to accept the invitation, I went back to the Office365Mon SharePoint Online team site and was able to successfully authenticate and get in with Viewer rights:

Wrap Up

Overall everything with the B2B feature went incredibly smoothly with no hiccups or glitches of any kind; most of the Azure guys really seem to have their act together these days. J Honestly, it’s impressive and I know a lot of teams at Microsoft that could really take a lesson from how engaged the Azure team is with the community, taking feedback, and delivering great products. I think the biggest challenge I’m imagining after my first look is just the long-term user management; for example, when an invited user’s account is deleted from its home Azure AD tenant it would be nice to have it trigger deletes in all of the other AD tenants where it’s been invited. Stuff like that…but I think it will come in time. This is very good start however.