单点登录(SSO)
单点登录功能(即Single Sign-On或SSO) 允许用户通过所在机构的身份验证服务(IDP)验证身份并登录TigerGraph GraphStudio和Admin Portal管理工具,而不用输入密码。若用户所属的IDP支持saml 2.0协议,则用户便可以在TigerGraph系统上集成SSO功能。
目前,我们已经验证过的身份提供者(Identity Provider)包括:
要打开SSO功能,用户需要:
  1. 1.
    配置Identity Provider,并为TigerGraph建立一个application。
  2. 2.
    将Identity Provider中的信息导入TigerGraph系统中并启动SSO验证。
  3. 3.
    创建包含代理规则(proxy rule)的用户组并将其用于SSO用户验证。
  4. 4.
    修改tigergraph默认的账户密码。
假定TigerGraph系统已经正常安装并启动,此时用户使用下面的URL便能访问GraphStudio的页面:
http://tigergraph-machine-hostname:14240
如果用户启用了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 指的是:
http://tigergraph-machine-hostname:14240/sso/saml/acs
SP entity id URL指的是:
http://tigergraph-machine-hostname:14240/sso/saml/meta
将滑动条拉至“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。
http://tigergraph-machine-hostname:14240/sso/saml/acs
移至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或域名均可)。
使用openssl生成自签名证书
$ openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout /home/tigergraph/sp-pkcs1.key -out /home/tigergraph/sp.cert
Generating a 2048 bit RSA private key
.................................................................................................................................+++
........+++
writing new private key to '/home/tigergraph/sp-pkcs1.key'
-----
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]:US
State or Province Name (full name) [Some-State]:California
Locality Name (eg, city) []:Redwood City
Organization Name (eg, company) [Internet Widgits Pty Ltd]:TigerGraph Inc.
Organizational Unit Name (eg, section) []:GLE
Common Name (e.g. server FQDN or YOUR name) []: tigergraph-machine-hostname
Email Address []:support@tigergraph.com
然后,将你私有秘钥从PKCS#1格式转换成PKCS#8格式:
openssl pkcs8 -topk8 -inform pem -nocrypt -in /home/tigergraph/sp-pkcs1.key -outform pem -out /home/tigergraph/sp.pem
最后,把证书和私有秘钥的权限修改为600或更低。(只有TigerGraph用户可以读写该文件,而其他用户均没有权限。)
chmod 600 /home/tigergraph/sp.*
使用gadmin工具启用和配置SSO
找一台TigerGraph主机,在该主机上执行命令gadmin --configure sso.saml
回答弹出的问题,示例如下:
配置sso.saml
$ gadmin --configure sso.saml
Enter new values or accept defaults in brackets with Enter.
Enable SAML2-based SSO: default false
security.sso.saml.enable [False]: true
True
Hostname of TigerGraph system: default 127.0.0.1
security.sso.saml.sp.hostname [127.0.0.1]: tigergraph-machine-hostname
tigergraph-machine-hostname
Path to host machine's x509 Certificate filepath: default empty
security.sso.saml.sp.x509cert: /home/tigergraph/sp.cert
/home/tigergraph/sp.cert
Path to host machine's private key filepath. Require PKCS#8 format (start with "BEGIN PRIVATE KEY").
security.sso.saml.sp.private_key: /home/tigergraph/sp.pem
/home/tigergraph/sp.pem
Identity Provider Entity ID: default http://idp.example.com
security.sso.saml.idp.entityid [http://idp.example.com]: http://identity.provider.entity.id
http://identity.provider.entity.id
Single Sign-On URL: default http://idp.example.com/sso/saml
security.sso.saml.idp.sso.url [http://idp.example.com/sso/saml]: http://identity.provider.single-sign-on.url
http://identity.provider.single-sign-on.url
Identity Provider's x509 Certificate filepath: default empty
security.sso.saml.idp.x509cert: /home/tigergraph/idp.cert
/home/tigergraph/idp.cert
Sign AuthnRequests before sending to Identity Provider: default true
security.sso.saml.advanced.authn_request.signed [True]:
True
Require Identity Provider to sign assertions: default true
security.sso.saml.advanced.assertions.signed [True]:
True
Require Identity Provider to sign SAML responses: default true
security.sso.saml.advanced.responses.signed [True]: false
false
Sign Metadata: default true
security.sso.saml.advanced.metadata.signed [True]:
True
Signiture algorithm [rsa-sha1/rsa-sha256/rsa-sha384/rsa-sha512]: default rsa-sha256
security.sso.saml.advanced.signature_algorithm [rsa-sha256]:
rsa-sha256
Authentication context (comma separate multiple values)
security.sso.saml.advanced.requested_authn_context [urn:oasis:names:tc:SAML:2.0:ac:classes:Password]:
urn:oasis:names:tc:SAML:2.0:ac:classes:Password
...
Test servers with supplied settings? [Y/n] y
...
Success. All settings are valid
Save settings? [y/N] y
...
Done.
{% endcode-tabs-item %} {% endcode-tabs %}
我们将security.sso.saml.advanced.responses.signed的值改为了false。其原因在于,某些Identity Provider(例如Auth0)不能同时支持确信(assertion)与应答(response)的签名。但如果你的Identity Provider同时支持两者的签名,则我们强烈建议将该属性值改为true。
$ gadmin config-apply
$ gadmin restart gsql -y

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

在验证SSO用户之前,我们需要在GSQL中按照代理规则建立用户组,并且为图数据库中的不同用户组分配权限。
TigerGraph系统的SSO功能支持两种类型的代理规则。一种基于名称ID(nameid),第二种基于属性(attribute)。通常基于属性的方式更常见,那是因为大多数情况下,用户组会以属性的方式传递到你的Identity Provider SAML Assertion中。在上面Okta的配置演示中,信息便是以名叫“group”的属性声明(Attribute Statement)传输的。通过向用户组赋予身份权限,所有符合代理规则的用户都会继承该用户组的权限。在某些特例中,如果管理员想给某个特定账号单独赋予权限,则可以使用名称ID来设置。
单用户代理
例:下面的示例中,我们建立一个名叫SuperUserGroup的用户组,该组内只包含一个用户:[email protected],并且给该用户赋予超级用户权限:
GSQL > CREATE GROUP SuperUserGroup PROXY "[email protected]"
GSQL > GRANT ROLE superuser TO SuperUserGroup
Role "superuser" is successfully granted to user(s): SuperUserGroup
用户组代理
假设你希望为一组用户创建一个叫做HrDepartment的用户组,这些SSO用户共享一个属性值为“hr-department”。假设我们要给他们在HrGraph图上赋予queryreader权限,则操作方法为:
GSQL > CREATE GROUP HrDepartment PROXY "group=hr-department"
GSQL > GRANT ROLE queryreader ON GRAPH HrGraph TO HrDepartment
Role "queryreader" is successfully granted to user(s): HrDepartment

修改默认用户的密码

一切结束后,别忘了在TigerGraph中开启用户验证。通过将默认的超级账户密码改成别的值便能做到这一点。在密码为默认值时,每次打开GraphStudio都会以超级账户自动登陆。
GSQL > change password
New Password : ********
Re-enter Password : ********
Password has been changed.
GSQL > exit

测试SSO功能

现在,所有的SSO配置均已完成,让我们测试一下吧。
在浏览器中打开GraphStudio页面,你可以在登陆栏的上方看到一个 Login with SSO 按钮。
点击这个按钮,页面会跳转到对应的Identity Provider的登陆界面。如果你已经在那里登陆过,则你会被自动重新定向回GraphStudio。验证过程大约需要10秒钟,随后你就能够使用GraphStudio了。如果你未曾在Identity Provider处登陆过,则你需要再登陆一次。在登陆完成后,点击GraphStudio界面右上方的 按钮可以查看你的SSO用户名。
如果回到GraphStudio时打开的仍然是登陆页面并提示以下报错,则表示该SSO用户没有对应图数据库的访问权限。请重新检查对应的用户组的代理规则以及所赋予的权限。
如果SSO验证失败并显示以下报错,则可能是由于某些配置在TigerGraph和Identity Provider之间不一致,或是别的未知错误所导致的。
你可以通过GSQL的日志文件进行错误处理。首先,找到你的GSQL日志文件:
$ gadmin log | grep GSQL_LOG
GSQL : /home/tigergraph/tigergraph/dev/gdk/gsql/logs/GSQL_LOG
然后筛选出与SAML验证相关的内容:
cat /home/tigergraph/tigergraph/dev/gdk/gsql/logs/GSQL_LOG | grep SAMLAuth
请重点关注最近的报错。通常这些报错通过字面意思就能理解。随后请按照实际的错误调整对应的TigerGraph或Identity Provider配置。若遇到任何无法解决的报错,也可以联系我们:[email protected]
Last modified 3yr ago