ASP.NET网站对接文档

暂不建议使用此方式,后续在此更新优化方法及Dotnet Core对接方法

获取SDK

网站的对接SDK从NuGet上获取。

不同版本的SDK

国双SSO Cas版使用的SDK是对官方SDK进行改造的。

官方SDK的下载源是nuget.org，使用它仅可以获取到用户的LoginEmail。

国双版SDK的下载源是nuget.gridsum.com，使用它会得到更多用户信息。

目前两个版本都支持跳转。

使用说明

我们通过定制应用的配置文件web.config来集成到ASP.NET网站中。SDK通过一个实现ASP.NET中的IHttpModule的Module——CasAuthenticationModule来完成工作。所以SDK的集成与网站的配置方式基本相同，包括：

  • 为CasAuthenticationModule配置相应属性
  • ASP.NET forms身份认证
  • CasAuthenticationModule注册
  • 认证配置
  • 诊断追踪配置（可选）

SDK的使用对代码是无侵入性的，即在web.config中配置完成后，无需在代码中手动验证用户是否已经通过单点登录系统认证（需要另外验证用户权限除外）。

完整示例

<configuration>
    <configSections>
        <section name="casClientConfig" type="DotNetCasClient.Configuration.CasClientConfiguration, DotNetCasClient" />
    </configSections>
    <system.web>
        <authentication mode="Forms" >
            <forms loginUrl="https://sso-cas.gridsumdissector.com/login" timeout="30" defaultUrl="~/Default.aspx"
             cookieless="UseCookies" slidingExpiration="true" path="/" />
        </authentication>
        <authorization>
            <deny users="?" />
        </authorization>
        <httpModules>
            <add name="DotNetCasClient" type="DotNetCasClient.CasAuthenticationModule,DotNetCasClient" />
        </httpModules>
    </system.web>
    <casClientConfig casServerLoginUrl="https://sso-cas.gridsumdissector.com/login"
            casServerUrlPrefix="https://sso-internal.gridsumdissector.com/"
            serverName="http://localhost:3459"
            redirectAfterValidation="true"
            gateway="false"
            renew="false"
            singleSignOut="true"
            ticketTimeTolerance="5000"
            ticketValidatorName="Cas20"
            serviceTicketManager="CacheServiceTicketManager" />
    <system.webServer>
        <validation validateIntegratedModeConfiguration="false" />
        <modules>
            <remove name="DotNetCasClient" />
            <add name="DotNetCasClient" type="DotNetCasClient.CasAuthenticationModule,DotNetCasClient" />
        </modules>
    </system.webServer>
</configuration>

CasAuthenticationModule的配置

定义section

<configSections>
    <section name="casClientConfig" type="DotNetCasClient.Configuration.CasClientConfiguration, DotNetCasClient" />
</configSections>

配置结点casClientConfig

在根标签configuration下为CasAuthenticationModule添加配置结点casClientConfig。

<casClientConfig casServerLoginUrl="https://sso-cas.gridsumdissector.com/login"
        casServerUrlPrefix="https://sso-internal.gridsumdissector.com/"
        serverName="http://localhost:3456"
        redirectAfterValidation="true"
        singleSignOut="true"
        ticketValidatorName="Cas20"
        serviceTicketManager="CacheServiceTicketManager" />

以上是我们建议默认使用的配置。下面是所有属性及其含义

casServerLoginUrl 必选

  • 单点登陆表单位置URL。
  • 使用https://sso-cas.gridsumdissector.com/login。

casServerUrlPrefix 必选

  • 单点登陆系统URL前缀。
  • 使用内网域名https://sso-internal.gridsumdissector.com/。
  • 有关内网域名的使用，请参见内网域名的使用。

serverName 必选

  • 当前网站的主机名。 这里的serverName的作用是生成在单点登陆系统登陆成功后会跳转到的URL，serverName必须是单点登陆系统可以解析的主机名。
  • 如果网站应用使用负载均衡、SSL Offloader、或其它类型的设备来代替应用接收请求，则需要提供公共的主机。
  • 协议前缀(http:// 或 https://)是可选的，建议添加相关协议。
  • 如果使用的是非常规端口，如(XD.gridsumdissector.com:8888)，则必须包含在配置中。
  • 请不要在末尾包含反斜杠。

ticketValidatorName 必选

  • 它指的是与单点登陆系统的认证方式名称。
  • 国双单点登陆系统使用的认证方式是Cas20协议，所以使用Cas20来配置。

serviceTicketManager 必选

  • 凭据管理器，它用来支持验证、撤消、单点登出等功能。
  • 使用默认管理器CacheServiceTicketManager。

singleSignOut 可选

  • 是否支持单点登出。
  • 建议使用单点登出功能。默认值为true。

renew 可选

  • 强制用户在访问应用时，重新从单点登陆系统进行认证。
  • 由于大部分不会有这样的需求，建议不使用。默认值为false。

gateway 可选

  • 启用单点登陆系统网关功能。
  • 功能尚未测试，建议不使用。默认值为false。

ticketTimeTolerance 可选

  • 在ticketValidatorName使用SAML协议认证方式时client与server的时差。
  • 由于我们使用Cas20协议认证，所以配置无效。

notAuthorizedUrl 可选

  • 这里设置的URL是当用户持有一个有效的ticket，但是用户并没有权限去访问某一地址或资源时，重定向的URL。如果未设置，会重定向到单点登陆系统的登陆页面。

proxyTicketManager 可选

  • 代理模式下的凭据管理器。
  • 由于现在对接的网站没有代理需求，所以它是不必要的。但这里不要使用，可能会出现重定向循环。

gatewayStatusCookieName 可选

  • 用来存取网关状态的Cookie(此Cookie会阻止每次请求client都会去网关验证)的名称。
  • 由于我们没有网关配置，所以不需要使用。默认为cas_gateway_status。

cookiesRequiredUrl 可选

  • 在gateway为true时生效。当client未接收会话cookie时重定向的地址。
  • 由于我们没有网关配置，所以不需要使用。

注册CasAuthenticationModule

将CasAuthenticationModule注册到httpModels中。

<system.web>
    <!-- 其它元素-->
    <httpModules>
        <add name="DotNetCasClient" type="DotNetCasClient.CasAuthenticationModule,DotNetCasClient" />
        <!-- 其它元素-->
    </httpModules>
</system.web>

<system.webServer>
    <!-- 禁用validateIntegratedModeConfiguration，防止在IIS 5/6 和 7+中报错 -->
    <validation validateIntegratedModeConfiguration="false" />
    <modules>
        <remove name="DotNetCasClient" />
        <!-- remove、add DotNetCasClient 在IIS 5/6中无效 -->
        <add name="DotNetCasClient" type="DotNetCasClient.CasAuthenticationModule,DotNetCasClient" />
        <!-- 其它元素-->
    </modules>
</system.webServer>

Forms的配置

为网站配置ASP.NET Forms身份认证。

<system.web>
    <authentication mode="Forms" >
        <!-- loginUrl要与casClientConfig中一致 -->
        <forms loginUrl="https://sso-cas.gridsumdissector.com/login" timeout="30" defaultUrl="~/Default.aspx" cookieless="UseCookies" slidingExpiration="true" path="/" />
    </authentication>
    <authorization>
        <deny users="?" />
    </authorization>
    <!-- 其它元素-->
</system.web>

关于Forms的配置，请根据需求按实际情况配置。只需确保loginUrl正确即可。

内网域名的使用

由于网站会与SSO进行交互，当网站在不能访问外网的服务器上时，需要配置内网地址与SSO进行交互。

我们使用的配置中https://sso-internal.gridsumdissector.com/，本地测试可能连接不上，需要连接vpn才能访问；若使用公网地址，服务器则有可能连接不上。

为了方便使用，使得本地测试和服务器都可以使用，可以通过使用两个配置来实现。

在web.config中，我们使用公网地址配置。

<casClientConfig casServerLoginUrl="https://sso-cas.gridsumdissector.com/login"
        casServerUrlPrefix="https://sso-internal.gridsumdissector.com/"
        serverName="http://localhost:3456"
        redirectAfterValidation="true"
        singleSignOut="true"
        ticketValidatorName="Cas20"
        serviceTicketManager="CacheServiceTicketManager" />

在Web.Release.config文件中添加一些转换语句，可以使得release发布时，配置文件中相应内容替换为服务器应该部署的配置。

<casClientConfig casServerLoginUrl="https://sso-cas.gridsumdissector.com/login"
        casServerUrlPrefix="https://sso-internal.gridsumdissector.com/"
        serverName="http://localhost:3456"
        redirectAfterValidation="true"
        singleSignOut="true"
        ticketValidatorName="Cas20"
        serviceTicketManager="CacheServiceTicketManager"
        xdt:Transform="Replace" />

以上配置表示在Release时，会使用Web.Release.config中的casClientConfig替换（Replace）Debug时的所有值。

在程序中使用SDK

在登录成功后，会在浏览器中存储对接网站登录信息的Cookie，根据FormsAuthentication.FormsCookieName从Request中取得Cookie。

// 获取Forms认证Cookie
var ticketCookie = this.Request.Cookie[FormsAuthentication.FormsCookieName];
// Cookie域
ticketCookie.Domain;
// Cookie过期时间
ticketCookie.Expires;
// Cookie名称
ticketCookie.Name;
// Cookie路径
ticketCookie.Path;
// Cookie安全标识
ticketCookie.Secure;
// Cookie值
ticketCookie.Value;

使用Forms Ticket

根据Cookie中存储的值可以获取Forms认证成功的Ticket。

// 获取Forms认证Cookie
var ticketCookie = this.Request.Cookie[FormsAuthentication.FormsCookieName];
// 获取Forms认证Ticket
var ticket = FormsAuthentication.Decrypt(ticketCookie.Value);
// Ticket的Cookie路径
ticket.CookiePath;
// Ticket过期时间
ticket.Expiration;
// Ticket是否已经过期
ticket.Expired;
// 包含Ticket的Cookie是否持久化
ticket.IsPersistent;
// Ticket发布时间
ticket.IssueDate;
// Ticket名称
ticket.Name;
// Ticket存储的用户信息
ticket.UserData;
// Ticket版本
ticket.Version;

使用SSO Ticket

我们在Ticket中存储的是用户的LoginEmail，在UserData中存储了SSO Ticket的标识信息。可以根据UserData获取SSO Ticket。

// 获取Forms认证Cookie
var ticketCookie = this.Request.Cookie[FormsAuthentication.FormsCookieName];
// 获取Forms认证Ticket
var ticket = FormsAuthentication.Decrypt(ticketCookie.Value);
// 获取SSO认证SSO Ticket
var ssoTicket = CasAuthentication.ServiceTicketManager.GetTicket(ticket.UserData);
// SSO Ticket Id，存储的是LoginEmail
ssoTicket.NetId;
// SSO Ticket惟一标识
ssoTicket.ServiceTicket;
// SSO Ticket认证Servce名称
ssoTicket.OriginatingServiceName;
// SSO Ticket认证客户端地址
ssoTicket.ClientHostAddress;
// SSO Ticket认证成功时间
ssoTicket.ValidFromDate;
// SSO Ticket认证到期时间
ssoTicket.ValidUntilDate;

使用Account Info

可以通过SSO Ticket获取用户信息。

// 获取Forms认证Cookie
var ticketCookie = this.Request.Cookie[FormsAuthentication.FormsCookieName];
// 获取Forms认证Ticket
var ticket = FormsAuthentication.Decrypt(ticketCookie.Value);
// 获取SSO认证SSO Ticket
var ssoTicket = CasAuthentication.ServiceTicketManager.GetTicket(ticket.UserData);
// 获取用户信息
var accountInfo = ssoTicket.Assertion.AccountInfo;
// 用户Key
accountInfo.AccountKey;
// 登录用户名
accountInfo.LoginEmail;
// 用户显示名
accountInfo.DisplayName;
// 用户Guid
accountInfo.AccountGuid;

使用单点登出

SDK中集成了单点登出功能，可以仅需要一行代码就可以实现。

CasAuthentication.SingleSignOut();

在单点登出后，会重定向到国双SSO Cas版首页。