如何使用 Rally.RestApi.dll 进行单点登录? [英] How to SSO using Rally.RestApi.dll?

问题描述

直到现在，我才知道 Rally RestAPI 不支持 SSO 登录.我相信这在 2014 年 1 月不再适用.相同的 API 用于 Excel 的 Rally Add-in(这里是 Rally Add-in for Excel)，支持 SSO 登录.我能否获得 Rally Excel 插件的源代码，或者至少有人请提供一个使用 Rally RestAPI 的 SSO 示例?

Until now, I have read that Rally RestAPI do not support SSO login. I believe this is no longer true as of Jan 2014. The same API is used in Rally Add-in for Excel (here is link for Rally Add-in for Excel) which support SSO login. Can I get either the source code of Rally Excel Add-in or at least someone please provide an example of SSO using Rally RestAPI?

我想做与 Excel 插件导出功能完全相同的事情，但想在纯 .net 应用程序中做.

I want to do exactly the same thing what Excel Addin Export functionality does but want to do in pure .net application.

推荐答案

我在 C# Rest Api 中添加了一个 howto，解释了如何像 Rally 在 Excel 插件中所做的那样进行 SSO 身份验证.为了方便，我把它贴在这里.

I have added a howto to the C# Rest Api that explains how to do an SSO authentication like Rally does in the Excel plugin. I am pasting it here for convenience.

谢谢，斯科特

Rally Web 服务 API (WSAPI) 本身仅支持基本身份验证.使用基本身份验证，WSAPI 会话必须使用用户名和密码启动，该用户名和密码根据直接存储在 Rally 中的用户名和密码列表进行验证.在客户端开始使用单点登录 (SSO) 之前，这可以正常工作.SSO 允许客户端使用单个企业范围的身份验证机制(如 LDAP 或 Active Directory)来管理用户凭据和密码.到目前为止，在启用 SSO 的情况下使用 WSAPI 要求客户端在 Rally 中为所有希望使用 Rally WSAPI 的用户维护一个重复的用户列表(白"列表).最近对 Rally 的更改现在允许 WSAPI 用户使用其 SSO 凭据访问 Rally，并减少将这些用户保留在白"名单中的需要.

The Rally Web Services API (WSAPI) natively supports only Basic Authentication. Using Basic Authentication, WSAPI sessions must be initiated with a username and password that is validated against a list of usernames and passwords stored directly in Rally. This works fine until clients begin using Single Sign On (SSO). SSO allows clients to use a single enterprise-wide authentication mechanism (like LDAP or Active Directory) to manage user credentials and passwords. Until now, using WSAPI with SSO enabled has required clients to maintain a duplicate user list (the "white" list) in Rally for all users who wish to use the Rally WSAPI. Recent changes to Rally now allow WSAPI users to access Rally using their SSO credentials and alleviate the need to maintain those users in the "white" list.

注意:Rally 当前的 SSO 实现基于 SAML 规范，该规范要求用​​户与浏览器交互以完成身份验证.因此，这种技术需要用户与浏览器进行交互，因此它与无头 WSAPI 客户端不兼容，例如将 Rally 与 VCS 和错误跟踪工具同步的客户端.

Note: Rally's current SSO implementation is based on the SAML specification which requires a user to interact with a browser to complete authentication. As such, this technique requires the user to interact with a browser, so it is incompatible with headless WSAPI clients like those that synchronize Rally with VCS and bug tracking tools.

在发起 SSO 连接时，用户提供一个 URL，该 URL 开始与 Rally 的服务提供者 (SP) 进行 SSO 握手，稍后涉及客户端的身份提供者 (IdP)，并以 Rally 用代表有效身份验证会话的 cookie 响应结束.如果经过身份验证的会话 cookie 包含在任何后续 WSAPI 调用中，Rally 会将这些调用与经过身份验证的用户相关联，并且 WSAPI 调用将被验证.为了在成功的 SAML SSO 身份验证后轻松访问经过身份验证的会话 cookie 以进行 WSAPI 调用，Rally 查找添加到初始 SSO URL 的参数，如果存在，将返回一个包含会话 cookie 的特殊网页.文本作为 SSO 握手的最终产品.用户可以使用该数据构建一个 cookie，以便在后续 WSAPI 调用中使用.

When initiating an SSO connection, the user provides a URL that starts the SSO handshake with Rally's Service Provider (SP), later involving the client's Identity Provider (IdP), and finishes with Rally responding with cookies that represent a valid authenticated session. If that authenticated session cookie is included in any subsequent WSAPI calls, Rally will associate those calls with the authenticated user and the WSAPI calls will be authenticated. To make it easy to get access to the authenticated session cookie for purposes of WSAPI calls following a successful SAML SSO authentication, Rally looks for a parameter added to the initial SSO URL that if present will return a special web page containing the session cookie in clear text as the final product of the SSO handshake. Users can use that data to construct a cookie to be used in subsequent WSAPI calls.

注意:下面的示例 URL(可能)特定于 Rally 的内部 SSO 实现.由于 SSO 用于允许客户使用他们自己的 SSO 基础设施(至少是 IdP 部分)提供他们自己的身份验证，因此 SSO URL 将是客户特定的.请联系您的 Rally TAM 或 Rally 支持以获取有关 SSO URL 的帮助.

Note: The example URLs below are (potentially) specific to Rally's internal SSO implementation. Since SSO is used to allow customers to provide their own authentication using their own SSO infrastructure (at least the IdP part), SSO URLs will be customer specific. Contact your Rally TAM or Rally Support for help with SSO URLs.

原始 SSO URL 类似于:

An original SSO URL looks something like:

 https://sso.rallydev.com/sp/startSSO.ping?PartnerIdpId=pingidp.f4tech.com-29577

特殊参数是:

 TargetResource=https://us1.rallydev.com/slm/j_sso_security_check?noRedirect=true

注意:此名称/值对使用 PingIdentity 作为 SSO 提供程序在 Rally 的特定 SSO 实现中设置 SSO RelayState.其他 SSO 提供程序可能具有用于设置 RelayState 的不同参数名称.例如，一些 SSO 提供程序使用 RelayState 作为参数名称.在任何情况下，该值始终相同(即https://us1.rallydev.com/slm/j_sso_security_check?noRedirect=true")

Note: This name/value pair sets the SSO RelayState in Rally’s specific SSO implementation using PingIdentity as the SSO provider. Other SSO providers may have a different parameter name used to set the RelayState. For instance, some SSO providers use RelayState as the parameter name. In any case, the value is always the same (i.e. "https://us1.rallydev.com/slm/j_sso_security_check?noRedirect=true")

所以一个完整的 URL 应该是这样的:

So a complete URL would look like:

 https://sso.rallydev.com/sp/startSSO.ping?PartnerIdpId=pingidp.f4tech.com-29577&TargetResource=https://us1.rallydev.com/slm/j_sso_security_check?noRedirect=true

如果用户导航到此修改后的 SSO URL，在身份验证后，他们将看到包含以下内容的网页:

If a user navigates to this modified SSO URL, after authentication, they will be presented with a web page that contains the following:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
    <head>
        <title>SSO Token</title>
    </head>
    <body>
        <form>
            <input type="hidden" name="authCookieName" value="ZSESSIONID"/>
            <input type="hidden" name="authCookieValue" value="khkjhkhkhkhkjhh"/>
        </form>
    </body>
</html>

如果用户根据此页面中包含的数据创建 cookie 并将该 cookie 与他们后续的 WSAPI 调用一起传递，则这些调用将成功通过身份验证.请注意，必须根据 IETF cookie 规范从为获取 cookie 进行的调用中推断出可选的 cookie 数据，如安全和路径.

If the user creates a cookie based on the data contained in this page and passes that cookie along with their subsequent WSAPI calls, those calls will be successfully authenticated. Note that optional cookie data like secure and path must be inferred from call made to obtain the cookie as per the IETF specification for cookies.

因此，为了发出 WSAPI 调用，从 GUI 界面登录 Rally 的基本过程(同样，这不适用于无头环境)如下:

So the basic process for logging into Rally from a GUI interface (again, this does not work for headless environments) for the purpose of issuing WSAPI calls is the following:

• 使用上述特殊参数从用户那里收集 SSO URL.
• 启动指向该 URL 的浏览器.
• 导航完成后，从返回的 HTML 页面中抓取 cookie 值.
• 关闭浏览器.
• 根据 cookie 值构造一个 cookie.
• 存储该 cookie 以备后用.
• 随所有后续 WSAPI 调用发送该 cookie.

如果使用此 cookie 进行身份验证的 WSAPI 调用失败，请重复此过程.请记住，这些 cookie 会过期，您应该准备好在重新进行身份验证后重试失败的调用，以创建流畅的用户体验.

Repeat this process if the a WSAPI call fails for authentication using this cookie. Remember that these cookies expire and you should be prepared to retry a failed call after re-authentication to create a smooth user experience.

Rally C# Rest API 将一种机制集成到其连接框架中，以简化不同 GUI 客户端的此过程，包括会话超时后的自动重新身份验证.这包括将令牌页面解析为有效 cookie 的方法.该库的调用者可以实现其他功能，例如推断可选的 cookie 数据(如域、路径、安全和主机端口)，以解决 Rally 不返回完整 cookie 数据的情况(如测试环境).

The Rally C# Rest API has a mechanism integrated into it's connection framework to make this process easy for different GUI clients including automatic re-authentication following session timeout. This includes methods to parse the token page into a valid cookie. Callers of this library can implement other features such as inferring optional cookie data (like domain, path, secure, and host port) to account for situations (like test environments) where Rally does not return complete cookie data.

使用 C# ReST API 连接到 Rally 意味着构建 RallyRestApi 的实例.有两个传统构造函数假定基本身份验证并在其他参数中使用用户名和密码.使用这些构造函数之一构造 RallyRestApi 将始终使用基本身份验证，永远不会使用 SSO.

Connecting to Rally using the C# ReST API means constructing an instance of RallyRestApi. There are two legacy constructors that assume Basic Authentication and take username and password among other parameters. Constructing a RallyRestApi using one of these constructors will always use Basic Authentication and will never use SSO.

第三个构造函数只接受一个 IConnectionInfo 对象.这是获取 RallyRestApi 的首选方式.使用 IConnectionInfo 对象构建 RallyRestApi 允许调用者在一个对象中指定所有连接信息，该对象可用于多个 RallyRestApi 实例之间的 SSO 回调和身份验证共享.

A third constructor takes only an IConnectionInfo object. This is the preferred way to obtain a RallyRestApi. Using an IConnectionInfo object to construct a RallyRestApi allows the caller to specify all connection information in one object that can be used for SSO callbacks and authentication sharing between multiple RallyRestApi instances.

为了方便 SSO 身份验证，C# ReST API 引入了 IConnectionInfo 接口和 ConnectionInfo 类.这些类代表一个对象，该对象包含连接首选项，并且可以在请求时启动和完成基于浏览器的 SSO 身份验证会话.ConnectionInfo 类实现所有连接首选项，并具有将 Rally SSO 登录页面解析为可用 Cookie 的方法.如果只需要基本身份验证，则可以按原样使用此类.IConnectionInfo 可在调用者不想扩展或以其他方式使用 ConnectionInfo 的情况下提供灵活性.

To facilitate SSO authentication, the C# ReST API introduced the IConnectionInfo interface and the ConnectionInfo class. These classes represent an object that holds connection preferences and can initiate and complete a browser based SSO authentication session when requested to do so. The ConnectionInfo class implements all of the connection preferences and has methods to parse the Rally SSO landing page into a usable Cookie. This class can be used as is if only Basic Authentication is required. IConnectionInfo is there for flexibility in case the caller does not want to extend or otherwise use ConnectionInfo.

当使用 IConnectionInfo 进行基本身份验证时，只需创建一个新的 ConnectionInfo 并设置适当的可公开访问的字段.使用它来构建一个 RallyRestApi.任何身份验证错误都会引发异常.

When using IConnectionInfo for Basic Auth simply create a new ConnectionInfo and set the appropriate publicly accessible fields. Use that to construct a RallyRestApi. Any authentication errors will throw exceptions.

Example:

var cInfo = new ConnectionInfo();
cInfo.UserName = "myName";
cInfo.Password = "pass";
cInfo.Server = new Uri("https://host.com");
cInfo.AuthType = Rally.RestApi.AuthorizationType.Basic;

var conn = new RallyRestApi(cInfo);

将 IConnectionInfo 用于 SSO 时，调用者必须实现 DoSSOAuth().下面是一个带注释的例子.

When using IConnectionInfo for SSO, the caller must implement DoSSOAuth(). Below is an annotated example.

public class MyConnectionInfo : Rally.RestApi.ConnectionInfo
{
    public override void doSSOAuth()
    {
        // Launch a browser to the this.server URI.
        // The browser will close automatically if it successfully reaches the SSO landing page 
        // Users can cancel the SSO handshake
        // Abort if the handshake is successful, but didn't arrive at the SSO landing page
        var ssoDialog = new SSOAuthDialog(server);
        DialogResult result = ssoDialog.ShowDialog();
        if (result == DialogResult.Cancel)
            throw new Exception("SSO authorization canceled");
        else if (result == DialogResult.Abort)
            throw new Exception(ssoDialog.abortReason);

        // Parse the SSO landing page into a Cookie and save it
        AuthCookie = parseSSOLandingPage(ssoDialog.getBrowser().DocumentText);

        // Infer Cookie values from SO Landing Page URL if not set
        if (String.IsNullOrWhiteSpace(authCookie.Domain) || authCookie.Domain == "null")
            authCookie.Domain = ssoDialog.getBrowser().Url.Host;
        AuthCookie.Secure = String.Equals(ssoDialog.getBrowser().Url.Scheme,"https",StringComparison.InvariantCultureIgnoreCase);

        // Set a specific port port if the SSO Landing Page URL has one
        if (!ssoDialog.getBrowser().Url.IsDefaultPort)
            Port = ssoDialog.getBrowser().Url.Port;
    }
} 

此示例使用带有浏览器组件的 WinForms 对话框向用户呈现 SSO 握手.请记住，您可以使用任何想要实现此部分的显示技术.这是一个带注释的示例:

This example uses a WinForms dialog with a browser component to present the SSO handshake to the user. Remember, you can use any display technology you want to implement this part. Here is an annotated example:

public partial class SSOAuthDialog : Form
{
    public String abortReason;

    public SSOAuthDialog(Uri url)
    {
        InitializeComponent();
        webBrowser.Url = url;
    }

    private void documentCompleted(object sender, WebBrowserDocumentCompletedEventArgs e)
    {
        // We have found the SSO Landing Page.
        if (webBrowser.DocumentText.Contains("authCookieName") && webBrowser.DocumentText.Contains("authCookieValue"))
        {
            Trace.TraceInformation("Found SSO authentication token on page: {0}", e.Url.AbsolutePath);
            DialogResult = DialogResult.OK;
            Close();
        }

        // We have landed on the Rally ALM page
        // This is usually caused by a bad URL 
        else if (webBrowser.DocumentText.Contains("window.FEATURE_TOGGLES"))
        {
            abortReason = String.Format("The SSO handshake was successful, but the 'RelayState' was not correctly set. Contact your administrator to obtain the correct URL parameter to set the SSO handshake 'RelayState' to: https://rally1.rallydev.com/slm/j_sso_security_check?noRedirect=true");
            Trace.TraceError(abortReason);
            DialogResult = DialogResult.Abort;
            Close();
        }
    }

    public WebBrowser getBrowser()
    {
        return webBrowser;
    }
}

SSO Example:

var cInfo = new MyConnectionInfo();
cInfo.Server = new Uri("https://host");
cInfo.AuthType = Rally.RestApi.AuthorizationType.SSO;

// This will cause an SSO authentication event
var conn = new RallyRestApi(cInfo);
// This will not b/c it will just use the auth Cookie already in cInfo
var conn2 = new RallyRestApi(cInfo);

将 IConnectionInfo 用于 SSO 时，重要的是缓存您发送以构建 RallyRestApi 的 IConnectionInfo 对象.成功 SSO 握手后，生成的身份验证 Cookie 存储在 IConnectionInfo 对象中，并将用于从该 RallyRestApi 对象进行的所有后续 WSAPI 调用.如果您需要使用之前成功的 SSO 登录的相同 auth Cookie 创建另一个 RallyRestApi 对象，只需使用相同的 IConnectionInfo 对象构造一个新的 RallyRestApi 对象，如果存在 auth Cookie，它将被使用.

When using IConnectionInfo for SSO, it is important to cache the IConnectionInfo object that you send to construct a RallyRestApi. After a successful SSO handshake, the resulting auth Cookie is stored in the IConnectionInfo object and will be used for all subsequent WSAPI calls made from that RallyRestApi object. If you need to create another RallyRestApi object using the same auth Cookie from a previously successful SSO login, simply construct a new RallyRestApi object with the same IConnectionInfo object and if there is an auth Cookie present, it will be used.

授权 Cookie 可能会过期.C# ReST Api 将检测过期的 SSO Cookie，并将根据需要启动新的 SSO 登录会话以获取新的有效 Cookie.

Authorization Cookies can expire. The C# ReST Api will detect an expired SSO Cookie and will initiate a new SSO login session as needed to obtain a new valid Cookie.

仅此而已.

这篇关于如何使用 Rally.RestApi.dll 进行单点登录?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！