1. 什么是IDPS？

IDPS是企企管理云为了实现用户身份认证而提供的IDP（Identity Provider身份提供者）身份认证服务。在计算机网络和互联网安全中，身份提供者是一种服务，它允许用户使用单一的身份验证凭据（如用户名和密码、数字证书或双因素身份验证）来访问多个不同的应用程序或系统。

IDPS身份提供者通常是用于认证企企管理员的用户，并将认证结果发送给企企管理云，或者将认证结果发送给需要访问的其他应用程序或系统。

IDPS服务的好处在于，它简化了用户登录的过程，并且可以提供更高的安全性。

2. IDPS能够做什么？

IDPS是企企管理去验证用户身份的服务。它的主要作用是确保用户的身份是真实的，并且只有被授权的用户才能登录到企企管理云的应用，或者通过签发token, 授权外部系统访问企企管理云的资源（Open API)。

IDPS同时提供了SSO单点登录接入的能力, 通过两种方式提供：

IDPS接受第三方的IDP身份凭据，通过第三方的用户身份，与企企管理云中的账号和用户绑定后，即可以使用第三方身份登录企企管理云。
IDPS以企企管理云中的用户凭据，通过签发IDPS的自建应用，在第三方IDP系统中注册后，即可以通过企企管理云的用户身份，访问第三方系统。

3. 目前支持IDP授权协议有哪些？

目前支持的IDP接入协议有： OAuth 2.0和OIDC（OpenID Connect）协议。

OAuth 2.0：OAuth 2.0是一种授权框架，它允许用户授权第三方应用程序代表用户访问他们的资源，例如他们的数据或存储在他们的帐户中的其他信息。OAuth 2.0支持多种授权类型，包括授权代码流、隐式流、客户端凭据流和密码凭据流。它是一种开放标准，广泛应用于各种不同类型的应用程序和服务。

OpenID Connect (OIDC)：OIDC是一个建立在OAuth 2.0授权框架之上的身份验证协议。它允许用户通过第三方身份提供者进行身份验证，而无需向每个应用程序提供单独的凭据。OIDC使用JSON Web Token（JWT）作为身份验证和授权令牌格式。

4. 有关授权协议的相关术语

资源所有者(Resource Owner)：拥有需要被访问的受保护资源的用户或系统。
客户端(Client)：代表用户访问资源的应用程序或服务。
授权服务器(Authorization Server)：OAuth 2.0协议中的服务器，用于向客户端颁发访问令牌。
身份提供者(OP: Open Id Provider)：OIDC协议中的服务器，用于验证用户身份并颁发身份令牌。
访问令牌（Access Token)：OAuth 2.0协议中的令牌，用于访问受保护的资源。
身份令牌(Id Token)：OIDC协议中的令牌，用于验证用户身份并向客户端提供有关用户的信息。
IDPS OpenID相关配置： https://idps.77hub.com/idps/.well-known/openid-configuration

5. 具体的应用场景使用说明

5.1. 场景1) 外部系统通过IDPS身份登录外部系统

a.通过IDPS身份登录流程如下图所示:

b.具体步骤如下：

步骤1：租户管理员/或者开发角色登录idps系统，新建自建应用

    - 应用类型： 自建应用
    - 应用名称： 起一个容易识别的名称（比如： 外部测试系统）
    - 应用所属IDP标识： 在idps中的唯一标识，要求为英文字母开始，标识当前自建应用，比如： testapp1
    - logoUrl: 应用的图标， 可以不设置
    - 重定向的url: 必须设置登录成功后， 回调第三方系统的callback url

 idps系统地址：https://idps.77hub.com
 接着需要记录新建应用的API Key 和Secret Key

自建应用如下图所示：

步骤2： IDPS 认证

2.1. 获取Authorization Code

  第三方系统需要使用idps登录时， 需要通过重定向用户浏览器到 https://idps.77hub.com/idps/auth 地址，并带上以下参数：

  client_id：必要参数，注册应用时获得的API Key。
  response_type：必要参数，此值固定为“code”。
  redirect_uri：必要参数，授权后要回调的URI，即接收Authorization Code的URI。redirect_uri必须与步骤一中的重定向url中的某一个相匹配。
  scope：必要参数，以空格分隔的权限列表，目前idps支持的scope如下：
      - offline_access： 离线访问，会返回refresh_token
      - openid:  返回id token
      - email: 返回email和phone信息
      - profile： 返回用户名称等信息 
  state：非必要参数，用于保持请求和回调的状态，授权服务器在回调时（重定向用户浏览器到“redirect_uri”时），会在Query Parameter中原样回传该参数。OAuth2.0标准协议建议，利用state参数来防止CSRF攻击。

  例如：client_id为n1pRXWNYFa4MQLzpDfHyovFb的应用要请求某个用户的默认权限，并在授权后需跳转到http://localhost:8080/login，同时希望在弹出窗口中展现用户登录、授权界面，则应用需要重定向用户的浏览器到如下URL：

  https://idps.77hub.com/idps/auth?client_id=n1pRXWNYFa4MQLzpDfHyovFb&redirect_uri=http://localhost:8080/login&response_type=code&scope=openid,

  响应数据包格式：
  此时授权服务会根据应用传递参数的不同，为用户展现不同的授权页面。如果用户在此页面同意授权，授权服务则将重定向用户浏览器到应用所指定的redirect_uri，并附带上表示授权服务所分配的Authorization Code的code参数，以及state参数（如果请求authorization code时带了这个参数）。

  例如：继续上面的例子，假设授权服务在用户同意授权后生成的 Authorization Code 为71c279ccd145a3dff977b38e6a8e34b4，则授权服务将会返回如下响应包以重定向用户浏览器到http://localhost:8080/login地址：

  HTTP/1.1 302 Found Location: http://localhost:8080/login?code=71c279ccd145a3dff977b38e6a8e34b4

  注意：每一个Authorization Code的有效期为30分钟，并且只能使用一次，再次使用将无效。

2.2. 通过Authorization Code获取Access Token

通过上面第一步获得Authorization Code后，便可以用其换取一个Access Token。获取方式是：应用在其服务端程序中发送请求（推荐使用POST）到 IDPS授权服务的https://idps.77hub.com/idps/token地址，并带上以下5个必须参数：

      grant_type：必须参数，此值固定为authorization_code。
      code：必须参数，通过上面第一步所获得的Authorization Code。
      client_id：必须参数，应用的API Key。
      client_secret：必须参数，应用的Secret Key。
      redirect_uri：必须参数，该值必须与获取Authorization Code时传递的redirect_uri保持一致。

  响应数据包格式：
  若参数无误，服务器将返回一段JSON文本，包含以下参数：

  access_token：要获取的Access Token。
  expires_in：Access Token的有效期，以秒为单位（默认60分钟的有效期）。
  refresh_token：用于刷新Access Token 的 Refresh Token。
  refresh_token_expires_in：Refresh Token的有效期，以秒为单位（默认7天的有效期，刷一次access token会自动继期）。
  id_token： JWT格式的ID Token信息

  例如：

     {
        "id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6ImVkYTk3N2Q1NWQwYzJiYzY0ZmQxNTZhYmNkZjc1YWQzNWZjNDZlOWUifQ.eyJpc3MiOiJodHRwOi8vdGVzdC5jb206ODA4MC9pZHBzIiwic3ViIjoiQ2dkMWMyVnlhV1F5RWc5Qk4wTldOekkyTVZBMU9ERXdNREkiLCJhdWQiOiJ0ZXN0LWFwcCIsImV4cCI6MTY4MTEwMjYxMiwiaWF0IjoxNjgxMDk5MDEyLCJhdF9oYXNoIjoiTjM4SXZJMkpFRWRpbTYzOU9RUnZtUSIsImVtYWlsIjoid29sZi5qaWFuZ0A3N2h1Yi5jb20iLCJlbWFpbF92ZXJpZmllZCI6dHJ1ZSwicGhvbmVfbnVtYmVyIjoiKzg2MTU2OTk3MzY3MzYiLCJwaG9uZV9udW1iZXJfdmVyaWZpZWQiOnRydWUsIm5hbWUiOiJ0ZXN0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoidGVzdCIsInRlbmFudF9pZCI6InRlbmFudDIiLCJyX2lkIjoiZHZnN2VzcW1uYmVuajJ1NTJrdmtlYXFpcSIsImlzX2Rldl9tYW5hZ2VyIjp0cnVlfQ.QGjUAkMzuBOHZPpK2qM1Qkz6y_2ZUMSg_Ka2YHc8Vi_L19Yr8EyeL7hrd7yZSAs47GPOCF5xUZLA7CzfSAVRDqbuL8LktZYD2-SwCwbtOsZbJVd_rVl1N6hRIiEs6FJwsYUiNA9Xgag-3MLrnfJMUSy5A6AN0AidpCfwYjAaEEaca-lyGlVXv0A1U3hx3JmBzRgNGmNZhlHuI1HHQUNEfQnqLy74JF416Irl_1TQjmdzLkJYVp7dvuuvvVfbSEHZS1C0bKaYbfASFi62UWHLrCdjHYPgIYgUcvQZdtryg4JjMfU1bTxP4kBhdoGsUR1O17izmyX_i3oyknyJhUn7aw",
        "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6ImVkYTk3N2Q1NWQwYzJiYzY0ZmQxNTZhYmNkZjc1YWQzNWZjNDZlOWUifQ.eyJpc3MiOiJodHRwOi8vdGVzdC5jb206ODA4MC9pZHBzIiwic3ViIjoiQ2dkMWMyVnlhV1F5RWc5Qk4wTldOekkyTVZBMU9ERXdNREkiLCJhdWQiOiJ0ZXN0LWFwcCIsImV4cCI6MTY4MTEwMDMxNSwiaWF0IjoxNjgxMDk2NzE1LCJhdF9oYXNoIjoicENScEtVU1pITE1tNkV5MGJQZWpiQSIsImVtYWlsIjoid29sZi5qaWFuZ0A3N2h1Yi5jb20iLCJlbWFpbF92ZXJpZmllZCI6dHJ1ZSwicGhvbmVfbnVtYmVyIjoiKzg2MTU2OTk3MzY3MzYiLCJwaG9uZV9udW1iZXJfdmVyaWZpZWQiOnRydWUsIm5hbWUiOiJ0ZXN0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoidGVzdCIsInRlbmFudF9pZCI6InRlbmFudDIiLCJyX2lkIjoiaGF2NmtjZmdpZWhyN2dzMmJjdTN5eG9uaSIsImlzX2Rldl9tYW5hZ2VyIjp0cnVlfQ.G5Ur2dCwBlCow7F1rgwiCaBTnPzOzNxZcq7TjuU66GViS-vxMI4nwsPdPnuNYy8dmfj4h8nkInpUBFiM3xMkPqnDqqyFqxxyPNrmmQcgY3Y6mjoChD6GjULvm01PpeQBrsrCvxwGzichEHKSfmqVyQCgkBRDQopfMOe6KRWZemHFQbAt5dfIkSrpsWpk1SZQ0b5AZ9b5s186pVwGnzVgLNzKGz47HWZSxEKLO4Xa-2SKj0CykMR9pePrHq7x-U0KfY00oRdQDgKxmA0-uqN6CirIjHe5_qUic_5YckuZ252hWvjH_d0brDXfl043ObA1I1CIbvPFWgc03QAyEWZ0Eg",
        "expires_in": 3599,
        "refresh_token": "ChloYXY2a2NmZ2llaHI3Z3MyYmN1M3l4b25pEhllamJqdDJzYW11dG5ubHF5bWFjZjJjZzV2",
        "refresh_token_expires_in": 604799
     }

  若请求错误，服务器将返回一段JSON文本，包含以下参数：

      error：错误码。
      error_description：错误描述信息，用来帮助理解和解决发生的错误。

https://idps.77hub.com/idps/token 接口postman请求示例如下：

2.3.使用Access Token/ID Token获取IDPS用户的基本资料

使用上面得到的Access Token/Id Token通过https://idps.77hub.com/idps/userinfo 信息用户的基本资料，包括如下信息：

{
    "account_id": "test1", //用户在IDPS上的账号标识
    "app_id": "A7CV7261P581002", //发放token的应用标识
    "cluster_id": "cn-northweast-1", //租户所在的集群标识
    "email": "wolf.jiang@77hub.com", //账号关联邮箱
    "is_dev_manager": true,  //用户是否为开发管理角色
    "name": "test",  //用户名
    "phone_number": "+8615699736736", //账号关联的角色
    "preferred_username": "test", //用户名
    "r_id": "dvg7esqmnbenj2u52kvkeaqiq", //refersh_token内部标识
    "tenant_id": "tenant2", //租户ID
    "tenant_name": "用于测试租户2", //租户名称
    "user_id": "userid2" //租户中的用户ID
}

https://idps.77hub.com/idps/userinfo 接口postman请求示例如下：

步骤3：

第三方系统需要将从步骤二2.3获取的用户信息与当前系统用户建立绑定关系，下次在通过IDPS进行认证时，回调取得用户信息，找到绑定的用户，即可直接进入到第三方系统。

5.2. 场景2) 企企管理云通过IDPS身份登录外部系统

该场景需要外部系统提供基于idp code的登录方式，即通过指定idp code（代表idp身份认证服务的code, 比如idps), 从第三方系统直接针对 idp code对应的idp发起认证请求，发起的过程与1）一致，这样，从企企云跳转到外部系统，只需要在浏览器中打开第三方系统的认证url, 比如： http://localhost:8080/idps/login, 则外部系统则会反过来向idps发起认证请求，实现以idps的身份登录到第三方系统的过程。

5.3. 场景3) 企企管理云通过IDPS绑定的第三方IDP身份登录企企云

目前idps支持的第三方IDP身份协议为OAtuh2.0和OIDC协议！

a. 通过IDPS 绑定的第三方账号登录流程如下图所示： b. 具体步骤如下：

步骤一

用户到第三方IDP创建应用，设置Redirect URI为企企IDPS的回调地址：https/idps.77hub.com/idps/callback。如果租户在idps设置了自己的子域名（比如test1.tenant.77hub.com）或者顶级域名（比如test1.com), 则可以使用对应的域名加上“/idps/callback做为回调地址。接着需要记录新建应用的API Key 和Secret Key，同时查询对应的第三方的IDP的授权协议（OAuth或者OIDC)：如果是OAuth协议，需要记录对应的授权url和token url，及支持的scopes信息等如果是OIDC协议，需要记录对应的issuer url, 及支持的scopes信息等

可以以Authing或者Okta为例进行测试。

以authing为例创建应用如下图所示：

以okta为例创建应用如下图所示：

步骤二：租户管理员/或者开发角色登录idps系统，新建外部应用

    - 应用类型： 外部应用
    - 应用名称： 起一个容易识别的名称，用于显示在外部IDP中进行授权识别（比如： 企企云认证应用）
    - 应用所属IDP标识： 在idps中的唯一标识，通常可以代表idp身份，比如okta或者authing等
    - logoUrl: 显示在登录页面的的图标
    - 接入方式：OIDC/OAUTH
    - ClientID/ClientSecret: 第一步申请的外部应用的clientID和sercret信息
    - 是否支持离线请求： 通常用于获取第三方系统的refresh token，保存做为离线访问使用（对于单点登录暂无用处理）
    - OIDC的其他配置
        - Issuer: OIDC认证服务的issuer url
        - 授权范围： 即scope信息， 默认为profile和emal,可以填写idp支持的scope, 如果需要实现集成，需要授权offline_access, 多个值以半角逗号分隔
        - 认证Claims中的用户名Key: 如果不是name, 则需要指定，否则取不到第三方IDP的用户名

Idps创建外部应用

步骤三：使用第三方用户身份登录企企云

 由于外部应用是按租户绑定的，因此需要知道当前租户才能够使用第三方IDP登录, 目前有两种方式：
 1. 使用标准域名加上租户ID进入登录页面， 例如： https://idps.77hub.com/idps/auth/local?tenant_id={tenant}
 2. 使用租户子域名，或者顶级域名进入登录页面 https://子域名.tenant.77hub.com/idps/auth
 进入登录页后，会在登录下面的选项出现第三方登录的图标， 点击即可实现第三方登录。 如果首次登录，需要在第三方回调回来的页面，输入绑定企企云的用户，则后继可以实现第三方IDP直接登录。

首次登录实现如下：

1.首次登录，登录界面以及第三方登录图标

2.点击第三方登录的图标，进入第三方登录界面

3.登录后重定向到IDPS登录界面

4.IDPS登录后进入授权界面

5.同意授权后，进入企企云

5.4. 场景4) 外部系统通过IDPS绑定的第三方IDP身份登陆企企云

主要过程与场景3）类似，只是在步骤三， 从第三方应用跳转企企云时, 需要指定idpCode, 比如使用的idp code是okta, 则， 跳转url为：
1. 使用标准域名加上租户ID， 例如： https://idps.77hub.com/idps/auth/okta?tenant_id={tenant}
2. 使用租户子域名，或者顶级域名, 例如： https://子域名.tenant.77hub.com/idps/auth

如果登录后希望自动打开指定的页面，需要提供param标识跳转的路径， param的值是一个url query字符串，比如: objectType=Reimburse&objectId=id1 (需要url encode), 表示跳到报销的的id1对应的详情页， 具体的路径参数是所有前端支持的路径

如果当前已登录，则直接登录，如果当前没有登录，则会进入单点登录界面

5.5. 场景5) 外部系统通过IDPS绑定的第三方IDP身份登录外部系统

按场景3）的前两步骤创建第三方idp登录认证， 然后按场景1）进行操作，只是在步骤二授权的url增加idpCode, 例如： https://idps.77hub.com/idps/auth/okta

5.6. 场景6) 企企管理云通过IDPS绑定的第三方IDP身份登录外部系统

步骤一：需要按场景3）的步骤一、二创建企企管理员上的第三方认证登录，比如通过okta登录。

步骤二：需要外部系统提供基于idp code的登录方式，即通过指定idp code（代表idp身份认证服务的code, 比如idps), 从第三方系统直接针对 idp code对应的idp发起认证请求，发起的过程与场景1）一致，从企企云跳转到外部系统，只需要在浏览器中打开第三方系统的认证url, 比如： http://localhost:8080/idps/login, 则外部系统则会反过来向idps发起认证请求，实现以idps的身份登录到第三方系统的过程。

外部系统发直的idps认证请求时，使用的授权url有两种方式：
1. 使用标准域名加上租户ID， 例如： https://idps.77hub.com/idps/auth/okta?tenant_id=tenant1
2. 使用租户子域名，或者顶级域名, 例如： https://test1.tenant.77hub.com/idps/auth

5.7. 场景7) （TODO)企企管理云通过IDPS获取第三方系统token访问第三方系统Open API

该功能暂不能提供

5.8. 场景8) 外部系统通过IDPS获取token访问企企管理云Open API

按场景1）取得ID Token和RefreshToken信息，通过ID Token即可访问OpenAPI接口，当ID Token过期时，需要使用保存的RefreshToken刷新ID token。刷新ID Token

6. 子域名设置

子域名设置，可登录idps系统，idps系统地址：https://idps.77hub.com , 登录后点击用户名 ,进入租户设置即可设置子域名

子域名设置如下图所示：

IDPS用户手册