Insight Technology

2021.07.05

ひとくちGitLab ~GitLabのTokenについて~

このエントリーをはてなブックマークに追加

こんにちは。インサイトテクノロジー札幌R&Dセンターの笹谷です。
好きなボトラーは大手ならディアジオ、インディペンデントボトラーならG&M、ElixirDistillersです。
業務ではGitLabを用いたCI/CDの構築、開発プロセスの改善、最近はAWS環境の自動構築とGitLabCI/CDとの連携を担当しております。
これまでGitLab CI/CD 基本編GitLab CI/CD 実践編GitLab CI/CD 発展編と題し、GitLab CI/CDや GitLab Runnerについて、それなりのボリュームでお話してきました。
今回は趣向を変え、GitLabで扱うTokenについて、スナック感覚で読めるボリュームでお話します。

GitLabで扱うTokenの種類

一般的に、Tokenは、サーバがクライアントに対して有効期限が定義可能なtokenを発行し、APIリクエスト時に付随されたTokenを照合することで、クライアントを認証する仕組みです。
例えばGitHubやGitLabのようなリモートレポジトリ管理サイトはもちろん、SlackなどでもAPI利用の際には、管理コンソールで発行されたtokenの利用が前提とされています。

GitLabにおいて、パスワード認証は強い権限が付与されます。そのため、スクリプトによる自動化や、ユーザの権限を制限した状態でのレポジトリへのアクセス、またはAPIを利用するような状況では、GitLab Tokenによる認証が便利です。

GitLabのTokenには、以下の種類があります。

  • Personal access tokens
    • GitLab API, GitLab repository, GitLab registryへの各アクセスの可否を設定して発行
  • OAuth2 tokens
    • GitLabをOAuth2 ProviderとしてOAuth認証を実装可能な仕組み
  • Impersonation tokens
    • Personal access tokensの特殊な形で、管理者が既存の別ユーザになりかわって作業可能にするtoken
  • Project access tokens
    • Project単位版のPersonal access tokens
  • Deploy tokens
    • git cloneおよびGitLab管理下のpackageとcontainer registryへのpush/pullを可能にする。API操作はできない。
  • Deploy keys
    • repositoryのread-onlyまたはread-writeのみ可能とする。
    • Projectのowner/maintainerが発行可能で、CIでrepositoryをcloneしてくるのに有用。APIやregistry操作はできない。
  • Runner registration token
    • GitLabRunnerをGitLab側に登録する際に認証するためのtoken
    • Project/Group repository単位でCI/CDのjobを実行するRunnerを紐付ける
    • RunnerのregistrationについてはGitLab CI/CD 応用編で詳しく紹介しています
  • Runner authentication token
    • GitLabRunnerの認証登録後にRunnerが入ったホストに登録されるtoken
    • config.toml内に自動登録される
  • CI/CD Job token
    • CI/CD job実行時のAPI利用の際に認証に使用される一時的なtoken
    • CI/CDのjob内でrepositoryをclone,pushなどする際、CI_JOB_TOKENとして予め環境変数に定義されているものを即座に利用可能

GitLab Tokenの用途と位置づけ

各Tokenの用途について端的に示すと、以下のようになります。

複数projectにまたがって、API/Repository/Registryに対するアクセスを許可するtoken
-> Personal Access Tokens

単一project限定で、API/Repository/Registryについてのアクセスを許可するtoken
-> Project Access Tokens(分類上はPersonal Access Tokensに含まれる)

GitLabだけでなく、別サービスを対象としてOAuth2認証tokenを発行したい場合
-> OAuth2 tokens(OAuth2 Provider)

単一および複数projectにおいて、管理者として別ユーザ名でのアクセスやアクションを実施したい場合
-> Impersonation token(分類上はPersonal Access Tokensの特殊系とされる)

ProjectまたはGroupに対して、Repository,Registryに関する操作のみ許可し、APIへの操作を制限するtokenがほしい場合
-> Deploy Tokens

主にCI/CDの場面で、ProjectまたはGroupに対して、Repositoryに関する操作のみ許可し、API,Container Registryへの操作を制限するtokenがほしい場合 -> Deploy Keys

GitLab RunnerにGitLabのproject/groupを登録する際に用いる自動生成token
-> Runner Registration Tokens

GitLab Runner側にRunner Registration Tokensとは別に自動登録されるtoken
-> Runner authentication tokens

GitLab CI/CDにおいて、job実行時に自動発行される、job内からRepositoryおよび一部APIエンドポイントへのアクセスを許可するtoken
-> CI/CD job token

GitLab.comにおけるTokenの発行の例

Project用PersonalAccessToken

以下は、ProjectをScopeとしたPersonalAccessTokenの発行の具体的手順です。 Owner/Maintainerの権限を持ったアカウントでGitLab.comにログインし、Tokenを発行したいProjectのSettings -> AccessTokensへ settings-access-tokens.png

Token nameを設定 Expiration dateで有効期限を設定できるので、一時的な利用であれば短期間のものを発行すると、管理しやすい 例えば期間限定でjoinするメンバー用に発行するなど token-expiration-date.png"

  • Select scopesでこのTokenでどこまでの操作を可能にするかを絞れる
    • APIを実行してproject内のissue一覧を取得するだけの用途であれば、read_apiだけを有効にする
    • ContainerRegistryにimageをpull/pushのみ実施するのであれば、read registry/write registryを有効にする

最後にCreateAccessTokenをクリックすると、tokenが発行されます。
すぐにクリップボードにコピーし、利用時まで適宜保管しておきましょう。 access-token-created.png"

上記で2021/08/31までの、Sandbox Projectを対象としたAPI操作可能なtokenを発行しました。
発行されたtokenは、名前、作成日時、利用履歴、有効期限、スコープの情報付きで管理されているのがわかります。 active-token.png"

実際に使う場合は、headerに記述してrequestすることで利用可能になります。今回はcurlでAPIを実行してみましょう。
GitLabのIssuesAPIで、issue id=13のissueから、issue title、作成日時、作成者名を抽出します。
private-token部分に、先程のtokenを入れています。

tsasaya@TSASAYA-L590:~$ curl -X GET --header "private-token:*************" "https://gitlab.com/api/v4/projects/*******/issues/13" | jq '. | .title, .created_at, .author.name'
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100  2438    0  2438    0     0   5429      0 --:--:-- --:--:-- --:--:--  5417
"調査:job内で加工したIssuesAPIベースのリリースノート文をreposにcommit/pushできるか"
"2021-02-03T04:49:02.370Z"
"笹谷泰輔"

調査issueのタイトル、作成日時、作成者が取れました。
ちなみに、Tokenを発行していないと、Loginを求めるHTMLとURLが返されます。
この要領で、APIからほしい情報を集めて別の場所に保存・通知するようなスクリプトなどで利用できます。

上記tokenを認証に使ってHTTPSでprojectをcloneする

ProjectAccessTokenのページに

You can also use project access tokens with Git to authenticate over HTTP(S). Learn more.

とあるように、access tokenは、OAuth2認証に利用できるため、以下のようにcloneすることもできます。
上記で作成したtokenはproject単位のtokenなので、別projectの認証では弾かれていることがわかります。

tsasaya@TSASAYA-L590:~$ git clone https://oauth2:*************@gitlab.com/group/subgroup/sandbox.git
Cloning into 'sandbox'...
remote: Enumerating objects: 572, done.
remote: Counting objects: 100% (73/73), done.
remote: Compressing objects: 100% (54/54), done.
remote: Total 572 (delta 49), reused 30 (delta 19), pack-reused 499
Receiving objects: 100% (572/572), 336.04 KiB | 2.54 MiB/s, done.
Resolving deltas: 100% (294/294), done.
tsasaya@TSASAYA-L590:~$ git clone https://oauth2:*************@gitlab.com/group/subgroup/set.git
Cloning into 'set'...
remote: HTTP Basic: Access denied
fatal: Authentication failed for 'https://oauth2:*************@gitlab.com/group/subgroup/set.git/'

終わりに

今回は、GitLab CI/CDよりも入門的なGitLab/GitLab.comの使い方に関する形で、GitLab Tokenを題材にお話しました。
これまでのエントリよりは設定ファイルやcodeも少なく、コンパクトに読んでいただけていれば幸いです。
これからGitLabのAPIを使い始める方、GitLab CI/CDを使い始める方は、下記の拙著の別エントリも合わせてご覧いただけると、より有益かもしれません。

どうやら弊社は開発メンバーを募集しているようです。ご興味があればjoin us。

GitLab CI/CD シリーズ

ページトップへ
DB TECH SHOWCASE テックギークに贈る、データテックカーニバル! 2021.11.17[WED]-19[FRI]/ONLINEDB TECH SHOWCASE テックギークに贈る、データテックカーニバル! 2021.11.17[WED]-19[FRI]/ONLINE