---
order: 2
---
# 将第三方系统页面嵌入到SuccBI

本文讲述如何将第三方系统页面在嵌入到SuccBI页面中系统后，让用户像访问一个系统一样登录访问SuccBI页面。需要进入如下开发配置：

1. 配置开发[单点登录](../../devops/sso/README.md)。
2. 如果SuccBI和第三方系统不是部署在同于个域中，第三方系统还需要[允许跨域](#cors)。

## 示例{#example}

下面以在dashboard中使用iframe展示第三方系统页面为例（需要考虑[跨域问题](#cors)）：

在dashboard编辑界面拖入iframe组件，在iframe的url上填入如下格式的URL：

```md
/api/sso/cert/redirect?redirect_url={第三方系统页面地址}
```

- url上`第三方系统页面地址`需要进行 [URL转义](https://tool.chinaz.com/tools/urlencode.aspx)。示例：

  访问第三方系统地址为`https://example.com/`，经过URL转义后的地址为`https%3A%2F%2Fexample.com`，iframe的url填写的的内容为`/api/sso/cert/redirect?redirect_url=https%3A%2F%2Fexample.com`。
- 考虑到iframe填写的url会比较麻烦，可以考虑[简化url](#simplify-url)。

![iframe](./images/example-dash-iframe.png)

## 简化跳转URL{#simplify-url}

考虑到url上填写的内容会比较复杂，SuccBI提供了授信域名的配置来简化，在系统设置元数据（/sysdata/settings/settings.json）中添加上类似配置:

```json
{
    "sys.trustedDomains": {
        "cert": { // cert为第三方系统起的别名
            "extranet" : "{第三方系统的部署地址}",//需要跳转到第三方系统部署部署地址
            "sso": true// 是否需要添加上数字证书登录的验证信息
        }
    }
}
```

在iframe组件的url中可填写如下格式的url：

```bash
/api/trusted-domains/cert/{第三方系统页面的相对地址}[?{第三方系统页面参数}]
```

示例:

- 第三方系统的部署地址为: `https://example.com`。
- 期望在iframe中访问:`https://exmaple.com/meta/demo?resid=123`。
- 在SuccBI dashboard的iframe所填写url可以是 `/api/trusted-domains/cert/meta/demo?resid=123`。

## 跨域{#cors}

### iframe跨域嵌入第三方系统页面{#cors-iframe}

1. 如果访问SuccBI使用的`https`协议，第三方系统也需要使用`https`协议。
2. iframe嵌入第三方系统的url的请求中，第三方系统应当针对这个请求不设置（不设置默认允许iframe嵌入），或者正确设置响应头[X-Frame-Options](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Headers/X-Frame-Options)。
   比如：`X-Frame-Options`设置为`allow-from https://example.succbi.com`，标识允许访问域名为`https://example.succbi.com`使用iframe嵌入。
3. 如果需要在chrome80以上版本浏览器中使用，还需要针对第三方系统处理[samesite问题](./faq/cookie-samesite.md)。

### 通过ajax跨域访问第三方系统{#cors-requests}

大型业务场景往往由多个系统组成，由于业务需求SuccBI页面中有时候需要使用`ajax请求`跨域请求第三方系统数据。跨域配置要点如下：

1. SuccBI前端`sys.ts`中封装了`ajax`以及其衍生方法`rc`、`rc_get`、`rc1`都提供了跨域请求功能。\
   实现本质上都是针对`XMLHttpRequest`设置了`withCredentials=true`。
2. 第三方系统需要针对SuccBI的跨域请求，添加相关[跨域响应头](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/CORS#access-control-expose-headers)。\
   需要注意的是浏览器在发起跨域请求前，都会发起一个[Preflight请求](https://developer.mozilla.org/zh-CN/docs/Glossary/Preflight_request)，服务器需要正确响应跨域请求和Preflight这两个请求。\
   下面是SuccBI针对跨域请求作出的跨域响应头示例，仅供参考，具体以及原理功能设置请参考[MDN跨域介绍](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/CORS#access-control-expose-headers)：

   ::: details 点击展开查看Preflight响应头示例>>

   ```bash
   Access-Control-Allow-Credentials: true
   Access-Control-Allow-Headers: X-Requested-With,Content-Type
   Access-Control-Allow-Methods: PATCH,PUT,POST,GET,DELETE,HEAD,OPTIONS
   Access-Control-Allow-Origin: https://docs.succbi.com
   Access-Control-Max-Age: 3600
   ```

   :::
   ::: details 点击展开查看跨域请求响应头示例>>

   ```bash
   Access-Control-Allow-Credentials: true
   Access-Control-Allow-Origin: https://docs.succbi.com
   ```

   :::
3. 如果需要在chrome80以上版本浏览器中使用，还需要针对第三方系统处理[samesite问题](./faq/cookie-samesite.md)。