单点登录(SSO)

单点登录功能(即Single Sign-On或SSO) 允许用户通过所在机构的身份验证服务(IDP)验证身份并登录TigerGraph GraphStudio和Admin Portal管理工具,而不用输入密码。若用户所属的IDP支持saml 2.0协议,则用户便可以在TigerGraph系统上集成SSO功能。

目前,我们已经验证过的身份提供者(Identity Provider)包括:

要打开SSO功能,用户需要:

  1. 配置Identity Provider,并为TigerGraph建立一个application。

  2. 将Identity Provider中的信息导入TigerGraph系统中并启动SSO验证。

  3. 创建包含代理规则(proxy rule)的用户组并将其用于SSO用户验证。

  4. 修改tigergraph默认的账户密码。

假定TigerGraph系统已经正常安装并启动,此时用户使用下面的URL便能访问GraphStudio的页面:

如果用户启用了SSL连接,则请将 http 改成 https。如果TigerGraph的 nginx 对应端口不是默认值14240,则请将端口号改为实际值。

配置Identity Provider

针对已经经过认证的Identity Provider,此处我们将详细说明配置步骤。如果您所属组织使用的Identity Provider未在我们的已验证列表中,请联系您的IT或网络安全部门。

在Identity Provider配置完成后,用户会获得一个SSO连接地址(即Identity Provider Single Sign-On URL),身份ID号(即Identity Provider Entity Id)以及一个X.509证书文件 idp.cert。接下来的配置过程需要用到这三样信息。

Okta

在使用管理员账号登录Okta后,点击右上角的Admin按钮

在右侧菜单中点击Add Applications按钮

在左侧工具栏中点击Create New App按钮。

在弹出的窗口中,选择SAML 2.0,并点击Create。

在App Name中输入TigerGraph(或其他你希望使用的应用名),点击下一步,你也可以选择上传一个图标。

输入Assertion Consumer Service URL(即Single sign on URL)以及SP Entity ID。

在本演示中,它们两者都是URL。用户需要知道运行TigerGraph的主机名。用户可以通过打开GraphStudio页面,然后再浏览器的地址栏中找到主机名。当然,输入IP地址或是域名也是可以的。

所谓的Assertion Consumer Service URL 或 Single sign on URL 指的是:

SP entity id URL指的是:

将滑动条拉至“Group Attribute Statements”的末尾。通常情况下,我们希望一个用户的权限继承自它所在的用户组。你可以给Attribute Statement起一个名字,但本示例中我们采用用户组来设定权限。我们希望筛选出所有用户的一切组属性,所以我们使用 Regex.* 来表示过滤规则。 点击下一步;

最后,请选择是否希望将你的app集成到Okta中。然后点击完成按钮。

此时,你的Okta Identity Provider已配置完成。点击View Setup Instructions 按钮可以获取到用于配置TigerGraph SSO的参数值。

在这里我们可以保存所需的Identity Provider Single Sign-On URL和Identity Provider Issuer(也叫做Identity Provider Entity Id)。我们可以将证书文件okta.cert下载下来,更名为idp.cert,然后将它复制到TigerGraph所在的服务器上,本示例假设我们将其放在home文件夹下(即/home/tigergraph/idp.cert)。若TigerGraph系统是以集群方式部署,则需要将该文件放到GSQL运行的服务器上(通常该服务器的别名叫m1)。

最后,返回上一个页面,打开Assigments标签页,点击Assign按钮,为你的用户或用户组赋予所需的身份权限。

Auth0

在登录Auth0之后,点击左侧的Clients链接,然后点击CREATE CLIENT(即创建客户端)按钮。

在弹出的窗口中,在Name栏输入TigerGraph(或其他您想使用的应用名)。然后点击Single Page Web Application,最后点击CREATE:

再次点击Clients,在列出的客户端中,点击刚刚创建的TigerGraph客户端右侧的配置按钮。

移至配置页最底部,点击Show Advanced Settings(即显示高级配置):

选择Certificates标签页,然后点击DOWNLOAD CERTIFICATE下载证书。下载选项中选择CER。文件成功下载后将其更名为idp.cert,然后将其复制到TigerGraph的主机上。如果TigerGraph系统是基于集群模式部署的话,需要将该文件放到GSQL服务器所在的主机上(通常它的机器名是m1)。

选择Endpoints标签页,复制SAML Protocol URL文本框中的文字。这些文字便是我们即将要用到的Identity Provider Single Sign-On URL。

移至页面顶部,选择Addons标签页,打开SAML2的开关:

在弹出的窗口中,在Application Callback URL中输入Assertion Consumer Service URL。

移至JSON代码的末尾,点击DEBUG按钮。然后再弹出的登录页面中以任何已经创建的账户登录。

如果登录成功,则SAML会返回以下明文XML格式应答。移至Attributes部分,在这里可以看到一些属性名称。这些属性名称将被用来在之后建立用户组的过程中,用于配置代理规则。

返回之前的弹出窗口,点击Usage标签页,复制Issuer的值。这个值就是Identity Provider Entity Id,我们将在接下来的步骤中用到它。

点击Settings标签页,移至弹窗底部,然后点击Save按钮。关闭弹出窗口。

Auth0 配置完毕. 返回第2步 Enable Single Sign-On for TigerGraph

在TigerGraph中开启SSO

在TigerGraph主机上预备证书和私有秘钥

自签名证书(即self-signed certificate)根据SAML标准的信任模型是可用的,这与配置SSL连接不同。对于SSL连接来说,在生产环境中必须强制性使用CA授权证书。

创建自签名证书的方法有多钟,以下为其中的一个示例。

首先,使用下面的命令生成一个PKCS#1格式的私有秘钥和一个X.509证书文件。在下面的例子中,Common Name的值应该是你的服务器名(IP或域名均可)。

然后,将你私有秘钥从PKCS#1格式转换成PKCS#8格式:

最后,把证书和私有秘钥的权限修改为600或更低。(只有TigerGraph用户可以读写该文件,而其他用户均没有权限。)

使用gadmin工具启用和配置SSO

找一台TigerGraph主机,在该主机上执行命令gadmin --configure sso.saml

回答弹出的问题,示例如下:

{% endcode-tabs-item %} {% endcode-tabs %}

我们将security.sso.saml.advanced.responses.signed的值改为了false。其原因在于,某些Identity Provider(例如Auth0)不能同时支持确信(assertion)与应答(response)的签名。但如果你的Identity Provider同时支持两者的签名,则我们强烈建议将该属性值改为true。

根据代理规则建立用户组并用其完成SSO认证

在验证SSO用户之前,我们需要在GSQL中按照代理规则建立用户组,并且为图数据库中的不同用户组分配权限。

TigerGraph系统的SSO功能支持两种类型的代理规则。一种基于名称ID(nameid),第二种基于属性(attribute)。通常基于属性的方式更常见,那是因为大多数情况下,用户组会以属性的方式传递到你的Identity Provider SAML Assertion中。在上面Okta的配置演示中,信息便是以名叫“group”的属性声明(Attribute Statement)传输的。通过向用户组赋予身份权限,所有符合代理规则的用户都会继承该用户组的权限。在某些特例中,如果管理员想给某个特定账号单独赋予权限,则可以使用名称ID来设置。

单用户代理

例:下面的示例中,我们建立一个名叫SuperUserGroup的用户组,该组内只包含一个用户:admin@your.company.com,并且给该用户赋予超级用户权限:

用户组代理

假设你希望为一组用户创建一个叫做HrDepartment的用户组,这些SSO用户共享一个属性值为“hr-department”。假设我们要给他们在HrGraph图上赋予queryreader权限,则操作方法为:

修改默认用户的密码

一切结束后,别忘了在TigerGraph中开启用户验证。通过将默认的超级账户密码改成别的值便能做到这一点。在密码为默认值时,每次打开GraphStudio都会以超级账户自动登陆。

测试SSO功能

现在,所有的SSO配置均已完成,让我们测试一下吧。

在浏览器中打开GraphStudio页面,你可以在登陆栏的上方看到一个 Login with SSO 按钮。

点击这个按钮,页面会跳转到对应的Identity Provider的登陆界面。如果你已经在那里登陆过,则你会被自动重新定向回GraphStudio。验证过程大约需要10秒钟,随后你就能够使用GraphStudio了。如果你未曾在Identity Provider处登陆过,则你需要再登陆一次。在登陆完成后,点击GraphStudio界面右上方的 按钮可以查看你的SSO用户名。

如果回到GraphStudio时打开的仍然是登陆页面并提示以下报错,则表示该SSO用户没有对应图数据库的访问权限。请重新检查对应的用户组的代理规则以及所赋予的权限。

如果SSO验证失败并显示以下报错,则可能是由于某些配置在TigerGraph和Identity Provider之间不一致,或是别的未知错误所导致的。

你可以通过GSQL的日志文件进行错误处理。首先,找到你的GSQL日志文件:

然后筛选出与SAML验证相关的内容:

请重点关注最近的报错。通常这些报错通过字面意思就能理解。随后请按照实际的错误调整对应的TigerGraph或Identity Provider配置。若遇到任何无法解决的报错,也可以联系我们:support@tigergraph.com