@aomex-contrib/oauth2-microsoft 0.0.0-stage → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +15 -0
- package/LICENSE +21 -0
- package/README.md +145 -2
- package/dist/index.d.ts +35 -0
- package/dist/index.js +23 -0
- package/dist/index.js.map +1 -0
- package/package.json +41 -3
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
# @aomex-contrib/oauth2-microsoft
|
|
2
|
+
|
|
3
|
+
## 0.1.0
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- [`013319f`](https://github.com/aomex/aomex-contrib/commit/013319f96e95278a693f55708798733412f0a947) Thanks [@geekact](https://github.com/geekact)! - 新增厂商 OAuth2 / OIDC 客户端包:Google、Microsoft、Apple、GitHub、Discord、GitLab、LinkedIn、Facebook、Twitter(X)、Spotify。
|
|
8
|
+
|
|
9
|
+
- 纯 OAuth2 厂商默认 `callback` 返回 `{ base, userinfo }`
|
|
10
|
+
- Apple:`form_post` + JWT `client_secret`;默认 profile 为 `{ claims, user }`(`user` 仅首次授权可能有姓名)
|
|
11
|
+
|
|
12
|
+
### Patch Changes
|
|
13
|
+
|
|
14
|
+
- Updated dependencies [[`013319f`](https://github.com/aomex/aomex-contrib/commit/013319f96e95278a693f55708798733412f0a947)]:
|
|
15
|
+
- @aomex-contrib/oauth2-preset@0.1.0
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2023-2024 geekact
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,146 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @aomex-contrib/oauth2-microsoft
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Microsoft / **Entra ID(Azure AD)OIDC** 登录预设。默认租户为 `common`(个人 Microsoft 账号 + 任意组织目录均可尝试登录)。省略 `onProfile` 时,`callback` 返回**已验签**的 `id_token` claims。
|
|
4
|
+
|
|
5
|
+
官方文档:[Microsoft identity platform / OIDC](https://learn.microsoft.com/entra/identity-platform/v2-protocols-oidc)。
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## 1. 安装
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
pnpm add @aomex-contrib/oauth2-microsoft @aomex/oauth2-client
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
---
|
|
16
|
+
|
|
17
|
+
## 2. Entra 后台准备
|
|
18
|
+
|
|
19
|
+
1. 打开 [Azure 门户](https://portal.azure.com/) →「Microsoft Entra ID」→「应用注册」→「新注册」
|
|
20
|
+
2. 名称随意;「受支持的帐户类型」按产品选择:
|
|
21
|
+
- 仅本组织 → 单租户
|
|
22
|
+
- 任意组织目录 → `organizations`
|
|
23
|
+
- 组织 + 个人 MSA → `common`(与本包默认一致)
|
|
24
|
+
- 仅个人 Microsoft 账号 → `consumers`
|
|
25
|
+
3. 「重定向 URI」平台选 **Web**,填:
|
|
26
|
+
`https://example.com/oauth/microsoft/callback`
|
|
27
|
+
4. 创建完成后:
|
|
28
|
+
-「概览」复制 **应用程序(客户端)ID** → `clientId`
|
|
29
|
+
-「证书和密码」→ 新建客户端密码 → 复制**值**(不是 ID)→ `clientSecret`
|
|
30
|
+
5. (可选)「API 权限」确认有 `openid` / `profile` / `email`;`offline_access` 用于 refresh
|
|
31
|
+
|
|
32
|
+
| 环境变量建议 | 对应 |
|
|
33
|
+
| ------------------ | -------------------- |
|
|
34
|
+
| `MS_CLIENT_ID` | 应用程序(客户端)ID |
|
|
35
|
+
| `MS_CLIENT_SECRET` | 客户端密码的「值」 |
|
|
36
|
+
|
|
37
|
+
---
|
|
38
|
+
|
|
39
|
+
## 3. 租户 / issuer
|
|
40
|
+
|
|
41
|
+
本包默认:
|
|
42
|
+
|
|
43
|
+
```ts
|
|
44
|
+
issuer: 'https://login.microsoftonline.com/common/v2.0';
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
若应用是**单租户**,或必须限制为某一目录,请覆盖 `oidc.issuer`:
|
|
48
|
+
|
|
49
|
+
```ts
|
|
50
|
+
const ms = new MicrosoftOAuth2Client({
|
|
51
|
+
clientId: process.env.MS_CLIENT_ID!,
|
|
52
|
+
clientSecret: process.env.MS_CLIENT_SECRET!,
|
|
53
|
+
redirectUri: 'https://example.com/oauth/microsoft/callback',
|
|
54
|
+
store: new CacheMemoryAdapter(),
|
|
55
|
+
oidc: {
|
|
56
|
+
// 把 {tenant} 换成你的租户 ID 或域名,例如 contoso.onmicrosoft.com
|
|
57
|
+
issuer: 'https://login.microsoftonline.com/{tenant}/v2.0',
|
|
58
|
+
},
|
|
59
|
+
});
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
`common` / `organizations` / `consumers` / 具体 tenant 必须与「应用注册」里帐户类型匹配,否则登录页或验签会失败。
|
|
63
|
+
|
|
64
|
+
---
|
|
65
|
+
|
|
66
|
+
## 4. store
|
|
67
|
+
|
|
68
|
+
保存 OAuth **`state`**(及基类可能用到的 PKCE 数据)。生产多实例请用 Redis 等共享 `CacheAdapter`。
|
|
69
|
+
|
|
70
|
+
---
|
|
71
|
+
|
|
72
|
+
## 5. 最小可跑通示例
|
|
73
|
+
|
|
74
|
+
```ts
|
|
75
|
+
import { CacheMemoryAdapter } from '@aomex/cache/memory';
|
|
76
|
+
import { MicrosoftOAuth2Client } from '@aomex-contrib/oauth2-microsoft';
|
|
77
|
+
|
|
78
|
+
const ms = new MicrosoftOAuth2Client({
|
|
79
|
+
clientId: process.env.MS_CLIENT_ID!,
|
|
80
|
+
clientSecret: process.env.MS_CLIENT_SECRET!,
|
|
81
|
+
redirectUri: 'https://example.com/oauth/microsoft/callback',
|
|
82
|
+
store: new CacheMemoryAdapter(),
|
|
83
|
+
// 默认 scopes: openid profile email offline_access
|
|
84
|
+
});
|
|
85
|
+
|
|
86
|
+
router.get('/oauth/microsoft', {
|
|
87
|
+
action: async (ctx) => {
|
|
88
|
+
await ms.redirect(ctx);
|
|
89
|
+
},
|
|
90
|
+
});
|
|
91
|
+
|
|
92
|
+
router.get('/oauth/microsoft/callback', {
|
|
93
|
+
action: async (ctx) => {
|
|
94
|
+
const claims = await ms.callback(ctx);
|
|
95
|
+
// claims.sub / oid / preferred_username / email …
|
|
96
|
+
ctx.send(claims);
|
|
97
|
+
},
|
|
98
|
+
});
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
---
|
|
102
|
+
|
|
103
|
+
## 6. 默认返回什么
|
|
104
|
+
|
|
105
|
+
`MicrosoftIdTokenClaims` 常见字段:
|
|
106
|
+
|
|
107
|
+
| 字段 | 含义 |
|
|
108
|
+
| -------------------------------------- | ----------------------------------- |
|
|
109
|
+
| `sub` | 主体标识 |
|
|
110
|
+
| `oid` | 目录中的对象 ID(常用作稳定用户键) |
|
|
111
|
+
| `tid` | 租户 ID |
|
|
112
|
+
| `preferred_username` / `email` / `upn` | 登录名相关 |
|
|
113
|
+
| `name` | 显示名 |
|
|
114
|
+
|
|
115
|
+
```ts
|
|
116
|
+
onProfile: async ({ oidc }) =>
|
|
117
|
+
findOrCreateUser({ microsoftOid: oidc.claims.oid ?? oidc.claims.sub }),
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
---
|
|
121
|
+
|
|
122
|
+
## 7. 默认预设
|
|
123
|
+
|
|
124
|
+
```ts
|
|
125
|
+
import { microsoft } from '@aomex-contrib/oauth2-microsoft';
|
|
126
|
+
// microsoft.oidc.issuer、microsoft.scopes
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
默认 scopes:`openid`、`profile`、`email`、`offline_access`。
|
|
130
|
+
|
|
131
|
+
---
|
|
132
|
+
|
|
133
|
+
## 8. 常见问题
|
|
134
|
+
|
|
135
|
+
**Q: AADSTS50011 redirect URI 不匹配?**
|
|
136
|
+
A: 门户里登记的 Web 重定向 URI 必须与代码完全一致。
|
|
137
|
+
|
|
138
|
+
**Q: 单租户应用却用 common?**
|
|
139
|
+
A: 把 `oidc.issuer` 改成该租户的 `.../{tenantId}/v2.0`。
|
|
140
|
+
|
|
141
|
+
**Q: 没有 refresh_token?**
|
|
142
|
+
A: 确认 scope 含 `offline_access`,且应用类型 / 权限允许。
|
|
143
|
+
|
|
144
|
+
---
|
|
145
|
+
|
|
146
|
+
通用能力见:https://aomex.js.org
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
import { OAuth2Client } from "@aomex/oauth2-client";
|
|
2
|
+
import { OidcVendorOptions, OidcVendorOptionsWithOnProfile, OidcVendorOptionsWithOnProfile as OidcVendorOptionsWithOnProfile$1, OidcVendorOptionsWithoutOnProfile, OidcVendorOptionsWithoutOnProfile as OidcVendorOptionsWithoutOnProfile$1 } from "@aomex-contrib/oauth2-preset";
|
|
3
|
+
/**
|
|
4
|
+
* Microsoft / Entra ID OIDC `id_token` 扩展声明(在标准 claims 之上)
|
|
5
|
+
* @see https://learn.microsoft.com/entra/identity-platform/id-token-claims-reference
|
|
6
|
+
*/
|
|
7
|
+
export type MicrosoftIdTokenClaims = OAuth2Client.IdTokenClaims & {
|
|
8
|
+
/**
|
|
9
|
+
* 目录中的对象 ID(Object ID);同一用户跨应用稳定,常作业务主键
|
|
10
|
+
*/
|
|
11
|
+
readonly oid?: string;
|
|
12
|
+
/** 租户 ID(Tenant ID) */
|
|
13
|
+
readonly tid?: string;
|
|
14
|
+
/** 主用户名(可能是邮箱、电话或 UPN 等,取决于租户配置) */
|
|
15
|
+
readonly preferred_username?: string;
|
|
16
|
+
/** 用户主体名称(User Principal Name) */
|
|
17
|
+
readonly upn?: string;
|
|
18
|
+
/** 令牌版本(如 `"2.0"`) */
|
|
19
|
+
readonly ver?: string;
|
|
20
|
+
};
|
|
21
|
+
export declare const microsoft: {
|
|
22
|
+
readonly oidc: {
|
|
23
|
+
readonly issuer: 'https://login.microsoftonline.com/common/v2.0';
|
|
24
|
+
};
|
|
25
|
+
readonly scopes: readonly ['openid', 'profile', 'email', 'offline_access'];
|
|
26
|
+
};
|
|
27
|
+
/**
|
|
28
|
+
* Microsoft / Entra ID OIDC 客户端;省略 `onProfile` 时 `callback` 返回已验签 claims
|
|
29
|
+
*/
|
|
30
|
+
export declare class MicrosoftOAuth2Client<Profile = MicrosoftIdTokenClaims, Claims extends MicrosoftIdTokenClaims = MicrosoftIdTokenClaims> extends OAuth2Client<Profile, Claims> {
|
|
31
|
+
/** OIDC 且省略 `onProfile`:`callback` 返回已验签 claims */
|
|
32
|
+
constructor(opts: OidcVendorOptionsWithoutOnProfile$1);
|
|
33
|
+
constructor(opts: OidcVendorOptionsWithOnProfile$1<Profile, Claims>);
|
|
34
|
+
}
|
|
35
|
+
export type { OidcVendorOptions, OidcVendorOptionsWithOnProfile, OidcVendorOptionsWithoutOnProfile };
|
package/dist/index.js
ADDED
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
import { OAuth2Client } from "@aomex/oauth2-client";
|
|
2
|
+
import { mergeOidcPreset } from "@aomex-contrib/oauth2-preset";
|
|
3
|
+
// src/index.ts
|
|
4
|
+
const microsoft = {
|
|
5
|
+
oidc: { issuer: "https://login.microsoftonline.com/common/v2.0" },
|
|
6
|
+
scopes: [
|
|
7
|
+
"openid",
|
|
8
|
+
"profile",
|
|
9
|
+
"email",
|
|
10
|
+
"offline_access"
|
|
11
|
+
]
|
|
12
|
+
};
|
|
13
|
+
/**
|
|
14
|
+
* Microsoft / Entra ID OIDC 客户端;省略 `onProfile` 时 `callback` 返回已验签 claims
|
|
15
|
+
*/
|
|
16
|
+
var MicrosoftOAuth2Client = class extends OAuth2Client {
|
|
17
|
+
constructor(opts) {
|
|
18
|
+
super(mergeOidcPreset(microsoft, opts));
|
|
19
|
+
}
|
|
20
|
+
};
|
|
21
|
+
export { MicrosoftOAuth2Client, microsoft };
|
|
22
|
+
|
|
23
|
+
//# sourceMappingURL=index.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["import { OAuth2Client } from '@aomex/oauth2-client';\nimport {\n mergeOidcPreset,\n type OidcVendorOptionsWithOnProfile,\n type OidcVendorOptionsWithoutOnProfile,\n} from '@aomex-contrib/oauth2-preset';\n\n/**\n * Microsoft / Entra ID OIDC `id_token` 扩展声明(在标准 claims 之上)\n * @see https://learn.microsoft.com/entra/identity-platform/id-token-claims-reference\n */\nexport type MicrosoftIdTokenClaims = OAuth2Client.IdTokenClaims & {\n /**\n * 目录中的对象 ID(Object ID);同一用户跨应用稳定,常作业务主键\n */\n readonly oid?: string;\n /** 租户 ID(Tenant ID) */\n readonly tid?: string;\n /** 主用户名(可能是邮箱、电话或 UPN 等,取决于租户配置) */\n readonly preferred_username?: string;\n /** 用户主体名称(User Principal Name) */\n readonly upn?: string;\n /** 令牌版本(如 `\"2.0\"`) */\n readonly ver?: string;\n};\n\nexport const microsoft = {\n oidc: { issuer: 'https://login.microsoftonline.com/common/v2.0' },\n scopes: ['openid', 'profile', 'email', 'offline_access'],\n} as const;\n\n/**\n * Microsoft / Entra ID OIDC 客户端;省略 `onProfile` 时 `callback` 返回已验签 claims\n */\nexport class MicrosoftOAuth2Client<\n Profile = MicrosoftIdTokenClaims,\n Claims extends MicrosoftIdTokenClaims = MicrosoftIdTokenClaims,\n> extends OAuth2Client<Profile, Claims> {\n /** OIDC 且省略 `onProfile`:`callback` 返回已验签 claims */\n constructor(opts: OidcVendorOptionsWithoutOnProfile);\n constructor(opts: OidcVendorOptionsWithOnProfile<Profile, Claims>);\n constructor(\n opts:\n OidcVendorOptionsWithoutOnProfile | OidcVendorOptionsWithOnProfile<Profile, Claims>,\n ) {\n super(mergeOidcPreset(microsoft, opts) as OAuth2Client.OidcWithoutOnProfileOptions);\n }\n}\n\nexport type {\n OidcVendorOptions,\n OidcVendorOptionsWithOnProfile,\n OidcVendorOptionsWithoutOnProfile,\n} from '@aomex-contrib/oauth2-preset';\n"],"mappings":";;;AA0BA,MAAa,YAAY;CACvB,MAAM,EAAE,QAAQ,gDAAgD;CAChE,QAAQ;EAAC;EAAU;EAAW;EAAS;CAAgB;AACzD;;;;AAKA,IAAa,wBAAb,cAGU,aAA8B;CAItC,YACE,MAEA;EACA,MAAM,gBAAgB,WAAW,IAAI,CAA6C;CACpF;AACF"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,44 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@aomex-contrib/oauth2-microsoft",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"description": "Microsoft / Entra ID OIDC 客户端预设",
|
|
5
|
+
"repository": {
|
|
6
|
+
"type": "git",
|
|
7
|
+
"url": "git@github.com:aomex/aomex-contrib.git"
|
|
8
|
+
},
|
|
9
|
+
"homepage": "https://aomex.js.org",
|
|
10
|
+
"license": "MIT",
|
|
11
|
+
"type": "module",
|
|
12
|
+
"sideEffects": false,
|
|
13
|
+
"types": "dist/index.d.ts",
|
|
14
|
+
"exports": {
|
|
15
|
+
".": {
|
|
16
|
+
"types": "./dist/index.d.ts",
|
|
17
|
+
"import": "./dist/index.js"
|
|
18
|
+
},
|
|
19
|
+
"./package.json": "./package.json"
|
|
20
|
+
},
|
|
21
|
+
"files": [
|
|
22
|
+
"dist",
|
|
23
|
+
"LICENSE",
|
|
24
|
+
"package.json",
|
|
25
|
+
"README.md",
|
|
26
|
+
"CHANGELOG.md"
|
|
27
|
+
],
|
|
28
|
+
"publishConfig": {
|
|
29
|
+
"access": "public"
|
|
30
|
+
},
|
|
31
|
+
"peerDependencies": {
|
|
32
|
+
"@aomex/oauth2-client": "^4.3.0"
|
|
33
|
+
},
|
|
34
|
+
"dependencies": {
|
|
35
|
+
"@aomex-contrib/oauth2-preset": "^0.1.0"
|
|
36
|
+
},
|
|
37
|
+
"devDependencies": {
|
|
38
|
+
"@aomex/cache": "^4.3.0",
|
|
39
|
+
"@aomex/common": "^4.3.0",
|
|
40
|
+
"@aomex/oauth2-client": "^4.3.0",
|
|
41
|
+
"@aomex/web": "^4.3.0"
|
|
42
|
+
},
|
|
43
|
+
"scripts": {}
|
|
6
44
|
}
|