認証: TestRail でのシングルサインオンの実装

TestRail と Active Directory などの外部認証システム、データベース、他のアプリケーション、API と統合してシングルサインオンを実装し、新規 TestRail ユーザーアカウントを作成することができます。このセクションでは、統合の技術的な詳細と独自の統合スクリプトを構築する方法について説明します。TestRail と Active Directory を統合する詳細な方法が知りたい場合は、このページを読んでください。

実装の詳細

TestRail は認証スクリプトをサポートしており、ほぼどのような外部システムとも統合できます。認証スクリプトをインストールすると、TestRail はユーザーがログインを試みたときにユーザーの認証情報が有効かどうかを確認します。

認証スクリプトが認証情報を検証する方法は、使用する外部認証システムによって異なります。たとえば、スクリプトがデータベースに照会してユーザー名とログイン情報を検証する場合があります。あるいは、API を呼び出して認証情報をチェックする場合もあります。認証情報の確認に使用された方法に関係なく、スクリプトは認証結果を TestRail に返してユーザーのログインを拒否または許可します。

スクリプトの基本

TestRail の認証スクリプトは、通常、PHP で作成されます。別のプログラミングツールや言語を使用して TestRail を統合したい場合、認証スクリプトから外部ツールまたは Web API を呼び出せば可能です。

TestRail 認証スクリプトの構造は非常に単純です。基本的に、実装する必要がある関数は authenticate_user の 1 つだけです。TestRail によってこの関数にユーザー名とパスワードが渡されます。認証情報を確認した後、スクリプトは認証結果を TestRail に返す必要があります。

// The anatomy of a basic authentication script
 
function authenticate_user($name, $password)
{
    // Verify the credentials and return result
    // ..
}

ヒント: ファイル末尾で <?php タグを閉じないことをお勧めします。これにより、ファイルの末尾に PHP の出力動作を変える可能性がある空白がないことが保証されます。

結果の返却

認証情報を確認した後、スクリプトは認証結果を TestRail に返す必要があります。これは、 AuthResult オブジェクトを作成し、関連するすべての引数を渡すことによって行われます。スクリプトは、スクリプトが依存している外部システムへの接続エラーなど、回復不可能なエラーを通知するために例外を発生させることもできます。次のセクションでは、TestRail に結果を返す方法について説明します。

エラーの通知

ユーザーの認証情報の検証中にエラーが発生した場合は、例外を発生させることをお勧めします。たとえば、スクリプトがデータベースに接続してユーザー名とパスワードを検証しようとしたが、データベースに到達できなかった場合は、適切なエラーメッセージを設定して例外を発生させます。TestRail の AuthException 例外型を使用することをお勧めします。

// The anatomy of a basic authentication script
 
function authenticate_user($name, $password)
{
    // Verify the credentials and return result
    // ..
}

認証の拒否

認証が失敗してユーザーアクセスが拒否されたとスクリプトが判断した場合は、AuthResultDenied クラスのインスタンスを作成して返します。

function authenticate_user($name, $password)
{
    // [..]
 
    return new AuthResultDenied();
}

認証の成功

ユーザーが認証された場合、AuthResultSuccess クラスのインスタンスを返します。TestRail は、認証結果を TestRail の内部ユーザーアカウントにリンクするためにユーザーの電子メールアドレスを必要とします。

ログイン名としてユーザーの電子メールアドレスを使用している場合は、ログイン名を TestRail に返すだけで済みます。それ以外の場合は、認証の一環として電子メールアドレスを検索する必要があります (たとえば、認証データベースまたは外部システムからユーザーの電子メールアドレスを読み取るなど)。

function authenticate_user($name, $password)
{
    // [..]
 
    return new AuthResultSuccess($user_email);
}

TestRail では、初めてログインしたユーザー用に新しいユーザーアカウントを自動的に作成することもできます。これは、すべての初期ユーザーアカウントを自動的に作成する優れた方法です。

たとえば、TestRail を Active Directory と統合したい場合、初めてログインしたユーザーのためにユーザーアカウントを作成するよう TestRail に指示できます。その後、ユーザーに電子メールで TestRail へのリンクを送信するだけで、TestRail は自動的に新しいユーザーアカウントを作成します。この機能を使用するには、TestRail にユーザーのフルネーム (名+姓) も指定する必要があります。

function authenticate_user($name, $password)
{
    // [..]
 
    $result = new AuthResultSuccess($user_email);
    $result->create_account = true;   // Create an account, if needed
    $result->name = $user_name;       // 'Bob Smith'
    $result->role_id = 3;             // Optional: ID of the user's role
    $result->group_ids = array(1, 2); // Optional: IDs of the user's groups    
    $result->is_admin = true;         // Optional: Admin privileges
    return $result;
}

認証のフォールバック

特定のユーザーを外部の認証システムで認証できない、または認証したくないが、TestRail のビルトインの認証システムを使用して認証したい場合があります。そのような場合は、TestRail 固有の認証システムにフォールバックするよう指示できます。もちろん、ケースバイケースでこれを行うことができます。

たとえば、ユーザーが Active Directory の認証情報でも、TestRail アカウントでもログインできるようにすることができます。ユーザーが (Active Directory のログイン名ではなく) ユーザ名として電子メールアドレスを入力した場合、このユーザーに関しては TestRail の認証システムを使用するように指示できます。それには、AuthResultFallback クラスのインスタンスを返します。

function authenticate_user($name, $password)
{
    // [..]
 
    return new AuthResultFallback();
}

インストール

スクリプトのインストールは、スクリプトのファイル名を auth.php として、TestRail インストールディレクトリ直下の /custom/auth/ に置くだけです。スクリプトが TestRail に追加されると、ユーザー認証に使用されます。TestRail の [管理] > [サイト設定] > [ログイン] で、認証スクリプトのパスとステータスを確認することもできます。

スクリプトを無効にするには、auth.php ファイルを削除するか名前を変更します。これでユーザーは自分の電子メールアドレスと TestRail パスワードでログインできるようになります。

認証: TestRail でのシングル サインオンの実装