こんにちは。インサイトテクノロジー札幌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へ
Token nameを設定
Expiration dateで有効期限を設定できるので、一時的な利用であれば短期間のものを発行すると、管理しやすい
例えば期間限定でjoinするメンバー用に発行するなど
- Select scopesでこのTokenでどこまでの操作を可能にするかを絞れる
- APIを実行してproject内のissue一覧を取得するだけの用途であれば、read_apiだけを有効にする
- ContainerRegistryにimageをpull/pushのみ実施するのであれば、read registry/write registryを有効にする
最後にCreateAccessTokenをクリックすると、tokenが発行されます。
すぐにクリップボードにコピーし、利用時まで適宜保管しておきましょう。
上記で2021/08/31までの、Sandbox Projectを対象としたAPI操作可能なtokenを発行しました。
発行されたtokenは、名前、作成日時、利用履歴、有効期限、スコープの情報付きで管理されているのがわかります。
実際に使う場合は、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。
