GitLab.com におけるカスタムドメインの検証
概要
GitLab 10.5 で、GitLab Pages のカスタムドメインに対する検証システムが導入されました。これは GitLab.io が提供するカスタムドメインに影響するセキュリティ対策で、未承認のユーザーによるドメインのハイジャックを防ぎます。
検証では、GitLab が生成したコードをドメインの DNS レコードに追加します。詳細は このドキュメントページ で確認できます。
ドメインは検証済みまたは未検証のいずれかであり、別途、有効化または無効化のいずれかの状態を取ります。新しいドメインが追加されたときは、未検証かつ無効化された状態です。一度検証されると、検証済みかつ有効化された状態になります。検証は定期的に再実行されます。検証に失敗した場合、ドメインは未検証となりますが、7 日間の猶予期間中は 有効化されたまま 残ります。猶予期間が経過すると、ドメインは期限切れとなり、無効化されます。
データベース内の既存のカスタムドメインには 30 日間の猶予期間が与えられます。その期間内に必要な TXT レコードが追加されない場合、これらのドメインも無効化されます。
ロギング
カスタムドメインの状態変化は Rails の application.log に記録され、所有プロジェクトのすべての Maintainer にメールで通知されます。GitLab.com のイベントは Kibana で確認でき、ドメイン名で検索すれば過去 1 週間に行われた操作を確認できます。
CNAME および A レコードとの相互作用
カスタムドメインを GitLab.io に向けるには、DNS に CNAME または A レコードを追加する必要があります。CNAME を使用する場合、同じドメイン名上で TXT レコードと共存させることはできません。代わりに、_gitlab-pages-verification-code.example.com のように特別なサブドメインで作成する必要があります。
CNAME レコードが使用されているかは、次のコマンドで確認できます:
dig +short cname example.com
このコマンドが何らかの出力を返す場合、後続の手順で検証用の TXT レコードを必ず特別なサブドメイン側に存在させる必要があります。
TXT レコードの確認
サポートへの依頼は、ユーザー側で検証コードを正しく DNS に追加したつもりなのにドメインが検証されない、というものが中心になります。次のコマンド（example.com を正しいドメインに置き換えてください）を実行してカスタムドメインの TXT レコードを確認できます:
dig +short txt example.com
dig +short txt _gitlab-pages-verification-code.example.com
これらのコマンドの片方または両方が、次の形式の行を出力するはずです:
"gitlab-pages-verification-code=78c8e1eb3311aecb7d6cffd1bc2e0e0f"
（複数行あっても、コードが行の途中に他のデータと混在していてもかまいません。空白で他のデータから区切られていれば問題ありません）
管理ユーザーであれば、GitLab.com のプロジェクトを開き、Settings ➔ Pages に移動して該当のカスタムドメインの Details ボタンを押すと、正しい検証コードを確認できます。
Rails コンソールで次を実行することでもコードを確認できます:
PagesDomain.find_by!(domain: "example.com").verification_code
レコードがまったく存在しないか、検証コードが一致しない場合、お客様は DNS レコードを正しく構成していません。その旨を伝え、ドキュメントへのリンクを送ることができます。誤ったレコードは TXT レコードの TTL の期間キャッシュされるため、誤ったレコードをアップロードしたあと、検証成功までに遅延が発生する可能性がある点に注意してください。
レコードが存在する場合、GitLab がレコード追加後にまだ検証チェックを実行していない可能性があります。カスタムドメイン詳細ページの Verify ownership ボタンを押すと、即時かつ同期的なチェックが実行され、検証が成功する可能性があります。
このチェックでドメインが検証できず、TXT レコードが直近で追加または変更されたものである場合、最も可能性の高い説明は、それ以前の失敗したチェックの結果として、失敗時のレコードが GitLab.com の使用する DNS サーバーにキャッシュされていることです。
これらのレコードがキャッシュされる時間は、ドメイン所有者が制御します:
- 「ネガティブ・ルックアップ」がキャッシュされた場合、その時間は SOA レコード の
MINIMUMフィールドで指定されます。 - 誤ったコードを含む TXT レコードは、TXT レコードの
TTLフィールドで指定された時間キャッシュされます。
ドメインの期限切れが間近でなければ、お客様にキャッシュの期限切れを待つようにお願いするだけで構いません。そうでない場合は、以下の手順に従って残りのキャッシュ時間より長い期間まで猶予期間を延長することを検討してください。
最後に、GitLab に実際のバグがあって検証が進まないケースもあり得ます。そうしたケースに遭遇したら報告し、以下の手順でドメインの猶予期間を手動で延長することができます。
カスタムドメインを手動で有効化する
警告: お客様がそのドメインの正当な所有者であると確信している場合にのみ、カスタムドメインを手動で検証してください。これは一般的には判断が難しい問題です。判断に迷う場合は、検証コードが正しく DNS に存在することにこだわり、それなしには何も行わないでください。
キャッシュまたは GitLab のバグが原因で検証が成功しない場合、Rails コンソールで次のコマンド（example.com を正しいドメインに置き換えてください）を実行することで、カスタムドメインが無効化されないようにできます:
PagesDomain.find_by!(domain: "example.com").update!(enabled_until: 1.month.from_now)
これによりドメインの検証完了までの期間が 1 か月延長され、期限切れになっていた、または一度も検証されたことのないドメインも有効化されます。これはキャッシュの期限切れまでの時間としても、バグの修正までの時間としても十分な長さです。
bfd74782)