This is an automated email from the ASF dual-hosted git repository.
benjobs pushed a commit to branch dev
in repository
https://gitbox.apache.org/repos/asf/incubator-streampark-website.git
The following commit(s) were added to refs/heads/dev by this push:
new d876547 Add document for SSO (#241)
d876547 is described below
commit d87654730210817bbc62f91d7e66b66e8376a928
Author: Leomax_Sun <[email protected]>
AuthorDate: Fri Sep 8 11:24:56 2023 +0800
Add document for SSO (#241)
---
docs/user-guide/10-SSO.md | 90 ++++++++++++++++++++
.../current/user-guide/10-SSO.md | 91 +++++++++++++++++++++
.../doc/image/sso/existing-user-login-process.png | Bin 0 -> 79579 bytes
static/doc/image/sso/github-login.png | Bin 0 -> 29176 bytes
static/doc/image/sso/google-login.png | Bin 0 -> 50455 bytes
static/doc/image/sso/login-success-redirect.png | Bin 0 -> 66393 bytes
static/doc/image/sso/new-user-login-process.png | Bin 0 -> 75944 bytes
.../doc/image/sso/user-login-sso-not-enabled.png | Bin 0 -> 42047 bytes
8 files changed, 181 insertions(+)
diff --git a/docs/user-guide/10-SSO.md b/docs/user-guide/10-SSO.md
new file mode 100644
index 0000000..a363e11
--- /dev/null
+++ b/docs/user-guide/10-SSO.md
@@ -0,0 +1,90 @@
+---
+id: 'SSO'
+title: 'SSO Integration'
+sidebar_position: 10
+---
+
+## Background
+As an enterpise practice, it's common to apply Single sign-on (SSO) across all
applications, so that user credential can be managed in a centralised and
secure manner.
+
+Based on the fact that Streampark use Apache Shiro for authetication and
authorization purpose, and we are going to use Pac4j framework to achive the
Single Sign-On (SSO) support feature. Pac4j is recommented by Shiro community
as SSO integration solution, and it's also applied by other Apache project,
like Knox, Durid, Zeppelin, etc.
+
+## SSO login workflow
+We come up three main use cases with the workflow shown below:
+
+a) New user login when SSO is enabled
+<img src="/doc/image/sso/new-user-login-process.png"/><br></br>
+
+b) Existing user login when SSO is enabled
+<img src="/doc/image/sso/existing-user-login-process.png"/><br></br>
+
+c) User login when when SSO is not enabled
+<img src="/doc/image/sso/user-login-sso-not-enabled.png"/><br></br>
+
+## How to enable SSO login
+- Enable the SSO from the `application.yml`:
+```
+...
+spring:
+ profiles:
+ active: mysql #[h2,pgsql,mysql]
+ include: sso
+...
+sso:
+ # If turn to true, please provide the sso properties the
application-sso.yml
+ enable: true
+```
+
+- Select preferred 3rd party login approch, such as Github or Google auth, and
fill in the `application-sso.yml` config as below:
+```
+pac4j:
+ callbackUrl: http://localhost:10000/callback
+ # Put all parameters under `properties`
+ # Check supported sso config parameters for different authentication clients
from the below link
+ #
https://github.com/pac4j/pac4j/blob/master/documentation/docs/config-module.md
+ properties:
+ # principalNameAttribute:
+ # Optional, change by authentication client
+ # Please replace and fill in your client config below when enabled SSO
+ principalNameAttribute: email
+ oidc:
+ type: google
+ id: xxx
+ secret: xxx
+ useNonce: true
+ # github:
+ # id: xxx
+ # secret: xxx
+```
+
+- Start the Streampark, and see whether it will redirect to external login
page correctly and comple the authentication process:
+
+<img src="/doc/image/sso/github-login.png"/><br></br>
+<img src="/doc/image/sso/google-login.png"/><br></br>
+<img src="/doc/image/sso/login-success-redirect.png"/><br></br>
+
+## Note
+Currently we only support `OAuth` and `OpenID Connect (OIDC)` as normal
supported login approch, if you need to support `Saml`, or `CAS`, please go to
the `streampark-console/streampark-console-service/pom.xml`, change to include
them in the below dependency:
+```
+ <!-- Include pac4j-config/core/oauth/oidc-->
+ <dependency>
+ <groupId>org.pac4j</groupId>
+ <artifactId>pac4j-springboot</artifactId>
+ <version>${pac4jVersion}</version>
+ <exclusions>
+ <exclusion>
+ <groupId>commons-collections</groupId>
+ <artifactId>commons-collections</artifactId>
+ </exclusion>
+ <!-- cas & opensaml is not supported-->
+ <exclusion>
+ <groupId>org.pac4j</groupId>
+ <artifactId>pac4j-cas</artifactId>
+ </exclusion>
+ <exclusion>
+ <groupId>org.pac4j</groupId>
+ <artifactId>pac4j-saml-opensamlv3</artifactId>
+ </exclusion>
+ </exclusions>
+ </dependency>
+```
\ No newline at end of file
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/user-guide/10-SSO.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/user-guide/10-SSO.md
new file mode 100644
index 0000000..4358d75
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/user-guide/10-SSO.md
@@ -0,0 +1,91 @@
+---
+id: 'SSO'
+title: 'SSO集成'
+sidebar_position: 10
+---
+
+## 背景介绍
+作为企业实践，在应用程序中应用单点登录 (SSO) 是很常见的，这样可以通过集中且安全的方式管理用户凭证。
+
+基于 Streampark 使用 Apache Shiro 进行身份验证和授权的事实，我们将使用 Pac4j 框架来实现单点登录 (SSO) 支持功能。
Pac4j 是 Shiro 社区推荐的 SSO 集成解决方案，也被其他 Apache 项目应用，如 Knox、Durid、Zeppelin 等。
+
+
+## SSO 登录工作流
+我们提出了三个主要用例，其工作流程如下所示：
+
+a) SSO启用时，新用户登录
+<img src="/doc/image/sso/new-user-login-process.png"/><br></br>
+
+b) SSO启用时，现有用户登录
+<img src="/doc/image/sso/existing-user-login-process.png"/><br></br>
+
+c) SSO未启用时，用户登录
+<img src="/doc/image/sso/user-login-sso-not-enabled.png"/><br></br>
+
+## 如何启用SSO登录
+- 从配置文件`application.yml`启用SSO:
+```
+...
+spring:
+ profiles:
+ active: mysql #[h2,pgsql,mysql]
+ include: sso
+...
+sso:
+ # If turn to true, please provide the sso properties the
application-sso.yml
+ enable: true
+```
+
+- 选择第三方方式，例如Github或谷歌登录，填写如下所示的`application-sso.yml`配置:
+```
+pac4j:
+ callbackUrl: http://localhost:10000/callback
+ # Put all parameters under `properties`
+ # Check supported sso config parameters for different authentication clients
from the below link
+ #
https://github.com/pac4j/pac4j/blob/master/documentation/docs/config-module.md
+ properties:
+ # principalNameAttribute:
+ # Optional, change by authentication client
+ # Please replace and fill in your client config below when enabled SSO
+ principalNameAttribute: email
+ oidc:
+ type: google
+ id: xxx
+ secret: xxx
+ useNonce: true
+ # github:
+ # id: xxx
+ # secret: xxx
+```
+
+- 重启Streampark，检查是否会重定向至正确的第三方登录页，并成功完成登录过程:
+
+<img src="/doc/image/sso/github-login.png"/><br></br>
+<img src="/doc/image/sso/google-login.png"/><br></br>
+<img src="/doc/image/sso/login-success-redirect.png"/><br></br>
+
+## 注意事项
+目前我们仅支持`OAuth`和`OpenID Connect
(OIDC)`作为常规支持的登录方式，如果您需要支持`Saml`或`CAS`，请转到`streampark-console/streampark-console-service/pom.xml`，将它们更为包含在依赖当中:
+```
+ <!-- Include pac4j-config/core/oauth/oidc-->
+ <dependency>
+ <groupId>org.pac4j</groupId>
+ <artifactId>pac4j-springboot</artifactId>
+ <version>${pac4jVersion}</version>
+ <exclusions>
+ <exclusion>
+ <groupId>commons-collections</groupId>
+ <artifactId>commons-collections</artifactId>
+ </exclusion>
+ <!-- cas & opensaml is not supported-->
+ <exclusion>
+ <groupId>org.pac4j</groupId>
+ <artifactId>pac4j-cas</artifactId>
+ </exclusion>
+ <exclusion>
+ <groupId>org.pac4j</groupId>
+ <artifactId>pac4j-saml-opensamlv3</artifactId>
+ </exclusion>
+ </exclusions>
+ </dependency>
+```
\ No newline at end of file
diff --git a/static/doc/image/sso/existing-user-login-process.png
b/static/doc/image/sso/existing-user-login-process.png
new file mode 100644
index 0000000..a856695
Binary files /dev/null and
b/static/doc/image/sso/existing-user-login-process.png differ
diff --git a/static/doc/image/sso/github-login.png
b/static/doc/image/sso/github-login.png
new file mode 100644
index 0000000..ec1cc44
Binary files /dev/null and b/static/doc/image/sso/github-login.png differ
diff --git a/static/doc/image/sso/google-login.png
b/static/doc/image/sso/google-login.png
new file mode 100644
index 0000000..849ca17
Binary files /dev/null and b/static/doc/image/sso/google-login.png differ
diff --git a/static/doc/image/sso/login-success-redirect.png
b/static/doc/image/sso/login-success-redirect.png
new file mode 100644
index 0000000..6044a33
Binary files /dev/null and b/static/doc/image/sso/login-success-redirect.png
differ
diff --git a/static/doc/image/sso/new-user-login-process.png
b/static/doc/image/sso/new-user-login-process.png
new file mode 100644
index 0000000..32c59e1
Binary files /dev/null and b/static/doc/image/sso/new-user-login-process.png
differ
diff --git a/static/doc/image/sso/user-login-sso-not-enabled.png
b/static/doc/image/sso/user-login-sso-not-enabled.png
new file mode 100644
index 0000000..ac200ac
Binary files /dev/null and
b/static/doc/image/sso/user-login-sso-not-enabled.png differ
