Provide clearer guidance on how to use your own Azure AD app registration to connect to Office 365

[garrytrinder]

Raised from #1460

When using the CLI against a tenant for the first time, users are required to consent to the permissions required by the multi-tenant Azure AD application when using either the device login or username & password flows.

Whilst this is fine in the majority of cases, there are scenarios where this is inconvenient and administrators are not comfortable with granting such permissions to a multi-tenant app in their environment.

In this scenario, administrators will want to provide their own Azure AD app registration to use with the CLI to enable greater control the permissions that are granted.

We should provide an end to end tutorial to help guide users through the process of how to generate a certificate (OS specific), creating their own Azure AD app registration and how to use it with the CLI.

[ashokswain27]

We have a similar use case for the authentication using certificate in CI/CD pipeline. It would be helpful if we can get any documentation for the same.

[tommymaynard]

I could use this document(s), right about... now.

[garrytrinder]

@tommymaynard I've been putting an outline together for this, its rough round the edges but might be enough to help you out, I hope to complete it tomorrow and get it into the docs over the weekend.

As an example, this will guide you through creating custom Azure AD application with only SharePoint Read Access and use it with Office 365 CLI.

Create Azure AD app

Go to Azure Portal
Azure Active Directory -> App Registrations -> New Registration
Name -> CustomPnPOffice365CLI -> Register
Authentication
Platform configurations -> Add a platform
Mobile and desktop applications -> Check https://login.microsoftonline.com/common/oauth2/nativeclient -> Configure
Advanced Settings -> Default Client Type -> Yes (enables Device Code flow)
API Permissions
Add Permission -> SharePoint
Delegated permissions -> AllSites -> AllSites.Read -> Add Permissions
Overview
Application (client) ID -> Copy -> Paste to notepad e.g. e7a14baf-fab4-4baa-a494-303a96bc64b6
Copy -> Directory (tenant) ID -> Paste to notepad e.g. e8954f17-a373-4b61-b54d-45c038fe3188

Set environment variables

Linux/Mac OS (Bash/Zsh)

Persist variables for session
export OFFICE365CLI_AADAPPID=e7a14baf-fab4-4baa-a494-303a96bc64b6
export OFFICE365CLI_TENANT=e8954f17-a373-4b61-b54d-45c038fe3188

Persist variables permanently
Depending on terminal, add the above export lines to .bashrc or .zshrc file in your home directory

Linux/Mac OS (PowerShell Core)

Environment variables set in bash/zsh will persist to pwsh session
Check variable values using
$env:OFFICE365CLI_TENANT
$env:OFFICE365CLI_AADAPPID

PowerShell (Windows 10)

Persist variables for session
$env:OFFICE365CLI_AADAPPID="e7a14baf-fab4-4baa-a494-303a96bc64b6"
$env:OFFICE365CLI_TENANT="e8954f17-a373-4b61-b54d-45c038fe3188"

Persist variables permanently
Search for "Edit the system environment variables" in Start Menu -> Launch
Environment Variables -> User variables for
-> New…
Variable Name -> OFFICE365CLI_AADAPPID
Variable value -> e7a14baf-fab4-4baa-a494-303a96bc64b6
-> OK
-> New
Variable Name -> OFFICE365CLI_TENANT
Variable value -> e8954f17-a373-4b61-b54d-45c038fe3188
-> OK -> OK -> OK

Check variable values using in new PowerShell session
$env:OFFICE365CLI_TENANT
$env:OFFICE365CLI_AADAPPID

Login using Custom AD App

Execute o365 login command
Follow device code flow in browser, login with Office 365 CLI account with appropriate permissions
Review permissions required Azure AD 'Permissions requested' prompt
Notice the name of your custom app and reduced permissions -> Accept to complete login

Invoke command to test permissions

Return to command line
Execute o365 spo site get --url https://<tenant>.sharepoint.com -o json --pretty
Command returns values

[tommymaynard]

@garrytrinder This write up was huge. I know so little about Azure (AWS is more of a specialty at the moment), although I've spent several years consuming and writing everything I can about PowerShell. Anyway, there's no way I could've ever known how to walk though and configure AAD and this app without this assistance. I would've walked away from this project today without it, and I really need something for a CI/CD pipeline that'll run on a Linux container with PowerShell 7.0.0, and interact with SharePoint. I know the goal here wasn't an AAD app setup, as you're more interested in slimming down the required permissions, but it. was. amazing. You should seriously be proud; this needs to live on the Office 365 CLI site. The above information has gotten me to a point where I can run a couple spo get commands. Now to figure out what needs to be changed/set in Azure to run an spo file add command. I"m much closer now to finishing the hardest part of this CI/CD pipeline!

[garrytrinder]

Thank you for your kind words @tommymaynard 😊

I'm glad I was able to help you out and thank you for your honesty. We are really appreciative that you stuck with our project and hope that you will continue to use it in the future. 👍🏻

It will certainly be added to the website in more detail, if you have any other feedback or suggestions around documentation that would help you, we would absolutely love to hear them.