This repository contains 3 applications:
- Web Application
- UpdateDevices function app
- UpdateDevices function: applies configuration changes for devices in Delegation Station following enrollment
- StragglerHandler function: re-attempts updates for devices that enrolled but could not be processed due to delays in InTune updating hardware information
- Cleanup function: Cleans up old DB entries related to the hand-off between the UpdateDevices and StragglerHandler functions
- (WIP) InTuneEnrollment function app
These applications can be deployed into Azure App Services (Windows or Linux) or Container Instances via Azure CLI, Visual Studio, or GitHub Actions.
Software is currently built on .NET6 and function apps are using isolated worker model.
The software utilizes a CosmosDB to maintain application data.
- Database Name: DelegationStationData
- Container
- Name: DeviceData
- PartitionKey: /PartitionKey
Note: You can use a different DB and Container name, but you will need to update related configuration values for each of the apps.
From your AzureAD tenant in the Azure portal, add a new app registration.
Name: DelegationStation
Supported account types: Accounts in this organizational directory only
Click on + Add a platform and select Web
Set the following settings and don't forget to hit Save
Add a Redirect URI value to return to the application URL. Example: https://delegationstation.azurewebsites.net/signin-oidc or https://delegationstation.azurewebsites.net/.auth/login/aad/callback
Note: The URL path (/signin-oidc) must match the CallbackPath setting in the Application.
Select ID tokens for the implicit grant and hybrid flows.
Select Accounts in this organizational directory only
Ensure the following Permission is listed under Microsoft.Graph
- User.Read (Delegated)
Click on + Add a permission Select Microsoft Graph Select Application permissions
Add the following permissions:
- Device.ReadWrite.All (Allows for updating of device attributes)
- Directory.Read.All (Allows for listing of AD Groups)
- DeviceManagementManagedDevices.ReadAll (Allows for reading and updating devices)
Once done, ensure that you have been Granted Admin Consent for these permissions.
This assumes you already have a certificate you will be using for authentication.
You will need a .CER/.CRT/.PEM file with the public key for the App Registration.
But you will also need a PFX with the private key (and a set pass phrase) to configure in the Application
- Click on Certificates
- Click on Upload Certificate
- Select the file to upload from your local machine.
- If you do not enter a description, it will use the Subject which you will need to use in the Application Configuration settings.
- Click on Client secrets
- Click on + New client secret
- Store the value in a secure location (key vault is recommended). This will be used in the configuration of the application.
This application utilizes Entra ID groups for accessing the application through claims. Each group that is assigned a role must be configured to be sent as a claim from the enterprise application. Add the following claims to the App registration:
- Navigate to the Token configuration blade.
- Click on + Add groups claim
- Select Security groups OR Groups assigned to the application (recommended for large enterprise companies to avoid exceeding the limit on the number of groups a token can emit)
- For each token type (ID, Access, SAML) select:
- Group ID
- Emit groups as role claims
The Enterprise Application configuration will allow you to restrict designated users and groups to the application.
- From the AD tenant screen in the Azure Portal, select Enterprise Applications
- Click on the App Registration you just created.
- Click on Users and groups
- Add any groups or users who need access to the application.
From your AzureAD tenant in the Azure portal, add a new app registration.
Name: DelegationStationFunction
Supported account types: Accounts in this organizational directory only
Click on + Add a permission Select Microsoft Graph Select Application permissions
Add the following permissions:
- Device.ReadWrite.All (Allows for updating of device attributes)
- Directory.Read.All (Allows for listing of AD Groups)
- DeviceManagementManagedDevices.ReadAll (Allows for reading and updating devices)
- AdministrativeUnit.ReadWrite.All (Allows for updating AUs)
Reduced permissions for monitoring without changes (will log changes, but not have permissions to apply them):
- Device.Read.All
- DeviceManagementManagedDevices.Read.All
This assumes you already have a certificate you will be using for authentication.
You will need a .CER/.CRT/.PEM file with the public key for the App Registration.
But you will also need a PFX with the private key (and a set pass phrase) to configure in the Application
- Click on Certificates
- Click on Upload Certificate
- Select the file to upload from your local machine.
- If you do not enter a description, it will use the Subject which you will need to use in the Application Configuration settings.
- Click on Client secrets
- Click on + New client secret
- Store the value in a secure location (key vault is recommended). This will be used in the configuration of the application.
In order to limit the function app to only be able to update only relevant Security Groups, use one of the following two methods:
- Option 1: Make the App Registration the owner of each of the groups the function app should have permissions to edit
- Option 2: Assign the App Registration a custom role on an AU containing all and only the relevant groups with the following permissions:
- microsoft.directory/groups/members/read
- microsoft.directory/groups.security/members/update
Any groups added to the application under Tags will have to have the service principals permissions added in order to work as expected.
Alternatively, you could add GroupMember.ReadWrite.All to the Graph Permissions granted to the App Registrations, but it is not recommended due to the broad access.
Do not make these changes if using reduced permissions to monitor changes but not apply them.
Use the following environment variables to configure the application. These can be set in the appsettings.json file or in the Azure App Service configuration.
Note that for nested settings, in the portal, the nesting is done via two underscore characters. For example, AzureAd__TenantId or AzureAD__ClientCertificates__CertificateDistinguishedName.
"AzureAd": {
"Instance": "",
"Domain": "",
"TenantId": "",
"ClientId": "",
"CallbackPath": "",
"ClientCertificates": {
"CertificateDistinguishedName": ""
}
}
"Instance": ""
The AuzreAD authentication endpoint. For example, "https://login.microsoftonline.com/"
"Domain": ""
The domain of your AzureAD tenant. For example, "delegationstation.microsoftonline.com"
"TenantId": ""
Can be found in the Azure Portal under Azure Active Directory -> Properties -> Directory ID
Can also be found in the Azure Portal under the App Registration -> Overview -> Directory ID
"ClientId" : ""
Can be found in the Azure Portal under the App Registration -> Overview -> Application (client) ID
"CallbackPath": ""
The path returned to after a successful user login. Must match what is set in the App Registration Authentication settings for the web app.
A typical setting would be "/signin-oidc"
"CertificateDistinguishedName" : ""
The subject name of the certificate to be used for client certificate authentication.
"AzureApp": {
"ClientSecret": ""
}
"ClientSecret": ""
(Optional) Required if not using certificate-based authentication.
Can be found in the Azure Portal under the App Registration -> Certificates & secrets -> Client secrets
"COSMOS_CONNECTION_STRING": ""
Can be found in the Azure Portal under the Cosmos DB -> Keys -> Primary Connection String
"COSMOS_ENDPOINT": ""
Use this setting when using managed-identity based authentication to CosmosDB. This is the URL of the CosmosDB instance.
"COSMOS_DATABASE_NAME" : ""
(Optional) The name of the Cosmos DB database. Default is "DelegationStationData"
"COSMOS_CONTAINER_NAME" : ""
(Opti
8000
onal) The name of the Cosmos DB container. Default is "DeviceData"
"DefaultAdminGroupObjectId" : ""
AzureAD group that contains Administrative users of the application, who can perform additional delegations within the application.
Can be found in the Azure Portal under Azure Active Directory -> Groups -> Group -> Properties -> Object ID
"AzureEnvironment" : ""
Can be set to "AzurePublicCloud", "AzureUSDoD", or "AzureUSGovernment" depending on the environment you are using.
"GraphEndpoint": ""
The URL of the graph instance you will be connecting to.
For example, "https://graph.microsoft.com/"
"AllowedHosts": "*"
"DefaultActionDisable": "false"
(Optional) Can be set to "true" to disable the device if not found in the database. If set to "false" the device will be allowed to connect if not found in the database.
This is only needed if you are connecting to Graph using certificates.
- In Windows Explorer, go to the location of the PFX with the private key.
- Right-click on the file and choose 'Install PFX'
- Choose Current User
- Confirm the correct PFX file is listed and click Next
- Enter password for the private key and click Next
- Click on Place all certificates in the following store and click on Browse...
- Choose Personal
- Review the final screen and choose Finish
- In the Azure Portal, go the Function App resource
- Click on Settings -> Certificates
- Click on Bring your own certificates (.pfx)
- Click on + Add certificate
- Choose Upload certificate (.pfx)
- Enter the file location and password and click on Validate
- Click on Add
*Note: In order to keep the certificates separate the WebApp and Function App need to be deployed in different RGs. Certs are shared across webspaces. More info here: https://learn.microsoft.com/en-us/azure/app-service/app-service-plan-manage#move-an-app-to-another-app-service-plan
Use the local.settings.json.template file to help setup your local configuration file.
When deploying to Azure, these will go in your Configuration Settings or Environment Variables section, which is separate in some versions of the portal.
"AzureEnvironment" : ""
"AzurePublicCloud", "AzureUSDoD", or "AzureUSGovernment" depending on the Azure environment you are using.
"COSMOS_CONNECTION_STRING": ""
Can be found in the Azure Portal under the Cosmos DB -> Keys -> Primary Connection String
"COSMOS_ENDPOINT": ""
Use this setting when using managed-identity based authentication to CosmosDB. This is the URL of the CosmosDB instance.
"COSMOS_DATABASE_NAME" : ""
(Optional) The name of the Cosmos DB database. Default is "DelegationStationData"
"COSMOS_CONTAINER_NAME" : ""
(Optional) The name of the Cosmos DB container. Default is "DeviceData"
"TriggerTime": "0 */15 * * * *"
Cron expression for the frequency of the primary UpdateDevices function. The recommendation is every 15 minutes.
"SHTriggerTime": "0 0 */4 * * *"
"
Cron expression for the frequency of the StragglerHandler function. The recommendation is every 4 hours.
"CleanupTriggerTime": "0 0 */12 * * *"
Cron expression for the frequency of the Cleanup function. The recommendation is to run this twice a day.
"AzureAd:TenantId" : ""
Can be found in the Azure Portal under Azure Active Directory -> Properties -> Directory ID
Can also be found in the Azure Portal under the App Registration -> Overview -> Directory ID
"AzureAd:ClientId" : ""
ClientID of the App Registration you created for this function app.
Can be found in the Azure Portal under the App Registration -> Overview -> Application (client) ID
"AzureApp:ClientSecret" : ""
ClientSecret of the App Registration you created for this function app.
(Optional) Can be found in the Azure Portal under the App Registration -> Certificates & secrets -> Client secrets
Required if you are not going to use Certificate-based authentication.
"CertificateDistinguishedName" : ""
(Optional) If using a certificate in place of a client secret, this the Subject of that certificate.
Can be found in the Azure Portal under the App Registration -> Certificates & secrets -> Client certificates
Will look under CurrentUser\my store for the certificate with the distinguished name.
"GraphEndpoint": ""
The URL of the graph instance you will be connecting to.
For example, "https://graph.microsoft.com/"
"DefaultActionDisable": "false"
(Optional) Can be set to "true" to disable the device if not found in the database. If set to "false" the device will be allowed to connect if not found in the database.
"MaxUpdateDeviceAttempts": "5"
(Optional, set with caution) This setting is used by the StragglerHandler and does not determine the number of attempts for the UpdateDevices function.
This setting is so the StragglerHandler does not start processing a device before UpdateDevices has completed it's attempts.
The default is 5, which is the correct value for using the default UpdateDevices frequency of every 15 minutes.
"MaxStragglerAttempts": "5"
(Optional) The number of times the Straggler Handler will re-attempt to process a device if it encounters errors during processing. Defaults to 5.
This is only needed if you are connecting to Graph using certificates.
- In Windows Explorer, go to the location of the PFX with the private key.
- Right-click on the file and choose 'Install PFX'
- Choose Current User
- Confirm the correct PFX file is listed and click Next
- Enter password for the private key and click Next
- Click on Place all certificates in the following store and click on Browse...
- Choose Personal
- Review the final screen and choose Finish
- In the Azure Portal, go the Function App resource
- Click on Settings -> Certificates
- Click on Bring your own certificates (.pfx)
- Click on + Add certificate
- Choose Upload certificate (.pfx)
- Enter the file location and password and click on Validate
- Click on Add
*Note: In order to keep the certificates separate the WebApp and Function App need to be deployed in different RGs. Certs are shared across webspaces. More info here: https://learn.microsoft.com/en-us/azure/app-service/app-service-plan-manage#move-an-app-to-another-app-service-plan