- 個人アクセストークンの作成
- 個人アクセストークンの取り消し
- トークンが最後に使用された時刻の表示
- 個人アクセストークンのスコープ
- 個人アクセストークンの有効期限が切れた場合
- プログラムによるパーソナルアクセストークンの作成
- 個人アクセストークンをプログラムで取り消す
- 個人アクセストークンを使ったリポジトリのクローン
- トラブルシューティング
- 個人アクセストークンに代わるもの
個人アクセストークン
パーソナルアクセストークンはOAuth2の代替となり、以下のような用途に使用できます：
- GitLab APIでの認証。
- HTTP Basic認証を使ってGitを認証します。
どちらの場合も、パスワードの代わりに個人用のアクセストークンを使って認証します。
個人アクセストークンは以下の通りです：
- 二要素認証（2FA）が有効な場合に必要です。
- ユーザー名を必要とするGitLabの機能で認証するために、GitLabのユーザー名と一緒に使用します。例えば、GitLabが管理するTerraformステートバックエンドや Dockerコンテナレジストリなど、
- プロジェクトアクセストークンや グループアクセストークンと似ていますが、プロジェクトやグループではなくユーザーに付けられます。
個人アクセストークンを使った API 認証の例については、API ドキュメントをご覧ください。
別の方法として、GitLab 管理者は API を使ってなりすましトークンを作成することができます。なりすましトークンを使って、特定のユーザーとしての認証を自動化しましょう。
個人アクセストークンの作成
個人アクセストークンはいくつでも作成できます。
- 左のサイドバーで、自分のアバターを選択してください。
- プロフィールの編集を選択します。
- 左サイドバーで、アクセストークンを選択します。
- 新しいトークンを追加]を選択します。
- トークンの名前と有効期限を入力します。
- トークンの有効期限はその日の午前0時(UTC)です。
- 有効期限を入力しない場合、有効期限は自動的に現在の日付より365日後に設定されます。
- デフォルトでは、この日付は現在の日付より最大 365 日遅くなります。
- 必要なスコープを選択します。
- 個人アクセストークンの作成」を選択します。
個人アクセストークンを安全な場所に保存します。ページを閉じると、アクセストークンにアクセスできなくなります。
個人アクセストークン名とスコープを事前に入力してください。
個人アクセストークンのページに直接リンクし、フォームに名前とスコープのリストをプリフィルすることができます。これを行うには、name パラメータとカンマで区切られたスコープのリストを URL に追加します。例えば
https://gitlab.example.com/-/profile/personal_access_tokens?name=Example+Access+token&scopes=api,read_user,read_registry
個人アクセストークンの取り消し
アクセストークンはいつでも失効させることができます。
- 左のサイドバーで、自分のアバターを選択してください。
- プロフィールの編集を選択します。
- 左サイドバーで、アクセストークンを選択します。
- アクティブな個人アクセストークン] 領域で、キーの横にある [失効] を選択します。
トークンが最後に使用された時刻の表示
トークンの使用情報は10分ごとに更新されます。GitLabはトークンが使用されると、トークンが使用されたとみなします：
トークンが最後に使われた時刻を見るには
- 左のサイドバーで、自分のアバターを選択してください。
- プロフィールの編集を選択します。
- 左サイドバーで、アクセストークンを選択します。
- アクティブな個人アクセストークン］エリアのキーの横にある［最終使用日］を表示します。
個人アクセストークンのスコープ
GitLab 16.0で導入されたコンテナやパッケージのレジストリにアクセスできなくなった個人アクセストークン。
パーソナルアクセストークンは、割り当てられたスコープに基づいてアクションを実行することができます。
| スコープ | アクセス |
|---|---|
api | すべてのグループとプロジェクト、コンテナレジストリ、パッケージレジストリを含む API への完全な読み取り/書き込みアクセスを許可します。 |
read_user |
/user API エンドポイントを介した、認証済みユーザーのプロファイル（ユーザー名、公開電子メール、フルネーム）への読み取り専用アクセスを付与します。また、/users以下の読み取り専用 API エンドポイントへのアクセスも許可します。 |
read_api | すべてのグループとプロジェクト、コンテナレジストリ、パッケージレジストリを含む API への読み取りアクセスを許可します。(GitLab 12.10 で導入)。 |
read_repository | Git-over-HTTP あるいは Repository Files API を使って非公開プロジェクトのリポジトリへの読み込み専用アクセスを許可します。 |
write_repository | Git-over-HTTP を使用する非公開プロジェクトのリポジトリへの読み書きアクセスを許可します (API は使用しません)。 |
read_registry | プロジェクトが非公開で作成者の認証が必要な場合に、コンテナレジストリ画像への読み込み専用 (pull) アクセスを許可します。コンテナレジストリが有効な場合にのみ有効です。 |
write_registry | プロジェクトが非公開で作成者の認証が必要な場合に、コンテナレジストリのイメージへの読み書き（プッシュ）アクセスを許可します。コンテナレジストリが有効な場合のみ利用可能です。(GitLab 12.10 で導入)。 |
sudo | 管理者として認証された場合に、システム内のどのユーザーとしても API アクションを実行する権限を付与します。 |
admin_mode | 管理者モードが有効な場合、管理者としてAPIアクションを実行する権限を付与します。(GitLab 15.8で導入)。 |
create_runner | Runnerの作成権限を付与します。 |
個人アクセストークンの有効期限が切れた場合
個人アクセストークンの有効期限は、お客様が定義された日付の午前0時（UTC）です。
- GitLabは毎日UTC午前01:00にチェックを行い、7日以内に有効期限が切れるパーソナルアクセストークンを特定します。これらのトークンのオーナーにはメールで通知されます。
- GitLabは毎日02:00 AM UTCにチェックを実行し、現在の日付で期限が切れる個人アクセストークンを特定します。これらのトークンのオーナーにはメールで通知されます。
- GitLab Ultimateでは、管理者はアクセストークンの有効期限を制限することができます。設定されていない場合、個人アクセストークンの最大有効期限は365日です。
- GitLab FreeとPremiumでは、個人アクセストークンの最大有効期間は365日です。
プログラムによるパーソナルアクセストークンの作成
テストや自動化の一環として、所定のパーソナルアクセストークンを作成することができます。
前提条件
- GitLabインスタンスのRailsコンソールセッションを実行するのに十分なアクセス権が必要です。
個人アクセストークンをプログラムで作成するには
-
Railsコンソールを開きます：
sudo gitlab-rails console -
以下のコマンドを実行して、ユーザ名、トークン、スコープを参照します。
トークンは20文字でなければなりません。スコープは有効で、ソースコードから見えるものでなければなりません。
例えば、ユーザー名
automation-botのユーザーに属するトークンを作成し、有効期限を 1 年とします：user = User.find_by_username('automation-bot') token = user.personal_access_tokens.create(scopes: ['read_user', 'read_repository'], name: 'Automation token', expires_at: 365.days.from_now) token.set_token('token-string-here123') token.save!
このコードは、Rails Runnerを使うことで1行のシェルコマンドに短縮できます：
sudo gitlab-rails runner "token = User.find_by_username('automation-bot').personal_access_tokens.create(scopes: ['read_user', 'read_repository'], name: 'Automation token', expires_at: 365.days.from_now); token.set_token('token-string-here123'); token.save!"
個人アクセストークンをプログラムで取り消す
テストや自動化の一環として、個人アクセストークンをプログラムで失効させることができます。
前提条件
- GitLab インスタンスのRails コンソールセッションを実行するには、十分なアクセス権限が必要です。
トークンをプログラムで失効させるには
-
Railsコンソールを開きます：
sudo gitlab-rails console -
token-string-here123のトークンを取り消すには、以下のコマンドを実行します：token = PersonalAccessToken.find_by_token('token-string-here123') token.revoke!
このコードは、Rails Runnerを使用して1行のシェルコマンドに短縮できます：
sudo gitlab-rails runner "PersonalAccessToken.find_by_token('token-string-here123').revoke!"
個人アクセストークンを使ったリポジトリのクローン
SSH が無効になっているときにリポジトリをクローンするには、次のコマンドを実行して個人アクセストークンを使用してリポジトリをクローンします：
git clone https://<username>:<personal_token>@gitlab.com/gitlab-org/gitlab.git
この方法では、個人アクセストークンが Bash 履歴に保存されます。これを避けるには、次のコマンドを実行します：
git clone https://<username>@gitlab.com/gitlab-org/gitlab.git
https://gitlab.com のパスワードを聞かれたら、個人アクセストークンを入力します。
clone コマンドのusername です：
- 任意の文字列を指定できます。
- 空文字列であってはなりません。
認証に依存するオートメーションパイプラインを設定する場合は、このことを覚えておいてください。
トラブルシューティング
個人アクセストークンの取り消し
個人アクセストークンが何らかの方法で誤って失効した場合、管理者はそのトークンを取り消すことができます。デフォルトでは、デイリージョブはシステム時間の午前1:00に失効したトークンを削除します。
- Railsコンソールを開きます。
-
トークンの取り消しを行います：
token = PersonalAccessToken.find_by_token('<token_string>') token.update!(revoked:false)例えば、
token-string-here123のトークンを取り消すには、次のようにします：token = PersonalAccessToken.find_by_token('token-string-here123') token.update!(revoked:false)
個人アクセストークンに代わるもの
Git over HTTPS の場合は、アクセストークンの代わりにOAuth 認証ヘルパーを使うこともできます。