REST API認証

ほとんどのAPIリクエストは認証を必要としますが、認証が提供されていない場合は公開データのみを返します。認証が不要な場合、各エンドポイントのドキュメントにその旨が明記されています。たとえば、/projects/:idエンドポイントは認証を必要としません。

GitLab REST APIでは、いくつかの方法で認証を行うことができます:

プロジェクトアクセストークンは次の製品でサポートされています:

GitLab Self-Managed: Free、Premium、Ultimate。
GitLab.com: Premium、Ultimate。

管理者の場合、管理者または管理者のアプリケーションは、以下のいずれかを使用して、特定のユーザーとして認証できます:

認証情報が無効であるか、欠落している場合、GitLabはステータスコード401のエラーメッセージを返します:

{
  "message": "401 Unauthorized"
}

デプロイトークンは、GitLabパブリックAPIでは使用できません。詳細については、デプロイトークンを参照してください。

OAuth 2.0トークン

OAuth 2.0トークンを使用して、access_tokenパラメータまたはAuthorizationヘッダーのいずれかでトークンを渡すことにより、APIで認証できます。

パラメータでOAuth 2.0トークンを使用する例:

curl --request GET \
  --url "https://gitlab.example.com/api/v4/projects?access_token=OAUTH-TOKEN"

ヘッダーでOAuth 2.0トークンを使用する例:

curl --request GET \
  --header "Authorization: Bearer OAUTH-TOKEN" \
  --url "https://gitlab.example.com/api/v4/projects"

詳細については、OAuth 2.0プロバイダーとしてのGitLabを参照してください。

すべてのOAuthアクセストークンは、作成された後、2時間有効です。refresh_tokenパラメータを使用して、トークンを更新できます。更新トークンを使用して新しいアクセストークンをリクエストする方法については、OAuth 2.0トークンのドキュメントを参照してください。

パーソナル/プロジェクト/グループアクセストークン

アクセストークンを使用して、private_tokenパラメータまたはPRIVATE-TOKENヘッダーのいずれかでトークンを渡すことにより、APIで認証できます。

パラメータでパーソナルアクセストークン、プロジェクトアクセストークン、またはグループアクセストークンを使用する例:

curl --request GET \
  --url "https://gitlab.example.com/api/v4/projects?private_token=<your_access_token>"

ヘッダーでパーソナルアクセストークン、プロジェクトアクセストークン、またはグループアクセストークンを使用する例:

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects"

OAuth準拠のヘッダーでパーソナルアクセストークン、プロジェクトアクセストークン、またはグループアクセストークンを使用することもできます:

curl --request GET \
  --header "Authorization: Bearer <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects"

ジョブトークン

ジョブトークンを使用して、job_tokenパラメータまたはJOB-TOKENヘッダーでトークンを渡すことにより、特定のAPIエンドポイントで認証できます。GitLab CI/CDジョブでトークンを渡すには、CI_JOB_TOKEN変数を使用します。

パラメータでジョブトークンを使用する例:

curl --request GET \
  --location --output artifacts.zip \
  --url "https://gitlab.example.com/api/v4/projects/1/jobs/42/artifacts?job_token=$CI_JOB_TOKEN"

ヘッダーでジョブトークンを使用する例:

curl --request GET \
  --header "JOB-TOKEN:$CI_JOB_TOKEN" \
  --url "https://gitlab.example.com/api/v4/projects/1/releases"

メインのGitLabアプリケーションにサインインすると、_gitlab_session Cookieが設定されます。このCookieが存在する場合、APIはそれを使用して認証します。APIを使用して新しいセッションCookieを生成することはサポートされていません。

この認証方法の主なユーザーは、GitLab自体のWebフロントエンドです。Webフロントエンドは認証済みユーザーとしてAPIを使用して、アクセストークンを明示的に渡すことなく、プロジェクトのリストを取得できます。

代理トークン

代理トークンは、パーソナルアクセストークンの一種です。代理トークンは管理者のみが作成でき、特定のユーザーとしてAPIで認証するために使用されます。

以下の代替手段として、代理トークンを使用します:

ユーザーのパスワード、またはパーソナルアクセストークンの1つ。
Sudo機能。ユーザーや管理者のパスワードまたはトークンが不明な場合もあれば、時間の経過とともに変更される場合もあります。

詳細については、ユーザートークンAPIのドキュメントを参照してください。

代理トークンは、通常のパーソナルアクセストークンとまったく同じように使用され、private_tokenパラメータまたはPRIVATE-TOKENヘッダーのいずれかで渡すことができます。

代理を無効にする

デフォルトでは、代理は有効になっています。代理を無効にするには、次の手順に従います:

/etc/gitlab/gitlab.rbファイルを編集します:
```
gitlab_rails['impersonation_enabled'] = false
```
ファイルを保存してから、変更を有効にするためにGitLabを再設定します。

config/gitlab.ymlファイルを編集します:
```
gitlab:
  impersonation_enabled: false
```
ファイルを保存してから、変更を有効にするためにGitLabを再起動します。

代理を再度有効にするには、この設定を削除して、GitLabを再設定するか（Linuxパッケージのインストール）、GitLabを再起動します（自己コンパイルのインストール）。

Sudo

すべてのAPIリクエストは、sudoスコープを持つOAuthトークンまたはパーソナルアクセストークンでユーザーが管理者として認証されていることを条件として、その管理者が別のユーザーであるかのようにAPIリクエストを実行することをサポートしています。APIリクエストは、代理ユーザーの権限で実行されます。

管理者として、操作が実行されるユーザーのIDまたはユーザー名（大文字と小文字を区別しない）を使用して、クエリ文字列またはヘッダーのいずれかでsudoパラメータを渡します。ヘッダーとして渡す場合、ヘッダー名はSudoである必要があります。

管理者権限のないアクセストークンが指定された場合、GitLabはステータスコード403のエラーメッセージを返します:

{
  "message": "403 Forbidden - Must be admin to use sudo"
}

sudoスコープのないアクセストークンが指定された場合、ステータスコード403のエラーメッセージが返されます:

{
  "error": "insufficient_scope",
  "error_description": "The request requires higher privileges than provided by the access token.",
  "scope": "sudo"
}

sudoユーザーIDまたはユーザー名が見つからない場合は、ステータスコード404のエラーメッセージが返されます:

{
  "message": "404 User with ID or username '123' Not Found"
}

有効なAPIリクエストと、ユーザー名を指定してsudoリクエストでcURLを使用するリクエストの例:

GET /projects?private_token=<your_access_token>&sudo=username

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Sudo: username" \
  --url "https://gitlab.example.com/api/v4/projects"

有効なAPIリクエストと、IDを指定してsudoリクエストでcURLを使用するリクエストの例:

GET /projects?private_token=<your_access_token>&sudo=23

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Sudo: 23" \
  --url "https://gitlab.example.com/api/v4/projects"