联邦认证

什么是联邦认证

在互联网早期，你的各类账号信息分散在不同的站点和应用，这存在以下问题：

每次访问一个新的站点都要注册一个新的用户名和密码账号。
这个账户就仅仅被存储在这个站点。
你无法在不同的站点下保持登录，用户的信息在不同的站点间也无法互通。

联邦认证通过标准协议将不同的身份提供商联合起来对用户进行认证。联邦是一种身份提供商之间的信任关系，建立联邦关系的身份提供商之间可以通过标准协议互相拉取用户信息。

为什么需要联邦认证

联邦认证是一种分布式的身份认证，当用户在身份提供商登录时，用户可以选择到当前身份提供商信任的联邦身份提供商登录。用户可以通过联邦认证登录一个新的系统，而不必每次在新的系统中注册账号。例如现在许多网站有自己的账密注册登录方式，也有微信扫码直接登录的方式，其中的微信就是这个网站的身份联邦，用户不必填写信息注册账号，直接使用微信就可以登录。

使用联邦认证有以下好处：

用户不必每次都要创建一个全新的账号。
接入联邦认证后用户可以在不同的组织和站点中畅游。

联邦认证原理

以下是联邦认证的过程，用户被重定向到身份联邦进行认证，用户先在身份联邦认证，身份联邦认证向 GenAuth 发送身份断言，等价于用户在 GenAuth 完成认证，GenAuth 再向业务系统发送身份断言，业务系统完成登录。

GenAuth 的联邦认证能力

GenAuth 支持多种标准协议进行联邦认证，你可以使用此应用快速体验。

OAuth2

GenAuth 支持丰富的社会化登录和自定义 OAuth2 身份联邦。

OpenID Connect

GenAuth 支持使用 OIDC 协议进行联邦认证。

SAML2

GenAuth 支持使用 SAML2 协议进行联邦认证。

CAS

GenAuth 支持使用 CAS 协议进行联邦认证。

成为 OpenID Connect 身份源

OpenID Connect 协议简称 OIDC，是一种轻量、安全的身份认证和授权协议。OIDC 是 OAuth 2.0 协议的超集。

OpenID Connect 协议有以下几种授权模式，分别是

授权码模式
隐式模式
混合模式
Client Credentials 模式
密码模式

成为 OpenID Connect 身份源后，其他应用可以使用相应模式的流程完成用户的认证与授权。

你可以在这里深入理解 OIDC 协议。

创建应用

为了让你的应用具备身份认证能力，你需要在 GenAuth 创建一个应用，名称建议填写你的实际应用项目的名称，进入控制台 > 应用 > 应用列表，点击创建应用：

填写你的应用名称，例如：网络笔记项目，为你的项目指定一个认证地址，将来你的用户会在这个地址完成认证。

回调链接填写你的项目后端路由，GenAuth 会将用户信息（确切地说是一个授权码 code）发送到这个地址。最后点击创建。

授权码模式

如果你的应用项目有后端服务，能够安全存储密钥，建议使用授权码模式。

首先在控制台 > 应用，找到你的应用，进入应用详情，在下方的「授权」卡片中，授权模式中勾选 authorization_code，返回类型中勾选 code，然后点击保存。

整体上，有以下流程：

在你的应用中，让用户访问登录链接，浏览器跳转到 GenAuth，用户在 GenAuth 完成认证。
浏览器接收到一个从 GenAuth 服务器发来的授权码。
浏览器通过重定向将授权码发送到你的应用后端。
你的应用服务将授权码发送到 GenAuth 获取 AccessToken 和 IdToken，如果需要，还会返回 refresh token。
你的应用后端现在知道了用户的身份，后续可以保存用户信息，重定向到前端其他页面，使用 AccessToken 调用资源方的其他 API 等等。

流程图如下：

查看接入文档。

授权码 + PKCE 模式

如果你的应用是一个 SPA 前端应用或移动端 App，建议使用授权码 + PKCE 模式来完成用户的认证和授权。授权码 + PKCE 模式适合不能安全存储密钥的场景（例如前端浏览器）。

首先在控制台 > 应用，找到你的应用，进入应用详情，在下方的「授权」卡片中，授权模式中勾选 authorization_code，返回类型中勾选 code，点击保存。在「安全性」卡片中，换取 token 身份验证方式、检验 token 身份验证方式、撤回 token 身份验证方式选择 none 然后点击保存。

整体上，有以下流程。

在你的应用中，让用户访问登录链接，浏览器跳转到 GenAuth，用户在 GenAuth 完成认证。
浏览器接收到一个从 GenAuth 服务器发来的授权码。
浏览器通过重定向将授权码发送到你的应用前端。
你的应用将授权码和校验码发送到 GenAuth 获取 AccessToken 和 IdToken，如果需要，还会返回 Refresh token。
你的应用前端现在知道了用户的身份，后续使用 Access token 换取用户信息，重定向到前端其他页面，使用 AccessToken 调用资源方的其他 API 等等。

流程图如下：

查看接入文档。

隐式模式

如果你的应用是一个 SPA 前端应用，不具备后端服务，建议使用隐式模式来完成用户的认证和授权。隐式模式适合不能安全存储密钥的场景（例如前端浏览器）。在隐式模式中，应用不需要使用 code 换 token，无需请求 /token 端点，AccessToken 和 IdToken 会直接从认证端点返回。

INFO

因为隐式模式用于不能安全存储密钥的场景，所以隐式模式不支持获取 Refresh Token。

首先在控制台 > 应用，找到你的应用，进入应用详情，在下方的「授权」卡片中，授权模式中勾选 implicit，返回类型中勾选 id_token token 和 id_token，然后点击保存。

整体上，有以下流程。

在你的应用中，让用户访问登录链接，浏览器跳转到 GenAuth，用户在 GenAuth 完成认证。
GenAuth 将浏览器重定向到你的应用回调地址，AccessToken 和 IdToken 作为 URL hash 传递。
你的应用从 URL 中取出 token。
你的应用可以将 AccessToken 与 IdToken 保存，以便后续使用，例如携带 AccessToken 访问资源服务器，携带 IdToken 请求服务端从而服务端能够辨别用户身份。

流程图如下：

查看接入文档。

混合模式

在某些场景你可能既希望直接从认证端点获取 token，又能获取授权码 code 用于后续获取 refresh token，建议使用混合模式。在混合模式中，应用会收到 token 与 code。应用可以选择将 code 发送给后端服务，用于从 /token 端点获取用户的 AccessToken、IdToken、refresh token。

首先在控制台 > 应用，找到你的应用，进入应用详情，在下方的「授权」卡片中，授权模式中勾选 authorization_code 和 implicit，返回类型中勾选 code id_token token、code id_token 和 code token，然后点击保存。

整体上，有以下流程。

在你的应用中，让用户访问登录链接，浏览器跳转到 GenAuth，用户在 GenAuth 完成认证。
GenAuth 将浏览器重定向到你的应用回调地址，code、AccessToken、IdToken 作为 URL hash 传递。
你的应用从 URL 中取出 code 和 token。
你的应用可以将 AccessToken 与 IdToken 保存，以便后续使用，例如携带 AccessToken 访问资源服务器，携带 IdToken 请求服务端从而服务端能够辨别用户身份。
你的应用可以将 code 发送给后端。
应用后端可以利用 code 获取用户的 AccessToken、IdToken 以及 refresh token。之后可以保存用户信息，使用 AccessToken 调用资源方的其他 API 等等。

流程图如下：

查看接入文档。

Client Credentials 模式

Client Credentials 模式用于进行服务器对服务器间的授权（M2M 授权），期间没有用户的参与。你需要创建编程访问账号，并将 AK、SK 密钥对交给你的资源调用方。

首先在控制台 > 应用，找到你的应用，进入应用详情，在下方的「授权」卡片中，id_token 签名算法选择 RS256，授权模式中勾选 client_credentials 然后点击保存。

整体上，有以下流程。

资源调用方将他的凭证 AK、SK 以及需要请求的权限 scope 发送到 GenAuth 授权端点。
如果凭证正确，并且调用方具备资源权限，GenAuth 为其颁发 AccessToken。

流程图如下：

查看接入文档。

密码模式

不推荐使用此模式，尽量使用其他模式。只有其他模式都无法解决问题时才会考虑使用密码模式。如果使用密码模式，请确保你的应用代码逻辑非常安全，不会被黑客攻击，否则将会直接泄露用户的账密。一般用于改造集成非常古老的应用，否则绝对不要把它作为你的第一选择。

首先在控制台 > 应用，找到你的应用，进入应用详情，在下方的「授权」卡片中，授权模式中勾选 password 然后点击保存。

整体上，有以下流程。

你的应用让用户输入账密信息。
你的应用将用户账密发送到 GenAuth。
如果账密正确，GenAuth 返回 token。

流程图如下：

查看接入文档。

刷新 Access Token

刷新 Access Token 需要用到 Refresh Token，你可以在这里学习 Refresh Token 相关的内容。Refresh Token 用于获取新的 Access Token，保持用户登录态。

获取 Refresh Token

如果你想获取 Refresh Token ，你需要发送请求到 GenAuth 获取 Refresh Token。

只有授权码模式和密码模式支持 Refresh Token。

下表中展示的授权模式与 Scope 参数组合发送到 Token 端点时，GenAuth 会返回 Refresh Token。

授权模式	Scope
refresh_token	offline_access
password	offline_access

WARNING

注意 ⚠️⚠️⚠️：使用授权码模式时必须在请求授权端点（/oidc/auth）时携带 scope 参数，值必须包含 offline_access，还必须携带 prompt 参数，值必须为 consent。否则 GenAuth 不会返回任何 Refresh Token。

在授权码模式中获取 Refresh Token

在使用授权码模式时，首先需要访问授权端点（/oidc/auth），携带 scope 参数，值必须包含 offline_access，还必须携带 prompt 参数，值必须为 consent，获取一个授权码 Code。然后将授权码发送到 Token 端点，GenAuth 会返回 Access Token、Id Token 和 Refresh Token。查看使用 OIDC 授权码模式了解更多信息。

获取授权码和 Refresh Token 的例子

下面的请求示例可以获取授权码和 Refresh Token，注意 scope 参数中的 offline_access 内容。

http

https://{你的应用域名}/oidc/auth?client_id={应用ID}
&response_type=code
&scope=openid%20profile%20email%20phone%20address%20offline_access
&redirect_uri={回调地址}
&state=4756806

获取 Access Token、Id Token 和 Refresh Token 的例子

下面的请求示例可以从 Token 端点获取到 Access Token、Id Token 和 Refresh Token。code 参数的值是上一步从认证端点返回的授权码。

http

POST https://${你的应用域名}/oidc/token?grant_type=authorization_code
&redirect_uri={回调地址}
&code={授权码}
&client_id={应用ID}
&client_secret={应用密钥}

响应示例

json

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IlRmTE90M0xibjhfYThwUk11ZXNzYW1xai1vM0RCQ3MxLW93SExRLVZNcVEifQ.eyJqdGkiOiJZUHB4NUVEWGlQWVJvNUFQWXAzci0iLCJzdWIiOiI1ZmY3MDFkODQ2YjkyMDNlMmY2YWM2ZjMiLCJpYXQiOjE2MTQwOTE0OTksImV4cCI6MTYxNDA5NTA5OSwic2NvcGUiOiJvZmZsaW5lX2FjY2VzcyBwcm9maWxlIG9wZW5pZCIsImlzcyI6Imh0dHBzOi8vb2lkYzEuYXV0aGluZy5jbi9vaWRjIiwiYXVkIjoiNWYxN2E1MjlmNjRmYjAwOWI3OTRhMmZmIn0.ZN_SlfVg1oNMz7uAK-5K84dqqqmlZehmAPOLytOR9HnLHImKJ9VO5u1hRsAjGCob0kMUV5wVxQhX3EFks7FtMamiX2Jvn-NYh4V_5T6l3LFf4uoKF6AykAg483nG3EEENuGgQo15bBszsoCGqFnNmUd0T4Cgxx0zbxXPxMdp_dcE14KzmNz1w-Qg3yVeYmSTZFdcLtZA2BYnVEa7LYA2yA3DgawwAcRmrlyEfnvCO3uY2TcsTKEAfQ-QgVIGRWOfyUE5f-_X3TolliO1fXnwZBdxEKMXLGW5E2bPVcePyiV0upYbUnQ079UxBlEiWlgeW_rpkTPXDxHAgiE488gtlg",
  "expires_in": 3600,
  "id_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI1ZmY3MDFkODQ2YjkyMDNlMmY2YWM2ZjMiLCJiaXJ0aGRhdGUiOm51bGwsImZhbWlseV9uYW1lIjpudWxsLCJnZW5kZXIiOiJVIiwiZ2l2ZW5fbmFtZSI6bnVsbCwibG9jYWxlIjpudWxsLCJtaWRkbGVfbmFtZSI6bnVsbCwibmFtZSI6bnVsbCwibmlja25hbWUiOm51bGwsInBpY3R1cmUiOiJodHRwczovL2ZpbGVzLmF1dGhpbmcuY28vYXV0aGluZy1jb25zb2xlL2RlZmF1bHQtdXNlci1hdmF0YXIucG5nIiwicHJlZmVycmVkX3VzZXJuYW1lIjpudWxsLCJwcm9maWxlIjpudWxsLCJ1cGRhdGVkX2F0IjoiMjAyMS0wMi0yM1QxNDo0NDoxOC4wODVaIiwid2Vic2l0ZSI6bnVsbCwiem9uZWluZm8iOm51bGwsImF0X2hhc2giOiIxaWRJSUxaWExpZkRscXJMY3ZNeV9BIiwiS0VZIjoiVkFMVUUiLCJhdWQiOiI1ZjE3YTUyOWY2NGZiMDA5Yjc5NGEyZmYiLCJleHAiOjE2MTQwOTUwOTgsImlhdCI6MTYxNDA5MTQ5OSwiaXNzIjoiaHR0cHM6Ly9vaWRjMS5hdXRoaW5nLmNuL29pZGMifQ._H59237sqpsY0OgyY_RM7CvuG6cFo1x03y-DBhd5hik",
  "refresh_token": "3T49f4Y48szoMmwBXragjqLwQZC4QhgnsM5Oy2WfmU-",
  "scope": "openid offline_access profile",
  "token_type": "Bearer"
}

在密码模式中获取 Refresh Token

在密码模式中，你只会用到 Token 端点。查看使用密码模式了解更多信息。

在密码模式的请求参数 scope 中包含 offline_access。

http

POST https://${你的应用域名}/oidc/token?grant_type=password
&client_id={应用ID}
&client_secret={应用密钥}
&username={用户名}
&password={密码}
&scope=openid%20offline_access

响应示例

json

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IlRmTE90M0xibjhfYThwUk11ZXNzYW1xai1vM0RCQ3MxLW93SExRLVZNcVEifQ.eyJqdGkiOiJZUHB4NUVEWGlQWVJvNUFQWXAzci0iLCJzdWIiOiI1ZmY3MDFkODQ2YjkyMDNlMmY2YWM2ZjMiLCJpYXQiOjE2MTQwOTE0OTksImV4cCI6MTYxNDA5NTA5OSwic2NvcGUiOiJvZmZsaW5lX2FjY2VzcyBwcm9maWxlIG9wZW5pZCIsImlzcyI6Imh0dHBzOi8vb2lkYzEuYXV0aGluZy5jbi9vaWRjIiwiYXVkIjoiNWYxN2E1MjlmNjRmYjAwOWI3OTRhMmZmIn0.ZN_SlfVg1oNMz7uAK-5K84dqqqmlZehmAPOLytOR9HnLHImKJ9VO5u1hRsAjGCob0kMUV5wVxQhX3EFks7FtMamiX2Jvn-NYh4V_5T6l3LFf4uoKF6AykAg483nG3EEENuGgQo15bBszsoCGqFnNmUd0T4Cgxx0zbxXPxMdp_dcE14KzmNz1w-Qg3yVeYmSTZFdcLtZA2BYnVEa7LYA2yA3DgawwAcRmrlyEfnvCO3uY2TcsTKEAfQ-QgVIGRWOfyUE5f-_X3TolliO1fXnwZBdxEKMXLGW5E2bPVcePyiV0upYbUnQ079UxBlEiWlgeW_rpkTPXDxHAgiE488gtlg",
  "expires_in": 3600,
  "id_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI1ZmY3MDFkODQ2YjkyMDNlMmY2YWM2ZjMiLCJiaXJ0aGRhdGUiOm51bGwsImZhbWlseV9uYW1lIjpudWxsLCJnZW5kZXIiOiJVIiwiZ2l2ZW5fbmFtZSI6bnVsbCwibG9jYWxlIjpudWxsLCJtaWRkbGVfbmFtZSI6bnVsbCwibmFtZSI6bnVsbCwibmlja25hbWUiOm51bGwsInBpY3R1cmUiOiJodHRwczovL2ZpbGVzLmF1dGhpbmcuY28vYXV0aGluZy1jb25zb2xlL2RlZmF1bHQtdXNlci1hdmF0YXIucG5nIiwicHJlZmVycmVkX3VzZXJuYW1lIjpudWxsLCJwcm9maWxlIjpudWxsLCJ1cGRhdGVkX2F0IjoiMjAyMS0wMi0yM1QxNDo0NDoxOC4wODVaIiwid2Vic2l0ZSI6bnVsbCwiem9uZWluZm8iOm51bGwsImF0X2hhc2giOiIxaWRJSUxaWExpZkRscXJMY3ZNeV9BIiwiS0VZIjoiVkFMVUUiLCJhdWQiOiI1ZjE3YTUyOWY2NGZiMDA5Yjc5NGEyZmYiLCJleHAiOjE2MTQwOTUwOTgsImlhdCI6MTYxNDA5MTQ5OSwiaXNzIjoiaHR0cHM6Ly9vaWRjMS5hdXRoaW5nLmNuL29pZGMifQ._H59237sqpsY0OgyY_RM7CvuG6cFo1x03y-DBhd5hik",
  "refresh_token": "3T49f4Y48szoMmwBXragjqLwQZC4QhgnsM5Oy2WfmU-",
  "scope": "openid offline_access profile",
  "token_type": "Bearer"
}

成为 OAuth 2.0 身份源

OAuth2.0 协议有以下几种授权模式，分别是授权码模式、隐式模式、密码模式。成为 OAuth2.0 身份源后，其他应用可以使用相应模式的流程完成用户的认证与授权。

你可以在这里深入理解 OAuth 2.0 协议。

创建应用

填写你的应用名称，例如：网络笔记项目，为你的项目指定一个认证地址，将来你的用户会在这个地址完成认证。回调链接填写你的项目后端路由，GenAuth 会将用户信息（确切地说是一个授权码 code）发送到这个地址。最后点击创建。

找到你的应用，进入「启用身份提供商」选项卡。

在下方的「OAuth2.0 身份提供商」卡片中，打开启用 OAuth2.0 Provider 开关，然后点击保存。

授权码模式

如果你的应用项目有后端服务，能够安全存储密钥，建议使用授权码模式。

首先在控制台 > 应用，找到你的应用，进入应用详情，进入「启用身份提供商」选项卡，在下方的「OAuth2.0 身份提供商」卡片中，授权模式勾选 authorization_code，然后点击保存。

整体上，有以下流程。

在你的应用中，让用户访问登录链接，浏览器跳转到 GenAuth，用户在 GenAuth 完成认证。
浏览器接收到一个从 GenAuth 服务器发来的授权码。
浏览器通过重定向将授权码发送到你的应用后端。
你的应用服务将授权码发送到 GenAuth 获取 AccessToken，如果需要，还会返回 refresh token。
你的应用后端现在知道了用户的身份，后续可以保存用户信息，重定向到前端其他页面，使用 AccessToken 调用资源方的其他 API 等等。

流程图如下：

查看接入文档。

隐式模式

如果你的应用是一个 SPA 前端应用，不具备后端服务，建议使用隐式模式来完成用户的认证和授权。隐式模式适合不能安全存储密钥的场景（例如前端浏览器）。在隐式模式中，应用不需要使用 code 换 token，无需请求 /token 端点，AccessToken 会直接从认证端点返回。

首先在控制台 > 应用，找到你的应用，进入应用详情，进入「启用身份提供商」选项卡，在下方的「OAuth2.0 身份提供商」卡片中，授权模式勾选 implicit，然后点击保存。

整体上，有以下流程。

在你的应用中，让用户访问登录链接，浏览器跳转到 GenAuth，用户在 GenAuth 完成认证。
GenAuth 将浏览器重定向到你的应用回调地址，AccessToken 作为 URL hash 传递。
你的应用从 URL 中取出 token。
你的应用可以将 AccessToken 保存，以便后续使用，例如使用 AccessToken 获取用户信息，携带 AccessToken 访问资源服务器。

流程图如下：

查看接入文档。

密码模式

首先在控制台 > 应用，找到你的应用，进入应用详情，进入「启用身份提供商」选项卡，在下方的「OAuth2.0 身份提供商」卡片中，授权模式勾选 password，然后点击保存。

整体上，有以下流程。

你的应用让用户输入账密信息。
你的应用将用户账密发送到 GenAuth。
如果账密正确，GenAuth 返回 token。

流程图如下：

查看接入文档。

成为 SAML2 身份源

本文讲述如何在 GenAuth 开启 SAML2 身份提供商，为其他服务商提供身份断言。可以通过 SAML2 协议将 GenAuth 与第三方应用集成。你可以在这里深入理解 SAML2 协议。

创建应用

填写你的应用名称，例如：阿里云测试，随意填写一个认证地址，最后点击「创建」按钮：

配置 SAML2 身份提供商

为了将你的组织与用户用于 SAML2 身份认证，你需要开启应用的 SAML2 身份提供商并进行配置。找到你的应用，进入「启用身份提供商」选项卡。

在「SAML2 身份提供商」卡片中，打开启用 SAML2 Provider 开关，填写默认 ACS 地址和设置信息。然后点击保存。具体的 ACS 地址 SAML SP 方会提供，具体的设置项需要根据 SAML SP 方的要求进行配置。

INFO

当你在 GenAuth 创建 SAML2 IdP 时，有的 SP 可能会先要求你上传 IdP 的元数据文档，才会为你提供相应的配置信息。此时建议先填写一个任意的 ACS 地址和默认的设置信息。然后下载 GenAuth 的 IdP 元数据文档上传到 SP 方。然后再将 ACS 地址和设置信息修改为从 SP 获得的正确内容。

默认 ACS 地址：SAML2 Identity Provider 默认会将 SAML Response 发送到 SAML Request 中指定的消费地址（哪里来的回到哪里去，GenAuth 默认会将 SAML 身份断言发到 SAML Request 中 AssertionConsumerServiceURL 参数指定的地址），如果 SAML Request 中未指定消费地址，GenAuth 会将 SAML Response 发到此处填写的地址。你可以从 SP 处获取到这个地址并填入这里。如果在 SP 处找不到，不妨先随意填写一个，但某些 SP 不会在 SAML Request 中指定消费地址，这种情况下这里必须填写正确的地址。

设置：SAML2 Identity Provider 的高级配置，需要填写一个 JSON 格式的对象，包含以下内容：

key	类型	描述	默认值
samlRequestSigningCert	string	SAML Request 验签证书，你可以从 SP 获得此证书内容。填写此字段后，会认为 SAML Request 经过签名，并检查签名是否合法。如果 SP 未对请求进行签名，GenAuth 会拒绝 SAML Request 导致认证失败。	-
signResponse	boolean	是否对 SAML Response 签名	false
nameIdentifierFormat	string	SAML Response 中的唯一标识符格式。	urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
lifetimeInSeconds	number	SAML 身份断言的过期时间，单位为秒。	3600
authnContextClassRef	string	SAML 身份认证上下文。	urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified
signatureAlgorithm	string	SAML 断言签名算法。	http://www.w3.org/2001/04/xmldsig-more#rsa-sha256
mappings	object	属性映射字典，GenAuth 用户信息中的字段映射到 SAML 身份断言中的映射字典，左侧的 key 代表用户在 GenAuth 中的信息字段，右侧的 value 代表 SAML 身份断言中的属性名。	默认不做字段映射。
destination	string	SAML Response 中的 Destination。	默认为 SAML Request 中的 `AssertionConsumerServiceURL`，如果不存在，就为配置的默认 ACS 地址，若是 IdP 发起登录，可能需要从对接的第三方应用文档中找到此值填入，否则可能登录错误。
recipient	string	SAML Response 中的 recipient。	默认为 SAML Request 中的 `AssertionConsumerServiceURL`，如果不存在，就为配置的默认 ACS 地址，若是 IdP 发起登录，可能需要从对接的第三方应用文档中找到此值填入，否则可能登录错误。
audience	string	SAML Response 中的 audience。	默认为 SAML Request 中的 `AssertionConsumerServiceURL`，如果不存在，就为配置的默认 ACS 地址，若是 IdP 发起登录，可能需要从对接的第三方应用文档中找到此值填入，否则可能登录错误。
emailDomainSubstitution	string	邮件域替换，SAML 断言中的身份标识中的邮箱域名会被替换为这里填写的内容，一些 SP 要求身份断言中的邮件域必须为特定的内容。如果填写此字段，必须禁止用户池注册，否则存在账号冒用风险。	-

示例：

json

{
  "audience": null,
  "recipient": "https://signin.aliyun.com/saml/SSO",
  "destination": "https://signin.aliyun.com/saml/SSO",
  "mappings": {
    "email": "Email",
    "username": "UserName"
  },
  "digestAlgorithm": "http://www.w3.org/2000/09/xmldsig#sha1",
  "signatureAlgorithm": "http://www.w3.org/2000/09/xmldsig#rsa-sha1",
  "authnContextClassRef": "urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified",
  "lifetimeInSeconds": 3600,
  "nameIdentifierFormat": "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified",
  "samlRequestSigningCert": "-----BEGIN CERTIFICATE-----\nMIICyDCCAjGgAwIBAgIBADANBgkqhkiG9w0BAQUFADCBgDELMAkGA1UEBhMCdXMx\nDTALBgNVBAgMBGFzZGYxDTALBgNVBAoMBGFzZGYxGDAWBgNVBAMMD2lkcDMuYXV0\naGluZy5jbjENMAsGA1UEBwwEYXNkZjENMAsGA1UECwwEYXNkZjEbMBkGCSqGSIb3\nDQEJARYMYXNkZkAxMjMuY29tMB4XDTE5MDUyNTA1NTgwMFoXDTIwMDUyNDA1NTgw\nMFowgYAxCzAJBgNVBAYTAnVzMQ0wCwYDVQQIDARhc2RmMQ0wCwYDVQQKDARhc2Rm\nMRgwFgYDVQQDDA9pZHAzLmF1dGhpbmcuY24xDTALBgNVBAcMBGFzZGYxDTALBgNV\nBAsMBGFzZGYxGzAZBgkqhkiG9w0BCQEWDGFzZGZAMTIzLmNvbTCBnzANBgkqhkiG\n9w0BAQEFAAOBjQAwgYkCgYEA2gggFHKUYkoEp83BfGgVjBiev+MIBm+AOuKVqIAX\naJDa1NHL+ApBWsfbKNoPPMy8sZdCBrDm6w5cx9cBjw4uBUap3elxr+MiFoCCc2Eg\nJundFhBVXkU6TafLzfoW4w6/yonmQ798nBKQrTmdc76tpT9xCwU2AmS5ooScQ9Xu\nNn0CAwEAAaNQME4wHQYDVR0OBBYEFMDHVJxYcOlCxnnRi1Lx4tj7gWKNMB8GA1Ud\nIwQYMBaAFMDHVJxYcOlCxnnRi1Lx4tj7gWKNMAwGA1UdEwQFMAMBAf8wDQYJKoZI\nhvcNAQEFBQADgYEAvDodW/ewvCEadY4PCFaBT0ZqoEvrb96hOrbP2hZV4lkCMbLq\noPWASgGTNr9TPnxGCvP9xOv77wzgLs7EAOI+ea1D+NIjUuKnjCLLBv034vMp8bRI\n/Ea9AsGqVCr8tK/3dPoJMxHIjs2cpqNdDcalCZkwBZ1Z0c0YtKIVDFnym5U=\n-----END CERTIFICATE-----",
  "emailDomainSubstitution": "authing.onaliyun.com"
}

自定义 SAML Response 属性：你可以在 SAML 身份断言中加入一些自定义属性，新加入的属性会出现在 SAML 身份断言的 Attribute 中。

示例:

配置自定义 SAML Response 属性

INFO

配置自定义 SAML Response 属性

以上配置，会在 SAML 身份断言中增加以下属性：

xml

<saml:Attribute Name="https://cloud.tencent.com/SAML/Attributes/Role" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
  <saml:AttributeValue
    xmlns:xs="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">qcs::cam::uin/2165337796:roleName/authing,qcs::cam::uin/2165337796:saml-provider/authing
  </saml:AttributeValue>
</saml:Attribute>
<saml:Attribute Name="https://cloud.tencent.com/SAML/Attributes/RoleSessionName" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
  <saml:AttributeValue
    xmlns:xs="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">Test
  </saml:AttributeValue>
</saml:Attribute>

你还可以从 GenAuth 的用户信息上动态读取字段，在一行中最右侧的文本框中输入：My email is ${user.email} and my gender is ${user.gender}。动态读取用户信息字段

INFO

动态读取用户信息字段

该条内容会在 SAML 身份断言中增加以下属性：

xml

<saml:Attribute Name="CustomName" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
  <saml:AttributeValue
    xmlns:xs="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">My email is yezuwei@authing.cn and my gender is M
  </saml:AttributeValue>
</saml:Attribute>

与应用集成

GenAuth 已经与阿里云、腾讯云、华为云、AWS、Kibana（AWS）进行了 SAML2 集成，查看相应的配置文档了解详细步骤。

成为 CAS 身份源

目前 GenAuth 实现了 CAS 1.0 的 /login，/validate，/logout 端点。

你可以在这里深入理解 CAS 协议。

创建应用

填写你的应用名称，例如：网络笔记项目，为你的项目指定一个认证地址，将来你的用户会在这个地址完成认证。回调链接填写你的项目后端路由，GenAuth 会将 Ticket 发送到这个地址。最后点击创建。

找到你的应用，进入「启用身份提供商」选项卡。

在下方的「CAS 身份提供商」卡片中，打开启用 CAS IdP 开关，然后点击保存。

Web flow

在 Web flow 中，整体有以下流程：

用户首次访问 App1。
用户与 App1 未建立会话，被重定向到认证页面。
用户未认证，用户在 CAS Server 完成身份认证。
用户被重定向到 App1 的回调地址，携带 Ticket。
App1 到 CAS Server 查验 Ticket 合法性。
App1 与用户建立会话，返回受保护资源。
用户访问应用 App2。
用户与 App2 未建立会话，被重定向到认证页面。
CAS Server 发现用户已认证，用户被重定向到 App2 的回调地址，携带 Ticket。
App2 到 CAS Server 查验 Ticket 合法性。
App2 与用户建立会话，返回受保护资源。

流程图如下：

查看接入 CAS 1.0 文档。

查看接入 CAS 2.0 文档。

联邦认证 ​

什么是联邦认证 ​

为什么需要联邦认证 ​

联邦认证原理 ​

GenAuth 的联邦认证能力 ​

OAuth2 ​

OpenID Connect ​

SAML2 ​

CAS ​

成为 OpenID Connect 身份源 ​

创建应用 ​

授权码模式 ​

授权码 + PKCE 模式 ​

隐式模式 ​

混合模式 ​

Client Credentials 模式 ​

密码模式 ​

刷新 Access Token ​

获取 Refresh Token ​

在授权码模式中获取 Refresh Token ​

获取授权码和 Refresh Token 的例子 ​

获取 Access Token、Id Token 和 Refresh Token 的例子 ​

响应示例 ​

在密码模式中获取 Refresh Token ​

响应示例 ​

成为 OAuth 2.0 身份源 ​

创建应用 ​

授权码模式 ​

隐式模式 ​

密码模式 ​

成为 SAML2 身份源 ​

创建应用 ​

配置 SAML2 身份提供商 ​

与应用集成 ​

登录阿里云控制台（中国区） ​

登录阿里云控制台（国际区） ​

登录腾讯云控制台 ​

登录 AWS 控制台（中国区） ​

登录华为云控制台（中国区） ​

登录 Kibana 控制台（AWS 中国区） ​

成为 CAS 身份源 ​

创建应用 ​

Web flow ​

联邦认证

什么是联邦认证

为什么需要联邦认证

联邦认证原理

GenAuth 的联邦认证能力

OAuth2

OpenID Connect

SAML2

CAS

成为 OpenID Connect 身份源

创建应用

授权码模式

授权码 + PKCE 模式

隐式模式

混合模式

Client Credentials 模式

密码模式

刷新 Access Token

获取 Refresh Token

在授权码模式中获取 Refresh Token

获取授权码和 Refresh Token 的例子

获取 Access Token、Id Token 和 Refresh Token 的例子

响应示例

在密码模式中获取 Refresh Token

响应示例

成为 OAuth 2.0 身份源

创建应用

授权码模式

隐式模式

密码模式

成为 SAML2 身份源

创建应用

配置 SAML2 身份提供商

与应用集成

登录阿里云控制台（中国区）

登录阿里云控制台（国际区）

登录腾讯云控制台

登录 AWS 控制台（中国区）

登录华为云控制台（中国区）

登录 Kibana 控制台（AWS 中国区）

成为 CAS 身份源

创建应用

Web flow