获取用户资料¶
要访问 Authany 账户中的任何应用，每个用户都必须在账户中拥有一份资料。用户资料包含用户的相关信息，例如姓名、联系方式，以及您定义的标准属性和自定义属性。您可以通过以下方式获取和管理用户资料：
说明
OIDC 中 UserProfile 的标准属性是用于表示终端用户身份信息的标准化架构，您不能新增或删除这些属性。如需引入其他属性，请使用自定义属性。
用户资料访问权限¶
访问权限定义了通过 Authany 管理台、User Info 端点或用户设置页面访问用户资料时，哪些信息可以被查看或修改。
针对每种访问用户资料的方式，都可以为每个资料属性单独设置访问权限。例如在下方截图中，Primary Email 属性在管理台的访问权限为 Editable，在 User Info 端点（也称为访问令牌持有者）的访问权限为 Read-only，在用户设置页面的访问权限为 Editable。简单来说，这个例子表示管理员可以在 Authany 管理台中修改 Primary Email，客户端应用可以使用用户的访问令牌查看其 Primary Email，而用户本人可以在用户设置页面编辑自己的 Primary Email。
访问权限选项¶
以下是可以为每个属性、针对特定访问方式设置的访问权限选项。
- Editable： 授予该访问方式查看和修改属性值的权限。
- Read-only： 具有该权限的访问方式只能查看属性值。
- Hidden： 如果某个属性对某种访问方式的权限设为
Hidden，该访问方式将无法查看或修改此属性。
默认情况下，Authany 为标准属性在各种用户资料访问方式下设置了不同的默认访问权限。您可以在 Authany 管理台的用户资料 > 标准属性中查看和配置这些默认访问权限。
对于自定义属性，您可以在管理台的用户资料 > 自定义属性中为每种用户资料访问方式定义访问权限。
每种访问用户资料的方式都属于以下访问权限类别之一：
- Portal Admin Access Right： 用于为管理员用户设置属性在 Authany 管理台中的访问权限。
- Token Bearer Access Right： 用于设置令牌持有者通过 User Info 端点访问属性时的访问权限，可以是 “Hidden” 或 “Read-Only”。
- End-user Access Right： 用于设置终端用户通过默认的用户设置界面访问该属性时的访问权限。
如何获取和管理用户资料¶
前提条件¶
- Authany 账户： 您需要一个 Authany 账户才能跟着本指南操作。如果还没有账户，可以到 Authany 官网免费创建一个。
- 已注册的应用： 您需要在 Authany 中拥有一个已注册的应用（客户端）。
1. 从 Authany UI 管理台获取用户资料¶
这是查看和管理用户资料最快、最简单的方式。
展开以查看具体步骤
查看指定用户的资料： 1. 进入 [Authany 管理台](https://manage.authany.com/)。 2. 进入**用户管理**。 3. 选择要查看资料的用户。 4. 在**用户详情**页面中，您会看到**资料**标签页。
要管理所有用户的标准属性访问权限：
进入**管理台** > **用户资料** > **标准属性**
要管理所有用户的自定义属性访问权限并新增自定义属性：
进入**管理台** > **用户资料** > **自定义属性**，然后点击**新增属性**
2. 从使用 Authany SDK 的应用中获取用户资料¶
Authany 完成身份验证并将控制权交还给您的应用后，会把用户资料提供给应用。大多数开发者更喜欢使用 Authany SDK，通过 fetch user info 函数获取 UserInfo 对象。要开始使用该函数，请阅读与您所选 SDK 对应的快速入门指南。以下是不同 Authany SDK 中调用 fetch user info 函数的代码片段：
try{
const userInfo = await authgear.fetchUserInfo()
// example: output the 'sub' attribute from userInfo to console
// sub is a unique identifier for each user.
// You can read other attributes such as email and phoneNumber depending on your login method
console.log(userInfo.sub)
} catch(e) {
// failed to fetch user info
}
authgear.fetchUserInfo { userInfoResult in
// sessionState is now up to date
// it will change to .noSession if the session is invalid
let sessionState = authgear.sessionState
switch userInfoResult {
case let .success(userInfo):
// read the userInfo if needed
let userId = userInfo.sub
let email = userInfo.email
case let .failure(error):
// failed to fetch user info
// the refresh token maybe expired or revoked
}
authgear.fetchUserInfo(new OnFetchUserInfoListener() {
@Override
public void onFetchedUserInfo(@NonNull UserInfo userInfo) {
// sessionState is now up to date
// read the userInfo if needed
// example: output the 'sub' attribute from userInfo to LogCat
// sub is a unique identifier for each user.
// You can read other attributes such as email and phoneNumber depending on your login method
Log.d("UserID:", userInfo.sub);
}
@Override
public void onFetchingUserInfoFailed(@NonNull Throwable throwable) {
// sessionState is now up to date
// it will change to NO_SESSION if the session is invalid
}
});
try {
UserInfo userInfo = await authgear.getUserInfo();
// read the userInfo if needed
// example: output the 'sub' attribute from userInfo to console
// sub is a unique identifier for each user.
// You can read other attributes such as email and phoneNumber depending on your login method
print(userInfo.sub);
} catch (e) {
// failed to fetch user info
// the refresh token maybe expired or revoked
}
// sessionState is now up to date
SessionState state = authgear.sessionState;
try
{
var userInfo = await authgear.FetchUserInfoAsync()
// example: output the 'sub' attribute from userInfo to console
// sub is a unique identifier for each user.
// You can read other attributes such as email and phoneNumber depending on your login method
console.log(userInfo.sub)
}
catch
{
// failed to fetch user info
// the refresh token maybe expired or revoked
}
说明
如需了解 user info 的结构和可用的用户资料属性，请参阅 UserInfo 页面。
3. 从 Admin API 获取用户资料¶
Authany 提供了一个 Admin API GraphQL 端点，允许应用和服务访问并操作用户资料对象。API Explorer 让用户可以交互式地探索 Admin API。借助 API Explorer，您可以搜索用户资料，或更新其标准属性或自定义属性。以下是具体操作步骤示例：
展开以查看具体步骤
1. 进入**管理台**。 2. 进入**高级** -> **Admin API**。 3. 找到 **GraphiQL Explorer** 部分。 4. 点击 **GraphiQL tool** 链接。
该工具会在新的浏览器标签页中打开。
5. 通过 `email` 搜索用户，并在查询中加入 `standardAttributes` 和 `customAttributes`。例如：
4. 从 OIDC UserInfo 端点获取用户资料¶
OpenID Connect（OIDC）的 UseInfo 端点是一个受保护的资源，当服务提供方出示由您的 Authany Token 端点签发的访问令牌时，该端点会返回用户信息。访问令牌中的作用域决定了 user info 端点响应中会返回哪些用户属性。需要注意的是，openid 作用域必须是访问令牌声明之一。
UserInfo 端点¶
UserInfo 端点会返回已通过身份验证的终端用户的声明（Claims），包括标准资料和自定义属性。
调用 fetch user info 函数会返回 userInfo 对象，其中包含该用户的唯一标识符。
以下是 userInfo 对象中通常包含的一些属性。如果当前用户设置了 email、phoneNumber 等属性以及自定义属性，这些属性也会出现在 userInfo 对象中。
| Key | Type | Description |
|---|---|---|
| isAnonymous | boolean | 表示该用户是否为匿名用户，即未提供任何身份或身份验证器 |
| isVerified | boolean | 表示该用户是否已完成验证要求 |
| sub | string | 该用户在您的 Authany 项目中的唯一标识符 |
要通过 OpenID Connect 的 UserInfo 端点获取用户资料，请按以下步骤操作：
展开以查看具体步骤
要访问用户资料端点，您需要在请求 `/oauth2/userinfo` 的请求头中携带 JWT 访问令牌 我们会在 API 调用中使用 **cURL** 命令，您也可以使用 [Postman](https://www.postman.com/) 或类似工具。 **前提条件** * 确保您已经在 Authany 管理台中注册了一个类型为 **OIDC Client Application** 的应用。 * 确保您已成功将应用配置为使用 Authany 作为 OIDC 提供方。详细步骤请参阅[快速入门指南](../../get-started/start-building.md)。 **步骤 1：获取访问令牌** 您的客户端应用需要为用户获取有效的访问令牌，才能向 UserInfo 端点发起请求。 要获取访问令牌，您需要向 **OpenID 应用的 Token 端点**发起请求，用授权后获得的**授权码**换取访问令牌。 * Token 端点的 URL 通常类似于 `https://curl --request POST \
--url 'https://<YOUR_AUTHGEAR_ENDPOINT>/oauth2/token' \
--header 'content-type: application/x-www-form-urlencoded' \
--data grant_type=authorization_code \
--data code={YOUR_AUTHORIZATION_CODE} \
--data redirect_uri={YOUR_REDIRECT_URI} \
--data 'client_id={YOUR_CLIENT_ID}' \
--data client_secret={YOUR_CLIENT_SECRET} \
--data scope=openid
关于 UserInfo 端点响应的结构和字段说明，请参阅这里。
5. 将用户资料嵌入 JWT 访问令牌¶
借助 Authany WebHooks，您可以将用户资料的标准属性和自定义属性嵌入 OIDC JSON Web Token（JWT）。这样一来，您无需再次调用 UserInfo 端点，就能在返回给 OIDC 客户端的 JWT 中获取这两类资料属性。
详情请参阅我们关于如何向 JWT 访问令牌添加自定义字段的文章。