Documenting things sucks. If it involves a lot of klick(edi klack klack) in portals and copying information around even more. But there’s hope. And it’s called automation. For the Intune part Thomas Kurt did already an awesome job with his IntuneDocumentation.  Now the Modern Workplace Concierge is ready to help you with documenting your Conditional Access configuration. I promise you: we will get through this within under 15 minutes! Afterwards you can make an impression on your fellow Enterprise Mobility teammates.

What’s inside?

A Conditional Access policy is returned by the Microsoft Graph API in the following JSON representation:


{
  "id": "714b5737-5f13-415e-bf96-d659f3a5928e",
  "displayName": "PROD - Admin protection - Azure management: Require MFA",
  "createdDateTime": null,
  "modifiedDateTime": null,
  "state": "enabled",
  "grantControls": {
    "operator": "OR",
    "builtInControls": [
      "mfa"
    ],
    "customAuthenticationFactors": [],
    "termsOfUse": []
  },
  "conditions": {
    "signInRiskLevels": [],
    "clientAppTypes": [],
    "platforms": null,
    "locations": null,
    "deviceStates": null,
    "applications": {
      "includeApplications": [
        "797f4846-ba00-4fd7-ba43-dac1f8f63013"
      ],
      "excludeApplications": [],
      "includeUserActions": []
    },
    "users": {
      "includeUsers": [
        "All"
      ],
      "excludeUsers": [],
      "includeGroups": [],
      "excludeGroups": [
        "04988d96-ad01-4569-9aee-a199a1cb4f8e"
      ],
      "includeRoles": [],
      "excludeRoles": []
    }
  },
  "sessionControls": null
}

That’s not really human readable. Especially the object id’s  (32 character UUIDs) make it difficult to guess to which users or apps a policy is assigned. But an API has definitely other goals than showing pretty formatted reports.

Time to shine

Now it’s time to shine for the Modern Workplace Concierge. He will process your conditional access policies and convert all the object id’s like included / excluded users, groups, directory roles and applications.

In order to perform the conversion from the object id’s to display names the concierge asks the Microsoft Graph API under the following endpoints (base url starting with https://graph.microsoft.com:443):

  • /beta/conditionalAccess/namedLocations
  • /beta/directoryRoleTemplates
  • /beta/servicePrincipals
  • /beta/groups
  • /beta/users

Additionally he uses a mapping table for other well known (but unfortunately not really nice documented Microsoft apps like the Azure Portal which share the same application id in every tenant).

Besides the conversion part the concierge queries:

  • /beta/identity/conditionalAccess/policies
  • /beta/organization

Have you spotted the new Conditional Access Graph URL? 😉And if you’re wondering why he queries the /organization resource, that’s to include your default domain in the filename name of the csv.

After hitting the “Create Documentation” button you can watch the concierge doing his work by expanding the messages tab which includes the requests sent to the Graph API.

When finished you will receive a CSV file containing your documentation.

Comma separated - not semicolon separated!

When opening your file in Excel gives you a file like this - don’t put the blame on the concierge! He’s not having a hiccup. It’s (the) Windows (list separator).

Make sure to replace the list separator

The concierge exports the csv with comma delimited (separated) values. But Excel uses the Windows list separator which might be a semicolon based on your regional settings. A nice explanation is available here.

An easy fix is to open the csv file in the windows notepad and replacing all commas “,” with a semicolon “;”. [ctrl] + [h] opens the replace dialogue.

Excel time

Now we’re ready to work on our documentation. We will transpose (rotate) our csv so the rows become columns and vice versa. This improves the readability of our documentation. Furthermore we will create a new Excel file to use formatting (which is not supported for csv files).

  1. Copy the CSV data to the clipboard

  2. Create a new excel workbook

  3. Right click & paste the csv data with the transpose option

  4. Expand the rows and columns and & turn on textwrap

  5. Have you ever heard about the max row height of 409 points in excel? To display all the included directory roles I replaced the line breaks with commas with this online tool.

  6. A few mouse klicks and formatting steps later I ended up with this report (click here to see the pdf version & here if you prefer to have the excel file): Conditional Access Policy Documentation

Guess that’s not too shabby? I really like the spreadsheet format because it provides an overview about all configured policies in one place. It might be a nice way to show your fellow teammates a current Conditional Access configuration.

Happy documenting and thank you for using the Modern Workplace Concierge.