跳到主内容

Nginx

使用Casdoor作为身份提供者（IdP）为NGINX Plus代理的应用程序启用基于OpenID Connect的单点登录。

本指南解释了如何为NGINX Plus代理的应用程序启用单点登录（SSO）。该解决方案使用OpenID Connect作为身份验证机制，以Casdoor作为身份提供者（IdP），以及NGINX Plus作为依赖方。

另见 GitHub 上的 NGINX Plus OpenID Connect。

先决条件​

说明假定您具有以下内容：

  • 一个正在运行的Casdoor服务器。见 服务器安装 和 用 Docker 试用。

  • 一个NGINX Plus订阅和NGINX Plus R15或更高版本。有关安装说明，请参阅NGINX Plus管理员指南。

  • NGINX JavaScript模块，用于处理NGINX Plus和IdP之间的交互。安装NGINX Plus后，使用适合您的操作系统的命令安装模块。

    对于Debian和Ubuntu：

    sudo apt install nginx-plus-module-njs

    对于CentOS，RHEL和Oracle Linux：

    sudo yum install nginx-plus-module-njs

  • 以下指令应包含在顶级（“主”）配置上下文中的**/etc/nginx/nginx.conf**中，以便加载NGINX JavaScript模块：

    load_module modules/ngx_http_js_module.so;

配置Casdoor​

**注意：**以下过程反映了出版时的Casdoor GUI，但GUI可能会发生变化。使用此指南作为参考，并根据当前的Casdoor GUI进行调整。

要在Casdoor GUI中为NGINX Plus创建一个Casdoor客户端，请按照以下步骤操作：

  1. 在**http://your-casdoor-url.com/login/**登录您的Casdoor帐户。

  2. 在顶部导航栏中，点击应用程序。在打开的应用程序页面上，点击左上角的添加按钮。

    addApp

  3. 在打开的编辑应用程序页面上，将名称和显示名称字段的值更改为您要启用SSO的应用程序的名称。在这里，我们使用的是NGINX Plus。

    appName

    在重定向URL字段中，输入NGINX Plus实例的URL，包括端口号，并以**/_codexch**结尾（在本指南中，它是https://your-site-url.com:443/_codexch）。

    redirectURL

    注意：

    • 对于生产环境，我们强烈建议您使用SSL/TLS（端口443）。
    • 即使您使用的是HTTP（80）或HTTPS（443）的默认端口，端口号也是必需的。

  4. 记下 Client ID 和 Client Secret，在 配置 NGINX Plus 的第 4 步 中会用到。

    客户端

  5. 点击顶部导航栏中的角色，然后点击打开的页面左上角的添加按钮。

    addRole

  6. 在打开的添加页面上，在名称和显示名称字段中输入一个值（这里是nginx-casdoor-role），然后点击保存按钮。

    roleName

  7. 在顶部导航栏中，点击用户。在打开的用户页面上，点击编辑编辑现有用户，或者点击左上角的添加按钮创建新用户。

  8. 在打开的添加页面上，根据您的喜好修改名称和显示名称（这里是user1）。

    userName

    在注册应用程序中选择NGINX Plus。

    signupApp

    在管理帐户字段中，选择应用程序中的NGINX Plus，并填写用户名和密码。

    managedAcc

  9. 返回到角色页面，点击nginx-casdoor-role行上的编辑。在打开的页面中，在子用户字段中，选择您刚刚创建的用户名（这里是built-in/user1）。

    subUsers

配置NGINX Plus​

要配置NGINX Plus作为OpenID Connect依赖方，请按照以下步骤操作：

  1. 首先，创建nginx-openid-connect GitHub仓库的克隆：

    git clone https://github.com/nginxinc/nginx-openid-connect

  2. 将克隆中的以下文件复制到**/etc/nginx/conf.d**目录：

    • frontend.conf
    • openid_connect.js
    • openid_connect.server_conf
    • openid_connect_configuration.conf

  3. 从Casdoor配置中获取授权端点、令牌端点和JSON Web Key（JWK）文件的URL。打开终端并执行以下curl命令，将输出管道到指定的python命令以生成可读的配置格式。为了简洁，我们已经截断了输出，只显示相关字段。 

    curl http://<casdoor-server-address>/.well-known/openid-configuration | python -m json.tool
    {
        "authorization_endpoint": "https://<casdoor-server-address>/login/oauth/authorize",
        "...":"...",
        "token_endpoint": "http://<casdoor-server-address>/api/login/oauth/access_token",
        "...":"...",
        "jwks_uri": "http://<casdoor-server-address>/.well-known/jwks",
        "...":"...",
    }

  4. 使用您喜欢的文本编辑器打开**/etc/nginx/conf.d/openid_connect_configuration.conf**。修改以下map指令的"default"参数值为指定的值：

    • map $host $oidc_authz_endpoint - 使用步骤3中的authorization_endpoint的值（在本指南中，https://<casdoor-server-address>/login/oauth/authorize）
    • map $host $oidc_token_endpoint - 使用步骤3中的token_endpoint的值（在本指南中，http://<casdoor-server-address>/api/login/oauth/access_token）
    • map $host $oidc_client - 使用配置Casdoor的步骤4中客户端ID字段的值
    • map $host $oidc_client_secret - 使用配置Casdoor的步骤2中客户端密钥字段的值
    • map $host $oidc_hmac_key - 使用一个独特的，长的，安全的短语

  5. 根据使用的NGINX Plus版本配置JWK文件：

    • 在NGINX Plus R17及更高版本中，NGINX Plus可以直接从步骤3中指定为jwks_uri的URL读取JWK文件。对**/etc/nginx/conf.d/frontend.conf**进行以下更改：
      1. 注释掉（或删除）auth_jwt_key_file指令。
      2. 取消注释auth_jwt_key_request指令。（参数/_jwks_uri引用了$oidc_jwt_keyfile变量的值，该值将在下一步中设置。）
      3. 将map $host $oidc_jwt_keyfile指令的"default"参数更新为步骤3中jwks_uri字段的值（在本指南中，http://<casdoor-server-address>/.well-known/jwks）。
    • 在NGINX Plus R16及更早版本中，或者如果您喜欢，JWK文件必须位于本地磁盘上。按照以下步骤操作：
      1. 将步骤3中jwks_uri字段指定的JWK文件的JSON内容复制到本地文件（例如，/etc/nginx/my_casdoor_jwk.json）。
      2. 在**/etc/nginx/conf.d/openid_connect_configuration.conf**中，将map $host $oidc_jwt_keyfile指令的"default"参数更改为本地文件的路径。

  6. 确保在NGINX Plus配置文件（通常是**/etc/nginx/nginx.conf**）中指定的user指令的用户具有读取JWK文件的权限。

测试​

打开浏览器并输入您的NGINX Plus实例的地址。然后，尝试使用被分配了NGINX Plus角色的用户的凭据登录。

测试

故障排除​

见 nginx-openid-connect 仓库中的 故障排查 一节。