From ca37836bc2b3ef4e0a10cb05b3e11edde6daa2de Mon Sep 17 00:00:00 2001
From: Paul Schreiber <github@paulschreiber.com>
Date: Wed, 14 Feb 2024 13:47:24 -0500
Subject: [PATCH] Add documentation for Microsoft SSO (#919)

* docs: Add Microsoft docs

* docs: add link to Microsoft docs
---
 README.md                         |  1 +
 docs/config-examples/microsoft.md | 29 +++++++++++++++++++++++++++++
 2 files changed, 30 insertions(+)
 create mode 100644 docs/config-examples/microsoft.md

diff --git a/README.md b/README.md
index 43d23213..bb704826 100644
--- a/README.md
+++ b/README.md
@@ -35,6 +35,7 @@ These providers are OpenID compliant, which means you can use [autodiscovery](ht
 - [Azure Active Directory](https://docs.microsoft.com/en-us/azure/active-directory) ([Example configuration](./docs/config-examples/azure-active-directory.md))
 - [AWS Cognito](https://eu-west-1.console.aws.amazon.com/cognito) ([Example configuration](./docs/config-examples/aws-cognito.md))
 - [Asgardeo](https://asgardeo.io) ([Example configuration](./docs/config-examples/asgardeo.md))
+- [Microsoft](https://learn.microsoft.com/en-us/entra/identity-platform/v2-protocols-oidc) ([Example configuration](./docs/config-examples/microsoft.md))
 
 ## Tested OAuth2 providers
 
diff --git a/docs/config-examples/microsoft.md b/docs/config-examples/microsoft.md
new file mode 100644
index 00000000..9713ea00
--- /dev/null
+++ b/docs/config-examples/microsoft.md
@@ -0,0 +1,29 @@
+## Microsoft
+
+1. Supplying "issuer" fails, because Microsoft returns `issuer` with the literal string `https://login.microsoftonline.com/{tenantid}/v2.0` when `https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration` is queried.. We need to manually specify `serviceConfiguration`.
+
+2. `REDIRECT_URL` varies based on platform:
+   - iOS: msauth.com.example.app://auth/
+   - Android: com.example.app://msauth/<SIGNATURE_HASH>/
+
+3. Microsoft does not have. revocationEndpoint.
+
+```js
+const config = {
+  serviceConfiguration: {
+    authorizationEndpoint: 'https://login.microsoftonline.com/common/oauth2/v2.0/authorize',
+    tokenEndpoint: 'https://login.microsoftonline.com/common/oauth2/v2.0/token',
+  },
+  clientId: '<APPLICATION_ID>',
+  redirectUrl: '<REDIRECT_URL>',
+  scopes: ['openid', 'profile', 'email', 'offline_access'],
+};
+
+// Log in to get an authentication token
+const authState = await authorize(config);
+
+// Refresh token
+const refreshedState = await refresh(config, {
+  refreshToken: authState.refreshToken,
+});
+```