Skip to content

Commit

Permalink
Fixing and updating the docs
Browse files Browse the repository at this point in the history
  • Loading branch information
FehintolaObafemi committed Jun 5, 2024
1 parent bde7cac commit 4d5e435
Show file tree
Hide file tree
Showing 3 changed files with 81 additions and 2 deletions.
79 changes: 79 additions & 0 deletions src/Authentication/docs/AT-Pop.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,79 @@
# Microsoft Graph PowerShell SDK: Access Token Proof of Possession (AT PoP) Capability

## Overview

This README provides comprehensive details on the Access Token Proof of Possession (AT PoP) functionality introduced in the Microsoft Graph PowerShell SDK. This feature enhances security by binding tokens to specific HTTP methods and URIs, ensuring they are used only for their intended purposes.

## Table of Contents

- [Key Features](#key-features)
- [Installation](#installation)
- [Configuration](#configuration)
- [Usage Examples](#usage-examples)
- [References](#references)

## Key Features

- **Access Token Proof of Possession (AT PoP)**: This feature binds tokens to specific HTTP methods and URIs, preventing misuse of tokens by ensuring they are used only for the intended HTTP requests.
- **Updated Dependencies**: Compatibility improvements with recent library changes.
- **Enhanced Token Acquisition Options**: Users can now specify the HTTP method and URI during token acquisition to further secure token usage.

### Token acquisition behaviors

| Condition | Unbound (default) | Bound (PoP) |
|-----------|-----------|-----------|
| First sign-in | New token, interactive| New token, interactive |
| Existing token, same URI | No new token, silent | No new token, silent |
| Existing token, different URI | No new token, silent | New token, silent |
| Existing expired token, below max token refreshes | New token, silent | New token, silent |
| Existing expired token, exceeded max refreshes | New token, interactive | New token, interactive |

## Installation

To install the Microsoft Graph PowerShell SDK with the latest updates, use the following command:

```powershell
Install-Module -Name Microsoft.Graph -AllowClobber -Force
```

Ensure you are using the latest version to access the AT PoP functionality.

## Configuration

### Enabling Access Token Proof of Possession

To enable AT PoP, configure the Microsoft Graph SDK options as follows:

```powershell
Set-MgGraphOption -EnableATPoP $true
Connect-MgGraph
```

This configuration ensures that the acquired token is only valid for the specified HTTP method and URI.

## Usage Examples

### Example 1:

```powershell
Set-MgGraphOption -EnableATPoP $true
Connect-MgGraph
Invoke-MgGraphRequest -Method GET https://graph.microsoft.com/v1.0/me -Debug
```

### Example 2:

```powershell
Set-MgGraphOption -EnableATPoP $true
Connect-MgGraph
Invoke-MgGraphRequest -Uri "https://graph.microsoft.com/v1.0/me/sendMail" -Method POST -Debug
```

## References

This README provides a detailed guide on the new AT PoP functionality, offering users the ability to secure their token usage effectively. If you have any questions or need further assistance, please refer to the official [Microsoft Graph PowerShell SDK documentation](https://docs.microsoft.com/en-us/powershell/microsoftgraph/).
2 changes: 1 addition & 1 deletion src/Authentication/docs/Get-MgGraphOption.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
external help file: Microsoft.Graph.Authentication.dll-Help.xml
Module Name: Microsoft.Graph.Authentication
online version: https://learn.microsoft.com/en-us/powershell/module/microsoft.graph.authentication/get-mgenvironment
online version: https://learn.microsoft.com/en-us/powershell/module/microsoft.graph.authentication/get-mggraphoption
schema: 2.0.0
---

Expand Down
2 changes: 1 addition & 1 deletion src/Authentication/docs/Set-MgGraphOption.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
external help file: Microsoft.Graph.Authentication.dll-Help.xml
Module Name: Microsoft.Graph.Authentication
online version: https://learn.microsoft.com/en-us/powershell/module/microsoft.graph.authentication/set-mgenvironment
online version: https://learn.microsoft.com/en-us/powershell/module/microsoft.graph.authentication/set-mggraphoption
schema: 2.0.0
---

Expand Down

0 comments on commit 4d5e435

Please sign in to comment.