User Attributes

User Attributes for Maester

A Maester Pack that checks that Microsoft Entra users have the attributes your HR processes, dynamic groups and licensing depend on, and that those values are formatted consistently.

Requirements: PowerShell 7.4 or later and the Maester 3.x prerelease (Install-PSResource -Name Maester -Prerelease). Pack support is not yet available in a stable release; see the pack documentation.

Trust: Maester reviews a pack before installation and pins the approved files, but it does not sandbox PowerShell. This pack's Graph permissions are read-only; its code still runs in your Maester session with access to your local environment. Review the install summary and the pack's declared access in maester-pack.json before approving it.

Quick start

Install-PSResource -Name Maester -Prerelease -TrustRepository -Scope CurrentUser
Import-Module Maester -MinimumVersion 3.0.0 -MaximumVersion 3.99.99 -Force
Install-MtPack DevClate/maester-pack-ua
Connect-MgGraph -Scopes ((Get-MtGraphScope) + 'User-LifeCycleInfo.Read.All')
Invoke-Maester -Pack CLT.UA -SkipBuiltIn

Install-MtPack installs the newest release, or main while this repository has no release. The extra User-LifeCycleInfo.Read.All scope lets MP.CLT.UA.1006 read hire dates; without it, that test reports Investigate. To run only this pack use -Pack CLT.UA -SkipBuiltIn; -Pack CLT.UA also runs Maester's built-in tests.

Tests

Attributes are set

MP.CLT.UA.1014–1017 check fields that many organisations deliberately leave blank (fax especially), so they carry the tag Optional. Leave them all out with -ExcludeTag Optional, or turn one off in maester-config.json, for example { "Id": "MP.CLT.UA.1016", "Enabled": false, "Reason": "Fax not used" }.

Attributes are formatted correctly

Attributes use approved values

MP.CLT.UA.1013 (country spelling) reads the same approved values. Until you set approved values, these tests report Investigate and list the values they find, so your first run gives you the list to start from. See Approved values.

Choosing which tests run

Tags used by this pack: UserAttributes (all), Presence, Format, Optional, Governance, Licensing, Guests, Address, Phone, Fax, LifecycleWorkflows.

Permissions

The connection Maester uses needs these Microsoft Graph permissions (all read-only):

Connect-Maester already asks for Directory.Read.All, which covers the first two. It does not ask for User-LifeCycleInfo.Read.All: to include it, connect with Connect-MgGraph -Scopes ((Get-MtGraphScope) + 'User-LifeCycleInfo.Read.All').

Which users are checked

By default every test checks enabled member users (MP.CLT.UA.1009 checks enabled guests, and MP.CLT.UA.1010 also checks disabled accounts). The Microsoft Entra Connect sync account is always left out.

Leaving users out

Users are left out at three levels, and the levels add up: a test's own list never replaces the others.

Users are user principal names or object IDs. Groups are object IDs (the pack-wide CLT.UA.ExcludedGroups also accepts a group's mail address), and their nested members are left out too. Each result ends with a bulleted summary, so you can see why someone isn't listed:

Left out 14 users:

• 2 emergency access (EmergencyAccessAccounts)
• 9 by the pack-wide exclusions (CLT.UA.ExcludedUsers and CLT.UA.ExcludedGroups)
• 3 by this test's ExcludedUsers and ExcludedGroups

{
  "GlobalSettings": {
    "EmergencyAccessAccounts": [ { "UserPrincipalName": "breakglass1@contoso.com", "Type": "User" } ],
    "CLT.UA.ExcludedUsers": ["svc-scanner@contoso.com"],
    "CLT.UA.ExcludedGroups": ["<object id of a Service Accounts group>"]
  },
  "TestSettings": [
    { "Id": "MP.CLT.UA.1005", "Parameters": { "ExcludedGroups": ["<object id of a Contractors group>"] } }
  ]
}

Pack settings

Approved values

The approved-value tests (MP.CLT.UA.1018–1026, and MP.CLT.UA.1013 for countries) compare each user's value with a list you approve. Blank values are not checked by these tests; the presence tests check those. There are three ways to give the lists, and you can mix them:

The checked-in example configuration is validated against the configuration JSON Schema in CI. Start with that file when building your tenant configuration. Validate your own config without a tenant:

Test-Json -Json (Get-Content ./maester-config.json -Raw) -SchemaFile ./schemas/maester-config.schema.json

{
  "GlobalSettings": {
    "CLT.UA.AllowedValues": {
      "department": ["IT", "Finance", "Human Resources"],
      "jobTitle": ["Chief Executive Officer", "IT Manager", "Accountant"],
      "country": ["United States", "Canada"],
      "locations": [
        { "name": "Seattle HQ", "streetAddress": "1 Microsoft Way", "city": "Redmond", "state": "WA",
          "postalCode": "98052", "country": "United States", "companyName": "Contoso Ltd",
          "businessPhones": "+14255550100" },
        { "name": "New York", "streetAddress": "500 Fifth Avenue", "city": "New York", "state": "NY",
          "postalCode": "10110", "country": "United States", "companyName": "Contoso Ltd" }
      ]
    },
    "CLT.UA.AllowedValuesFile": "./validation.json"
  },
  "TestSettings": [
    { "Id": "MP.CLT.UA.1019", "Parameters": { "AllowedValues": ["IT Manager", "Accountant"] } }
  ]
}

• Keys are the Graph property names: department, jobTitle, companyName, streetAddress, city, state, postalCode, country, businessPhones, officeLocation, plus locations. Each takes a list, or a single value.
• Locations count as lists too. The values in locations are approved values of each attribute, so the cities, postal codes and phone numbers of your offices don't need listing twice. MP.CLT.UA.1026 also checks that a user's fields belong to the same location. A field a location leaves out is not compared, and name is shown in results.
• The 2.x validation.json works as it is. Its validTitles, validDepartments and validLocations are read, and zipCode counts as postalCode. Point CLT.UA.AllowedValuesFile at it.
• The file path is read from the folder the run starts in, unless it is absolute. If the file is missing or not valid JSON, the tests that need it report an error that names the setting and the path.
• Letter case matters by default (Finance is not finance). Set a test's CaseSensitive to false to ignore case.

First run: with no approved values set, each test reports Investigate with a table of the values in use and how many users have each. Copy the correct ones into CLT.UA.AllowedValues, then run again to see what to fix.

Test parameters

Every test takes these parameters:

Test-specific parameters:

Set them in maester-config.json:

{
  "TestSettings": [
    { "Id": "MP.CLT.UA.1008", "Parameters": { "Fields": ["city", "country", "officeLocation"] } },
    { "Id": "MP.CLT.UA.1016", "Parameters": { "MaxRows": 0 } },
    { "Id": "MP.CLT.UA.1011", "Parameters": { "AllowSpaces": true } },
    { "Id": "MP.CLT.UA.1013", "Parameters": { "AllowedCountries": ["United States", "Canada"] } },
    { "Id": "MP.CLT.UA.1007", "Enabled": false, "Reason": "Single company" }
  ]
}

Developing

See TESTING.md for the full guide: loading the pack-enabled Maester without touching the Maester repository, offline checks, connecting with the right scopes, running tests while you develop, installing locally for a full report, and seeding test users. The short version:

Test-MtPack .              # the checks Install-MtPack runs, without installing
Connect-Maester
Invoke-MtTest -Path .      # run the pack from this folder
Invoke-MtTest -Path ./tests/Test.MP.CLT.UA.1011.ps1 -Parameter @{ AllowSpaces = $true }
Invoke-MtTest -Path ./tests/Test.MP.CLT.UA.1016.ps1 -Parameter @{ MaxRows = 0 }   # list every failing user

Versions and releases

Install-MtPack DevClate/maester-pack-ua installs the newest GitHub release, or the main branch while the repository has no release. The repository includes the pack workflows: check-pack.yml checks every push and pull request with Maester 3.x, validates the example configuration, and checks version/changelog consistency. bump-version.yml and release.yml publish a release for each merged pull request once the repository variable PACK_RELEASES is true; the release workflow warns if the release is not immutable or the pack index does not show its status. Until releases are enabled, raise Version in maester-pack.json by hand. Every change is written under ## Unreleased in CHANGELOG.md. Report security problems as described in SECURITY.md.

History

The presence tests started as Maester 2.x Pester tests in DevClate/Custom-Maester-Tests (ENTRA.UA.1001–1017). In this pack they:

• run on the Maester 3.0 native test engine, with no Pester, connection checks or try/catch;
• share one query helper, so exclusions work the same way in every test;
• read managers and sponsors in one Graph request instead of one per user;
• skip disabled accounts by default and take exclusions as parameters instead of hard-coded names;
• merge the five address tests into one (MP.CLT.UA.1008).

The approved-value tests started as the Validating tests (ENTRA.UV). In this pack they read their lists from maester-config.json or a file you name instead of a validation.json beside the tests, list each unapproved value once with how many users have it, ignore blank values (the presence tests check those), and read zipCode correctly as the postal code.

License

MIT