CAS协议介绍.doc

CAS协议介绍中创软件商用中间件有限公司CAS协议介绍前言本文是CAS协议规范的中文译文。251. Introduction以下是CAS1.0和2.0协议的官方规范。注：CAS1.0和2.0协议大体包含两个方面的内容：各种票根（Ticket）和暴露给CAS客户的HTTP（S）URL。这些UPL（/login、/logout、/validate、/serviceValidate、/proxy、/proxyValidate等）围绕着这些票根（ST、TGC、PGT、PT等）进行活动。在此期间服务和终端服务之间会进行多次HTTPS交互。Conventions & Definitions（公约和定义）l “Client” 指的是终端用户或者是WEB浏览器。l “Server”指的是统一认证服务所在的服务器。l “Service” 指的是终端用户或者WEB浏览器试图访问的应用. l “Back-end service”是指一个服务试图代表一个client去访问一个应用，这个应用就被称为终端服务（Back-end service） 。它也被称作“target service”目标服务。注：这里的service可以包含两部分，一是应用程序本身提供的service；二是应用程序本身还可提供代理服务，使Client能够通过它的代理功能访问终端服务。按照翻译，不容易理解“终端服务”，通过下面的图可以很容易看清楚它的作用。黄色区域指Client；绿色区域指Server；紫色区域指Service；蓝色区域指终端服务。其中CAS1.0中没有终端服务这一块，也没有Service的proxy，也即不能进行代理认证。2. CAS URIsCAS是一个基于HTTP的协议，这就要求其每一个组成部分可以通过特定的URIs访问到。本节将讨论每个的URIs。2.1. /login as credential requestor/login URI通过两种行为运转：一是作为一个凭证索取者，二是作为凭证接收者。根据它对凭证的反应来区分他是作为凭证索取者还是凭证接收者。如果客户端已经与CAS建立了一个单点登录的session，Web浏览器给CAS一个安全的cookie，里面包含有一个以字符串形式存在的身份信息TGT（Ticket-Granting Ticket），存储这个身份信息TGT的cookie就被称为票证授予的cookie（TGC- Ticket-Granting Cookie）。如果TGC里面有一个有效的TGT，CAS可以发出一个服务门票（Service Ticket，ST），这个ST可以在本规范内的其他任何情况下使用。本规范的要求。见第3.6节提供更多的资料，TGC。2.1.1. parameters下面的HTTP请求的参数可通过/login，这时它作为凭证索取者。他们都是区分大小写的，他们都必须处理/login。· service可选 -客户端尝试访问的应用的标识符。在几乎所有情况下，这将是应用的URL。请注意，作为一个HTTP请求的参数，此URL的值必须是符合RFC 中URL编码的描述。（详情参见RFC 1738 4 的第2.2节）。如果没有指定service并且单点登录session尚不存在，CAS应要求具有凭证的用户发起一个单点登录session。如果没有指定service但单点登录session已经存在，CAS应显示一条消息，通知客户，这是已经登录· Renew可选 -如果此参数设置，单点登录将被绕过。在这种情况下，CAS将要求客户提交证书，不论是否存在一个CAS的单点登录session。这个参数与“gateway”参数不兼容。服务重定向到/login的URI和登录表单视图，张贴在/login的URI中的值不应同时出现在“renew”和“gateway”请求参数。两个参数都设置这种行为是未定义的。CAS推荐：在实施时，如果设置“renew”参数则忽略“gateway”参数。推荐：当设置“renew”参数时，其值应该为“true”。注：也就是说：https:/server/cas/login?service=serviceUrl&renew=true&gateway=true这种参数传递是错误的，不能同时出现两个参数。注：CAS协议允许客户端选择是否跳出单点登录，这就是renew。它允许一个客户端通知CAS服务器总是验证一个用户，不管一个单点登录的session是否存在。这是一个非常有用的属性，当一个特定的使用CAS认证机制的服务允许访问敏感资料时，它能强迫CAS重新认证一个用户，确保登录的是一个正确的用户。这时，那个应经存在的单点登录session应该是被终止的。使用这个属性通知CAS重新验证凭证时，客户端应用应该中定向用户到以下的URL上：https:/server/cas/login?service=serviceUrl&renew=true当请求验证这个票据时，客户端可以要求CAS确保这个票据是来自一个新的认证请求。应用场景可参见：部署的客户端集成示例bookshop，改变该参数值，体验效果。· Gateway可选 -如果这个参数设定，CAS将不会向客户端索要凭据。如果客户端有一个已存在的CAS单点登录的session，或者如果单点登录session可以通过非交互方式（i.e. trust authentication，信托认证）建立，CAS可以将客户端请求重定向到“service”参数指定的URL，而且还加上有效的服务票据（Service Ticket，ST）。 （CAS还可以插入一个通知页面，通知客户端一个CAS认证已经发生了。）如果客户端没有CAS单点登录的session，并且也不可能通过非交互方式建立认证，CAS必须将客户端重定向到“service”参数指定的URL，并且不在URL后面附加“ticket”。如果“service”参数未指定但设置了“gateway”参数，CAS将认为这种行为未定义。在这种情况下推荐：如果两个参数都没有指定，CAS应要求凭据。同样这个参数与“renew”参数不兼容。如果要设置“gateway”参数，推荐设置为“true”。注：应用场景可参见：部署的客户端集成示例bookshop，改变该参数值，体验效果。 总结：“renew”参数的作用：在存在SSO session的情况下client请求访问资源，是重新认证用户信息还是不用认证放这个请求过去。“gateway”参数的作用：与“renew”参数相反，“gateway=true”时是指只要存在SSO session就不用重新认证了。Renew始终要求用户进行主认证，所谓主认证就是借助于/login进行的认证操作，此时IE用户必须手工提供自身的帐号信息。基于TGC、PT的登录都不属于主认证。相比之下，gateway始终不会允许CAS服务器丢出/login登录页面给IE用户，从而不可能进行主认证。只要gateway=true则永远进不到/login登录页面，只有确认用户能从其他途径得到SSO session才可以设置true。2.1.2. URL examples of /loginSimple login example: https:/server/cas/login?service=http%3A%2F%2FDon't prompt for username/password: https:/server/cas/login?service=http%3A%2F%2F&gateway=trueAlways prompt for username/password: https:/server/cas/login?service=http%3A%2F%2F&renew=true2.1.3. response for username/password authentication当/login的行为作为凭证索取者时，根据请求的证书的类型响应会有所不同。在大多数情况下，CAS作出的回应是显示登录屏幕要求输入用户名和密码。此网页必须是包括“用户名”，“密码”参数的表单。该表单也可包括 “warn”参数 。如果“service”已被指定为从/login登录，那么“service”也成了登录表单的一个参数，包含着通过/login以后最初的地址。将在第2.2.1节对这些参数进行详细的讨论。该表单必须通过HTTP POST方法来提交到/login，然后/login就作为凭据接收人，将在第2.2节讨论。2.1.4. response for trust authentication信任认证作为一种基本的认证，对各种各样的请求都考虑了进去。信任认证的用户体验就是高度详尽的部署，考虑本地策略和特殊情况下认证机制的实现。当/login行为作为信任认证的票据索取者时，其行为将取决于接收的证书的类型。如果证书是有效的，CAS会立即将用户重定向到请求的服务。另外，CAS可能会显示一个警告信息：证书是存在的，并允许客户端确认它是否想利用这些证书。推荐：CAS的实施允许部署者选择首选行为。如果证书是无效的或不存在，CAS推荐显示客户端验证失败的原因，以及可能替代目前的用户身份验证的其他方式（如用户名/密码身份验证）。2.1.5. response for single sign-on authentication如果客户已经建立了一个CAS的单点登录session，客户端将带着自己的HTTP会话cookie来/ Login ，并予以处理的行为将在第2.2.4节。但是，如果“renew”参数设置了，处理行为参见第2.1.3或2.1.4 。2.2. /login as credential acceptor当一组接收的证书通过了/login，/login将扮演凭证接收者的角色，具体行为将在本节定义。2.2.1. parameters common to all types of authentication当/login作为凭据接收人时，下面的HTTP请求参数可能被传递到/login。他们都是区分大小写的，它们都必须由/login控制。 service可选 -客户端尝试访问的应用的URL。成功验证后CAS必须将客户端重定向到这个URL。这是详细讨论了第2.2.4节。 warn可选 -如果此参数设置，单点登录将不能是透明。客户端必须被提示通过了验证正在转向请求的服务。2.2.2. parameters for username/password authentication除了在第2.2.1节指明的可选参数，当/login作为用户名/密码认证方式的接收人时，下列HTTP请求参数必须被传递到/login。他们都区分大小写。 username需要 -正在试图登录的客户端的用户名。password需要 -正在试图登录的客户端的密码。It需要 -登入票证。这是的一部分在第2.1.3节的登录表单中讨论过了。登录门票将在第3.5节讨论。2.2.3. parameters for trust authenticationThere are no REQUIRED HTTP request parameters for trust authentication. Trust authentication may be based on any aspect of the HTTP request. 2.2.4. response/login作为凭证接收者时，下列其中一个回复是它必须提供的。 成功登入：在不将客户端凭证传递到service的情况下，重定向客户端请求到“service”参数指定的网址。这种重定向的结果必须导致用户端向它所请求的服务发出一个GET请求。要求必须包括一个有效的服务票据（Service Ticket，ST），作为HTTP请求的参数通过，它就是“ticket” 。见附录B获取更多信息。如果“服务”未指定，CAS必须通知客户端，它已成功地开始了一个单点登录session。 未能登入：/login将再次作为凭证索取者返回。因此建议在这种情况下，CAS服务器向用户显示错误信息，说明为什么登入失败（例如密码错误，锁定帐户等） ，如果有必要的话，提供一个机会，让用户能够尝试再次登录。2.3. /logout/logout用于销毁客户端的CAS单点登录会话。TGC被摧毁（第3.6节），随后请求/login将不会取得服务门票（ST），直到用户再次交出主凭证（从而建立了一个新的单点登录session）。2.3.1. parameters以下HTTP请求参数为/logout指定的。这是区分大小写的，应由/logout来处理。 url可选 -如果“url”是指定的，通过“url”参数指定的URL应该是登出页面并且带有描述性文字。例如， “您刚才的应用退出提供了一个链接，希望您的后续。请单击此处访问http:/www.go-back.edu .”2.3.2. response/logout必须展示一个页面，向用户表明现在已经登出。如果“url”请求参数生效，/logout还应提供一个链接到以前登入的URL的链接 ，具体描述在第2.3.1 。2.4. /validate CAS 1.0/validate检查ST的有效性，/validate是CAS1.0协议的一部分，因此不处理代理认证。当一个代理凭证通过/validate时，CAS必须作出反应。2.4.1. parameters下面的HTTP请求的参数可以指定为/验证。它们是区分大小写的，必须全部交由/验证。 service需要 服务的标识符，是需要带着ticket访问的服务。 ticket需要 -/login发出的服务凭证（ST）。服务车票的描述见3.1节。 renew可选 -如果这个参数设定，凭证验证将只在ST是来自用户的主证书时才会通过验证，如果ticket是来自SSO session，则验证失败。即，只用通过主登录页面过来的附带着ST的请求，才能被验证。2.4.2. response/validate will return one of the following two responses: On ticket validation success: yes<LF>username<LF>On ticket validation failure: no<LF><LF>2.4.3. URL examples of /validateSimple validation attempt: https:/server/cas/validate?service=http%3A%2F%2F&ticket=ST-1856339-aA5Yuvrxzpv8Tau1cYQ7Ensure service ticket was issued by presentation of primary credentials: https:/server/cas/validate?service=http%3A%2F%2F&ticket=ST-1856339-aA5Yuvrxzpv8Tau1cYQ7&renew=true2.5. /serviceValidate CAS 2.0/serviceValidate检查ST的有效性，并且返回一个XML片段。 当被请求时，/serviceValidate还必须创造和传出PGT（proxy-granting ticket，代理准许凭证）。如果/serviceValidate收到只是一个PT（proxy ticket，代理凭证），它不可以返回一个成功的验证。CAS推荐：如果/ serviceValidate收到PT，应该在返回的XML响应的错误信息里说明失败的原因，原因是由于PT传递到了/ serviceValidate。也即：/ serviceValidate不能负责校验PT。2.5.1. parameters下面的HTTP请求的参数是/ serviceValidate可以指定的。它们是区分大小写的，必须全部交由/ serviceValidate处理。 service需要 -服务的标识符，是需要带着ticket访问的服务。第2.2.1节。 ticket需要 - /login发出的服务凭证（ST）。ST将在3.1节详解。 pgtUrl 可选 -代理回调的URL。将在2.5.4节讨论。 renew可选 -如果这个参数设定，凭证验证将只在ST是来自用户的主认证时才会通过验证，如果ticket是来自SSO session，则验证失败。2.5.2. response/ serviceValidate将返回一个格式化的CASserviceResponse XML，详细描述参加附录A。On ticket validation success: <cas:serviceResponse xmlns:cas='http:/www.yale.edu/tp/cas'> <cas:authenticationSuccess> <cas:user>username</cas:user> <cas:proxyGrantingTicket>PGTIOU-84678-8a9d. </cas:proxyGrantingTicket> </cas:authenticationSuccess></cas:serviceResponse>On ticket validation failure: <cas:serviceResponse xmlns:cas='http:/www.yale.edu/tp/cas'> <cas:authenticationFailure code="INVALID_TICKET"> Ticket ST-1856339-aA5Yuvrxzpv8Tau1cYQ7 not recognized </cas:authenticationFailure></cas:serviceResponse>2.5.3. error codes下面的值可能被用来作为验证失败时“code”属性的值。以下是最低限度的错误代码，所有CAS服务器必须实现的，当然还包括其他一些实现。 INVALID_REQUEST -请求参数不全。上面讲到至少必须有“service”和“ticket”两个参数。 INVALID_TICKET -提供的ticket无效，或者你的“renew”属性设置为true，而不是从主认证（/login）过来的。返回的XML中的消息体中的<cas:authenticationFailure>块应说明具体细节。 INVALID_SERVICE -提供ticket是有效的，但是和服务规定的ticket并不匹配。CAS必须使这张ticket失效，并禁止今后再验证该ticket。 INTERNAL_ERROR 在ticket验证时发生内部错误。对于所有的错误代码，CAS推荐为<cas:authenticationFailure>提供更详细的描述信息。2.5.4. proxy callback如果一个服务想代理一个客户端到终端服务（Back-end service）的认证，他必须获得一个PGT（proxy-granting ticket，代理授予凭证）。要获取这个凭证是受代理回调URL控制的。这个URL将唯一的和安全的识别终端服务，并且代理客户端的认证请求。终端服务然后基于自身的识别回调URL来决定是否接受这个证书。The proxy callback mechanism works as follows: 代理回调机制的工作流程如下：1.The service that is requesting a proxy-granting ticket specifies upon initial service ticket or proxy ticket validation the HTTP request parameter "pgtUrl" to /serviceValidate (or /proxyValidate). This is a callback URL of the service to which CAS will connect to verify the service's identity. This URL MUST be HTTPS, and CAS MUST verify both that the SSL certificate is valid and that its name matches that of the service. If the certificate fails validation, no proxy-granting ticket will be issued, and the CAS service response as described in Section 2.5.2 MUST NOT contain a <proxyGrantingTicket> block. At this point, the issuance of a proxy-granting ticket is halted, but service ticket validation will continue, returning success or failure as appropriate. If certificate validation is successful, issuance of a proxy-granting ticket proceeds as in step 2. 1.想使用代理认证的服务需要一个PGT，这个PGT来自初始的ST或者PT，并且是通过设置HTTP请求参数“pgturl”在/serviceValidate（或/ proxyValidate）上确认才得到的。这就是一个服务的回调URL，CAS服务器将链接到它并且验证服务的身份信息。这个URL必须是HTTPS的，并且CAS必须确认SSL证书是有效的，并且它的名字与它请求的服务相匹配。如果证书验证失败，将不发放PGT，并且就像第2.5.2节中描述的，必须使CAS服务返回的XML中<proxyGrantingTicket>不包含PGT。在这一点上，PGT停止发布，但ST验证仍将继续，还要根据现状返回成功或失败。如果证书验证成功，发行PGT的过程见如下第2步。2.CAS uses an HTTP GET request to pass the HTTP request parameters "pgtId" and "pgtIou" to the pgtUrl. These entities are discussed in Sections 3.3 and 3.4, respectively. 2.CAS使用HTTP GET请求传递HTTP请求的参数“ pgtId ”和“ pgtIou ”到pgtUrl。实际上是在具有代理功能的客户端配置的一个servlet。这些实体将在第3.3和3.4中讨论。3.If the HTTP GET returns an HTTP status code of 200 (OK), CAS MUST respond to the /serviceValidate (or /proxyValidate) request with a service response (Section 2.5.2) containing the proxy-granting ticket IOU (Section 3.4) within the <cas:proxyGrantingTicket> block. If the HTTP GET returns any other status code, excepting HTTP 3xx redirects, CAS MUST respond to the /serviceValidate (or /proxyValidate) request with a service response that MUST NOT contain a <cas:proxyGrantingTicket> block. CAS MAY follow any HTTP redirects issued by the pgtUrl. However, the identifying callback URL provided upon validation in the <proxy> block MUST be the same URL that was initially passed to /serviceValidate (or /proxyValidate) as the "pgtUrl" parameter. 3.如果HTTP的GET返回HTTP状态码200 （正常），CAS必须以服务响应的方式响应/serviceValidate （或/proxyValidate ）的请求（第2.5.2节），并且在响应返回的XML的<cas:proxyGrantingTicket>节点上包含PGTIOU（Proxy-granting ticket IOU）（第3.4节）。如果HTTP GET返回的是其他状态码，除的HTTP 3xx重定向外，CAS必须以服务响应的方式响应/serviceValidate （或/ proxyValidate ）的请求，并且在响应返回的XML中不能包含<cas:proxyGrantingTicket>块。CAS可跟踪pgturl传出的任何HTTP重定向。但不管怎样，在<proxy>节点中提供验证的回调URL，必须与最初通过/ serviceValidate （或/ proxyValidate ）的“pgturl”参数相同。4.The service, having received a proxy-granting ticket IOU in the CAS response, and both a proxy-granting ticket and a proxy-granting ticket IOU from the proxy callback, will use the proxy-granting ticket IOU to correlate the proxy-granting ticket with the validation response. The service will then use the proxy-granting ticket for the acquisition of proxy tickets as described in Section 2.7. 4.代理服务，收到CAS服务器返回的PGTIOU，并且通过代理回调还能获得一个PGT（事实上返回的PGT和PGTIOU都被存储下来），然后通过使用PGTIOU与与PGT进行匹配。这样就能找到需要的PGT，利用这个PGT就可以得到PT（proxy-ticket）。参见第2.7节。2.5.5. URL examples of /serviceValidateSimple validation attempt: https:/server/cas/serviceValidate?service=http%3A%2F%2F&ticket=ST-1856339-aA5Yuvrxzpv8Tau1cYQ7Ensure service ticket was issued by presentation of primary credentials: https:/server/cas/serviceValidate?service=http%3A%2F%2F&ticket= ST-1856339-aA5Yuvrxzpv8Tau1cYQ7&renew=truePass in a callback URL for proxying: https:/server/cas/serviceValidate?service=http%3A%2F%2F&ticket=ST-1856339-aA5Yuvrxzpv8Tau1cYQ7&pgtUrl=https:/my-server/myProxyCallback2.6. /proxyValidate CAS 2.0/proxyValidate必须执行与/serviceValidate相同的验证任务，并且还要验证PT。/proxyValidate必须能够验证ST和PT。2.6.1. parameters/proxyValidate与/serviceValidate所使用的参数完全相同，请参见2.5.1。2.6.2. response/proxyValidate能够返回一个格式化的CAS服务响应XML，此XML的结构参见附录一。On ticket validation success: <cas:serviceResponse xmlns:cas='http:/www.yale.edu/tp/cas'> <cas:authenticationSuccess> <cas:user>username</cas:user> <cas:proxyGrantingTicket>PGTIOU-84678-8a9d.</cas:proxyGrantingTicket> <cas:proxies> <cas:proxy>https:/proxy2/pgtUrl</cas:proxy> <cas:proxy>https:/proxy1/pgtUrl</cas:proxy> </cas:proxies> </cas:authenticationSuccess></cas:serviceResponse>请注意，当认证已开始通过多重代理进行时，一组代理的顺序要反映在<cas:proxies>块中。最近访问代理必须首先出现在代理链上，然后按照代理的新旧顺序依次添加到代理链上。在上面的例子中，服务确定的第一个访问代理的网址是：https：/proxy1/pgtUrl，并且服务的代理认证是依靠第二个URL-https：/proxy2/pgtUrl辨别出来的。注：代理链<cas:proxies>里面放的是一组代理，是指获取PT的路径。它的顺序代表着同被代理者的远近关系，同被代理者更近的代理者出现在更前面。On ticket validation failure: <cas:serviceResponse xmlns:cas='http:/www.yale.edu/tp/cas'> <cas:authenticationFailure code="INVALID_TICKET"> ticket PT-1856376-1HMgO86Z2ZKeByc5XdYD not recognized </cas:authenticationFailure></cas:serviceResponse>2.6.3 URL examples of /proxyValidate/proxyValidate与/serviceValidate一样接受相同的参数。参阅第2.5.5使用范例。2.7. /proxy CAS 2.0/proxy提供到服务的PT，并且这个服务是获取了PGT的，并且可以为后端服务做代理认证。2.7.1. parameters下面的HTTP请求的参数是/proxy必须指定的。他们都区分大小写。 pgt 需要 代理服务在验证ST和PT后所获取的PGT。 targetService 需要 -后端服务的标识符。请注意，并非所有的后端服务都是web服务，因此这一标识符不会永远是URL。但是不管怎样，这里指定的服务标识符必须匹配访问/proxyValidate时的“service”参数。2.7.2. response/proxy能够返回一个格式化的CAS服务响应XML，此XML的结构参见附录一。On request success: <cas:serviceResponse xmlns:cas='http:/www.yale.edu/tp/cas'> <cas:proxySuccess> <cas:proxyTicket>PT-1856392-b98xZrQN4p90ASrw96c8</cas:proxyTicket> </cas:proxySuccess></cas:serviceResponse>On request failure: <cas:serviceResponse xmlns:cas='http:/www.yale.edu/tp/cas'> <cas:proxyFailure code="INVALID_REQUEST"> 'pgt' and 'targetService' parameters are both required </cas:proxyFailure></cas:serviceResponse>2.7.3. error codes下面的值可能被用来作为验证失败时“code”属性的值。以下是最低限度的错误代码，所有CAS服务器必须实现的，当然还包括其他一些实现。 INVALID_REQUEST -请求参数不全。上面讲到至少必须有“service”和“ticket”两个参数。 BAD_PGT -提供的PGT无效。 INTERNAL_ERROR 在ticket验证时发生内部错误。对于所有的错误代码，CAS推荐为<cas:authenticationFailure>提供更详细的描述信息。2.7.4. URL example of /proxySimple proxy request: https:/server/cas