olipassey/AzAppRegistrationExpiry
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update README.md

Browse Source
This commit is contained in:
Oli Passey
2025-03-05 11:21:51 +00:00
committed by GitHub
parent de0a24f4a2
commit e72b820ace
1 changed files with 88 additions and 74 deletions
Download Patch File Download Diff File Expand all files Collapse all files

152
README.md
View File

@@ -1,90 +1,104 @@
# Azure Function App for Secret Expiry Notifications # Azure App Registrations and Entra ID Account Expiry Notification
This Azure Function App fetches Azure App Registrations, checks for expiring secrets, and sends email notifications to the owners. This repository contains an Azure Function that monitors Azure App Registrations and Entra ID account credentials, particularly focusing on the expiry of password credentials for both. It automatically fetches app registrations and account details, processes expiry information, and sends notifications to relevant stakeholders.
## Prerequisites ## Features
- Azure Subscription - Fetches Azure App Registrations and associated credentials (password credentials).
- Azure CLI - Retrieves specific Entra ID accounts and checks their password expiration.
- Python 3.11 - Sorts and classifies the credentials based on their expiry dates.
- Azure DevOps account - Sends a customized email notification to users, with an HTML table showing the details of expiring or expired credentials.
- Self-hosted agent (optional)
## Setup ## Requirements
### Local Development - **Azure Function App**: This code is designed to run as an Azure Function.
- **Environment Variables**: The following environment variables are required for the function to authenticate to Microsoft Graph API and send emails:
- `AZURE_CLIENT_ID`: The Azure AD application client ID.
- `AZURE_CLIENT_SECRET`: The Azure AD application client secret.
- `AZURE_TENANT_ID`: The Azure AD tenant ID.
- `MONITORED_ACCOUNTS`: A comma-separated list of user principal names (UPNs) to monitor for password expiry.
- `SMTP_SERVER`: The SMTP server for sending email notifications.
- `SMTP_PORT`: The port to use for SMTP (usually 587).
- `SMTP_USERNAME`: The SMTP server username.
- `SMTP_PASSWORD`: The SMTP server password.
- `FROM_EMAIL`: The email address from which the notifications will be sent.
- `FROM_NAME`: The name displayed for the `FROM_EMAIL` address.
- `TO_EMAIL`: The recipient email address for the notifications.
1. **Clone the repository:** ## Setup
```sh ### 1. Clone the repository:
git clone https://github.com/OliPassey/AzAppRegistrationExpiry.git ```bash
cd AzAppRegistrationExpiry git clone <repo_url>
``` ```
2. **Create local dev environment & Install dependencies**: ### 2. Install dependencies:
Make sure you have Python3.11 installed, then run:
``` Ensure that you have the necessary libraries installed in your environment:
python3.11 -m venv .venv
source .venv/bin/activate ```bash
pip install -r requirements.txt pip install -r requirements.txt
```
### 3. Configure Environment Variables:
You need to set the following environment variables:
* **Azure Authentication**: These variables are used to authenticate against Microsoft Graph API.
* **SMTP Configuration**: These variables are used to send email notifications.
Example for local development (Linux/macOS):
```bash
export AZURE_CLIENT_ID="<your-client-id>"
export AZURE_CLIENT_SECRET="<your-client-secret>"
export AZURE_TENANT_ID="<your-tenant-id>"
export MONITORED_ACCOUNTS="user1@domain.com, user2@domain.com"
export SMTP_SERVER="smtp.yourserver.com"
export SMTP_PORT="587"
export SMTP_USERNAME="your-smtp-username"
export SMTP_PASSWORD="your-smtp-password"
export FROM_EMAIL="your-email@domain.com"
export FROM_NAME="Your Name"
export TO_EMAIL="recipient-email@domain.com"
``` ```
3. **Configure environment variables**: ### 4. Deploy to Azure:
Create a local.settings.json file in the root of the function app directory with the following contents
{
"IsEncrypted": false,
"Values": {
"AzureWebJobsStorage": "<YourAzureWebJobsStorage>",
"FUNCTIONS_WORKER_RUNTIME": "python",
"AZURE_CLIENT_ID": "<YourAzureClientId>",
"AZURE_CLIENT_SECRET": "<YourAzureClientSecret>",
"AZURE_TENANT_ID": "<YourAzureTenantId>",
"SMTP_SERVER": "<YourSmtpServer>",
"SMTP_PORT": "<YourSmtpPort>",
"SMTP_USERNAME": "<YourSmtpUsername>",
"SMTP_PASSWORD": "<YourSmtpPassword>",
"FROM_EMAIL": "<YourFromEmail>",
"FROM_NAME": "<YourFromName>",
"TO_EMAIL": "<YourToEmail>"
}
}
4. **Run the function locally**: Follow [Azure Functions deployment guide](https://docs.microsoft.com/en-us/azure/azure-functions/functions-deploy) to deploy the function to Azure.
Use the Azure Functions Core Tools to run the function:
```
func start
```
## Usage Function Workflow
-----------------
Once the function is running, it will run every week day morning at 9am and send an email with results. The TO_EMAIL should be the administrator email for EntraID or whoever looks after App Registrations. It will also CC: all App Owners as listed in the App Registration. 1. **Authentication**: The function authenticates to Microsoft Graph API using the Azure AD application credentials (Client ID, Client Secret, Tenant ID).
2. **Fetching Data**:
* The function fetches all app registrations and their associated password credentials using Microsoft Graph API.
* It fetches user account details for the specified Entra ID accounts and checks for password expiration.
3. **Processing Expiry Dates**: The credentials are processed to calculate the days until expiration. The credentials are sorted and categorized as:
* **Green**: More than 30 days to expiration.
* **Yellow**: Between 8-30 days to expiration.
* **Orange**: 7 days or less to expiration.
* **Red**: Expired.
* **Blue**: No expiration set.
4. **Email Notification**:
* The function generates an HTML report that contains all relevant app registrations and account details.
* The report is sent via email to the specified recipient and optionally to the owners of the apps.
## Deployment Email Notification Example
--------------------------
1. **Create an Azure DevOps Project (Private)** The email notification contains an HTML table that shows:
2. **Create a Variable Group in Azure DevOps:** * **App Registrations**: Display name, secret name, expiry date, days to expiry, and owners.
* **Entra ID Accounts**: Display name, user principal name, password expiry date, and status.
Go to Pipelines > Library. ### Color Coding in the Notification:
Click on + Variable group. * **Green**: More than 30 days until expiry.
* **Yellow**: Between 8-30 days until expiry.
* **Orange**: 7 days or less until expiry.
* **Red**: Expired.
* **Blue**: No expiration set.
Name your variable group (e.g., MyVariableGroup). Notes
-----
Add the following variables and mark sensitive variables as secrets: * Ensure that the monitored accounts list is correctly populated with the UPNs of the users whose password expiry you want to track.
* The email notification will only be sent if there are app registrations or Entra ID accounts with upcoming or expired credentials.
AzureWebJobsStorage
AZURE_CLIENT_ID
AZURE_CLIENT_SECRET
AZURE_TENANT_ID
SMTP_SERVER
SMTP_PORT
SMTP_USERNAME
SMTP_PASSWORD
FROM_EMAIL
FROM_NAME
TO_EMAIL
3. **Create a Pipeline from the Azure-pipeline.yaml file in the root of the repo**
4. **Run the Pipeline:**
Trigger the pipeline to deploy the infrastructure and the function app code.