Hermes CLI Tool 🪽👟

Note: This is a fork of a private project developed during contract work for Studentmediene i Trondheim AS in summer 2025. This repository represents a snapshot of the project with sensitive information removed and commits rebased to ensure no confidential data is exposed. The original project remains private.

Table of Contents

• Table of Contents
• Hermes CLI Tool Documentation 🪽👟
  • Key Features
  • Project Structure
  • Getting Started
    • Prerequisites
    • CSV File Format
    • Group Mappings (groups.json)
  • Running Hermes with Docker
  • Running it locally (recommended for development)
    • 🖥️ Local Requirements
    • ✅ Go Environment
    • 📦 Go Dependencies
    • 📦 Required PowerShell Modules
    • Exchange Online Management
  • Command-line Flags:
    • Example:
    • Output and Logging
  • Technical Details
    • Authentication
    • Dependencies
    • Development Environment

Hermes CLI Tool Documentation 🪽👟

Hermes is a command-line interface (CLI) tool designed to automate the onboarding process for new users within Microsoft Entra ID (formerly Azure AD). It streamlines the creation of user accounts, assigns them to relevant groups, and can send welcome emails, leveraging the Microsoft Graph API and PowerShell for comprehensive management.

Key Features

• User Provisioning: Creates new user accounts in Microsoft Entra ID based on data from a CSV file.
• Automated Group Assignment: Assigns users to appropriate Microsoft 365, security, and distribution groups based on their specified position from predefined mappings.
• Email-Enabled Security Group Handling: Special processing for security groups and email-enabled ones, generating a PowerShell script for manual execution to ensure Exchange Online permissions are applied.
• Welcome Email Sending: Optionally sends welcome/invitation emails to new users with their generated credentials.
• CSV Data Parsing & Validation: Reads applicant data from a CSV file, performs comprehensive validation (e.g., phone number format, email address validity, accepted offer status), and generates usernames.
• Dry Run Mode: Allows simulating the onboarding process without making actual changes to Microsoft Entra ID, useful for testing and verification.
• Detailed Logging: Provides a logging mechanism to collect and output information, warnings, and errors to a log file for review.

Project Structure

The codebase is organized into several key directories:

• configs/: Stores configuration files such as groups.json (group mappings) and groups.template.json.
• internal/: Houses the core logic components:
  • config/: Manages application configuration.
  • csv/: Contains logic for parsing and validating CSV files, including parser.go and parser_test.go.
  • graph/: Interacts with the Microsoft Graph API for user and group management, including client.go (Graph client creation), groups.go (group operations), and users.go (user creation).
  • groupDelegation/: Specifically handles group assignment logic, including the separation and processing of email-enabled security groups.
  • onboarding/: Orchestrates the entire onboarding workflow.
  • usernameGenerator/: Contains the logic for generating usernames.
• output/: Contains files created by the app like scripts and logs
• pkg/: Contains utility packages:
  • email/: Provides functionality for sending emails.
  • logger/: Implements the logging mechanism.
  • resolveoutputdir/: Helps in resolving output directories.
  • passwordgenerator/: Provides functionality for creating unique passwords for users
• testdata/: Stores example CSV files used for testing.
• .gitignore: Defines files and directories to be ignored by Git (e.g., compiled binaries, log files, temporary data).
• CHANGELOG.md: Documents notable changes to the project.
• Dockerfile: Defines the steps to build a Docker image for the application.
• go.mod: Specifies Go module dependencies.
• main.go: The main entry point for the application.
• README.md: This documentation file.

Getting Started

Hermes is designed to be run as a command-line tool, typically within a Docker container due to its dependencies on PowerShell modules for Microsoft 365 interactions.

Prerequisites

• Docker (recommended for ease of setup)
• A CSV file containing applicant data.
• A secrets.env file in root with necessary authentication credentials for Microsoft Entra ID.
  • AZURE_TENANT_ID=your-tenant-id
  • AZURE_CLIENT_ID=your-client-id
    • Azure secrets can be found in the Azure Portal under your registered application's Overview page
  • AZURE_CLIENT_SECRET=your-client-secret
    • The client secret must be created under Certificates & secrets in your Azure application registration

CSV File Format

The CSV file must contain the following headers (in Norwegian) for the csv.Parse function to correctly extract applicant data:

• Navn: Full name of the applicant (e.g., "Ola Peder Nordmann").
• Telefon: Phone number (Norwegian format, will be formatted to +47XXXXXXXX).
• E-postadresse: Applicant's personal email address.
• Stilling: Position applied for.
• Status: Application status (e.g., "Tilbud, takket ja" for accepted offers).

From these, the tool extracts FirstName, LastName, and generates a 7-character Username.

Navn, Telefon is added as personal information on the newly created accounts.

E-postadresse is used to send invitation email.

Status is to sort out who is supposed to be onboarded.

Stilling is used to categorise the created users to add them to groups based on the corresponding Stilling in the groups.json.

Group Mappings (groups.json)

The groups.json file defines how positions are mapped to various Microsoft 365, security, and distribution groups. It also specifies default_groups that all users are added to.

Running Hermes with Docker

Important

All files created by the app can be found under the directory output/

The Docker image includes PowerShell and necessary Microsoft Graph SDK and Exchange Online Management modules.

Building the docker image. Open terminal of choice with docker. Cd to where Hermes is located then run the commad:

docker build -t name-of-your-choice .

Then you can run commands, but with docker, getting files created by the app is not as straightforward as running it locally. You need to mount the output path and mount other files you want and the program will handle this, it is what pkg/resolveoutputdir/resolveoutputdir.go does.
Like this:

docker run --rm `
>>   -v "$($PWD.Path)\output:/app/output" `
>>   -v "$($PWD.Path)\secrets.env:/app/secrets.env" `
>>   -v "$($PWD.Path)\applicants-spring-2025-copy.csv:/app/TESTDATA.csv" `
>>   name-of-your-choice -csv /app/TESTDATA.csv

This command mounts local directories (output/, secrets.env, and your CSV file) into the Docker container's app/ directory and executes the main binary with the -csv flag. Using this command make sure the scripts and logs created by the app end up in the output/ directory locally on your computer.

Note

The docker image's working directory is defined in the Dockerfile

WORKDIR /app

Meaning changing this changes where files need to be mounted and where those mounted files can be referenced

Running it locally (recommended for development)

Important

All files created by the app can be found under the directory output/

🖥️ Local Requirements

✅ Go Environment

• Install Go (version 1.24 or later recommended)
  • Download Go

📦 Go Dependencies

• Ensure you have go.mod and go.sum in the root.
• Run the following in your project directory:

  go mod tidy
  go build -o main .
  # The -o flag forces build to write the resulting executable or object to the named output file or directory

📦 Required PowerShell Modules

These modules are required to interact with Microsoft 365 and Exchange Online:

Exchange Online Management

Used to manage Exchange Online features, including mailboxes and distribution/security groups.

Install-Module -Name ExchangeOnlineManagement -Force -Scope CurrentUser
Install-Module -Name Microsoft.Graph -Force -Scope CurrentUser


### PowerShell Compatibility by OS

### 🪟 Windows
- Native support.
- Both Windows PowerShell (5.1) and PowerShell 7+ available.

### 🐧 Linux (Ubuntu, Debian, CentOS, Fedora, etc.)
- Installable via package manager or script.
- Fully supports PowerShell 7+.

### 🍎 macOS
- PowerShell 7+ is available via Homebrew.
- Runs natively on macOS.

Command-line Flags:

• -csv <path_to_csv>: Required. Path to the CSV file containing user data
• -group-mappings <path_to_json>: Path to the JSON file with group mappings (defaults to groupMappings.json in the app directory if not specified)
• -dry-run <default: false>: Boolean flag to perform a dry run (simulate actions without making changes)
• -verbose <default: false>: Boolean flag for more detailed logging output
• -email-security-batch-file <path>: Path for the JSON batch file for email-enabled security groups
• -email-security-script-file <path>: Path for the generated PowerShell script for email-enabled security groups
• -domain <domain_name>: The domain for user emails (e.g., "example.com")
• -welcome-email-batch <path>: Path for welcome email batch file
• -welcome-email-script <path>: Path for welcome email PowerShell script file
• -generate-welcome-email <default: true>: Boolean flag for generating welcome email script

Example:

$ go run "cmd/hermes/main.go" -csv testdata/applicants-spring-2025-copy.csv -dry-run true

Output and Logging

Hermes logs its operations and results.

• General Logs: Information, warnings, and errors are collected and written to a log.txt file (or a custom filename if specified) at the end of execution.
• Failed Users: If any users fail during the onboarding process, their information is written to a separate log file for manual review.
• Email-Enabled Security Group Scripts: If email-enabled security groups are involved and it's not a dry run, the tool will generate a PowerShell script (.ps1) and a JSON batch file (*batch*.json) in the output directory. These files are necessary for post-processing and manual execution in Exchange Online to complete group assignments. The tool will remind the user to run this script.

Caution

Running the Powershell scripts too early after a big onboarding process, as in creating a lot of new users, can take some time for Azure to update. This can result in a failed run. To avoid this issue we recommend waiting a couple minutes before running the script or checking if users exist in exchange online using this command (recommend the last user created. Information can be found in the log.txt):

Connect-ExchangeOnline
Get-User -Identity "user@domain.com"

Technical Details

Authentication

The tool can authenticate with Microsoft Graph API using:

• Client Secret Credential: Recommended for automated processes, using client ID and secret.
• User Credentials (ROPC flow): Can be used for specific operations like sending mail, but generally less secure for automated tasks.
• Application Permissions: For sending mail on behalf of any user without requiring individual user credentials.

Dependencies

Key Go module dependencies listed in go.mod include:

• github.com/Azure/azure-sdk-for-go/sdk/azidentity: For Azure AD authentication.
• github.com/joho/godotenv: For loading environment variables from .env files.
• github.com/microsoft/kiota-authentication-azure-go: Microsoft Kiota authentication library.
• github.com/microsoftgraph/msgraph-sdk-go: The official Microsoft Graph SDK for Go.

Development Environment

The Dockerfile outlines the build process:

1. Stage 1 (Builder): Uses golang:1.24-alpine to build the Go application. It installs git and compiles the main binary.
2. Stage 2 (Final Image): Uses mcr.microsoft.com/powershell:7.4-debian-bullseye-slim as the base. It installs essential tools (curl, unzip, less) and, crucially, the ExchangeOnlineManagement and Microsoft.Graph PowerShell modules, which are vital for interacting with Exchange Online and Graph API functionalities that Go might not directly support (especially for email-enabled security groups). The compiled Go binary and groupMappings.json are then copied into this final image.