Skip to content

Latest commit

 

History

History

app-auth

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
GraphTutorialAppOnly.ps1
GraphTutorialAppOnly.ps1
 
 
README.md
README.md
 
 
settings.example.json
settings.example.json
 
 

README.md

How to run the completed project

Prerequisites

To run the script in this folder, you need the following:

  • The Microsoft Graph PowerShell SDK installed on your development machine. (Note: This tutorial was written with PowerShell 7.2.2 and Microsoft Graph PowerShell SDK version 1.9.5. The steps in this guide may work with other versions, but that has not been tested.)
  • A Microsoft work or school account with the Global administrator role.

If you don't have a Microsoft account, you can sign up for the Microsoft 365 Developer Program to get a free Microsoft 365 subscription.

Register an application

  1. Open a browser and navigate to the Azure Active Directory admin center and login using a Global administrator account.

  2. Select Azure Active Directory in the left-hand navigation, then select App registrations under Manage.

  3. Select New registration. Enter a name for your application, for example, PowerShell Graph Tutorial.

  4. Set Supported account types to Accounts in this organizational directory only.

  5. Leave Redirect URI empty.

  6. Select Register. On the application's Overview page, copy the value of the Application (client) ID and Directory (tenant) ID and save them, you will need these values in the next step.

Create a self-signed certificate

The Microsoft Graph PowerShell SDK requires a certificate for app-only authentication. For development purposes, a self-signed certificate is sufficient. You need a certificate with the private key installed on the local machine, and the public key exported in a .CER, .PEM, or .CRT file.

Windows

On Windows, you can use the pki PowerShell module to generate the certificate.

$cert = New-SelfSignedCertificate -Subject "CN=PowerShell App-Only" -CertStoreLocation `
  "Cert:\CurrentUser\My" -KeyExportPolicy Exportable -KeySpec Signature -KeyLength 2048 `
  -KeyAlgorithm RSA -HashAlgorithm SHA256
Export-Certificate -Cert $cert -FilePath "./PowerShellAppOnly.cer"

Linux/MacOS

On Linux or MacOS, you can use OpenSSL to generate the private and public keys, then use PowerShell to install the private key into a certificate store readable by PowerShell.

  1. Generate a new X509 certificate using the following command.

    openssl req -x509 -newkey rsa:2048 -sha256 -days 365 -keyout powershell.pem -out powershell.crt -subj "/CN=PowerShell App-Only"

  2. OpenSSL prompts you for a PEM pass phrase. Enter a pass phrase you will remember.

  3. Create a PFX file using the following command.

    openssl pkcs12 -export -out powershell.pfx -inkey powershell.pem -in powershell.crt

  4. OpenSSL prompts you for the pass phrase for powershell.pem, enter the pass phrase you used in the previous step.

  5. OpenSSL prompts you for an export password. Enter a password you will remember.

  6. Open PowerShell and run the following commands, replacing <export-password> with the export password you used in the previous step.

    using namespace System.Security.Cryptography.X509Certificates
$store = [X509Store]::new('My', 'CurrentUser', 'ReadWrite')
$store.Add([X509Certificate2]::new('./powershell.pfx', '<export-password>', [X509KeyStorageFlags]::PersistKeyS
et))
$store.Dispose()

Update the app registration

  1. In the AAD Admin Center, select API permissions under Manage.

  2. Remove the default User.Read permission under Configured permissions by selecting the ellipses (...) in its row and selecting Remove permission.

  3. Select Add a permission, then Microsoft Graph.

  4. Select Application permissions.

  5. Select User.Read.All, then select Add permissions.

  6. Select Grant admin consent for..., then select Yes to provide admin consent for the selected permission.

  7. Select Certificates and secrets under Manage, then select Certificates.

  8. Select Upload certificate. Upload the PowerShellAppOnly.cer or powershell.crt file you created in the previous step, then select Add.

Configure the sample

  1. Open settings.json and update the values according to the following table.

    Setting Value
    clientId The client ID of your app registration
    clientCertificate The subject of the certificate generated in Create a self-signed certificate. For example, CN=PowerShell App-Only.
    tenantId The tenant ID of your organization

Run the sample

In PowerShell, navigate to the project directory and run the following command.

./GraphTutorialAppOnly.ps1

Note: The scripts included in this sample are not digitally signed. Attempting to run them may result in the following error:

.\GraphTutorialAppOnly.ps1: File C:\Source\GraphTutorialAppOnly.ps1 cannot be loaded. The file C:\Source\GraphTutorialAppOnly.ps1 is not digitally signed. You cannot run this script on the current system. For more information about running scripts and setting execution policy, see about_Execution_Policies at https://go.microsoft.com/fwlink/?LinkID=135170.

If you get this error, use the following commands to unblock the file and temporarily allow unsigned scripts in the current PowerShell session. This will not change the default execution policy, the setting is only effective in the current session.

Unblock-File .\GraphTutorialAppOnly.ps1
Set-ExecutionPolicy Unrestricted -Scope Process