Skip to content

authentication.md

Latest commit

 

History

History
145 lines (110 loc) · 7.44 KB

authentication.md

File metadata and controls

145 lines (110 loc) · 7.44 KB
Raw
title Authenticate with GitLab
stage AI Coding
group Code Review
info To determine the technical writer assigned to the Stage/Group associated with this page, see <https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments>

{{< details >}}

  • Tier: Free, Premium, Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

{{< /details >}}

The GitLab CLI supports several authentication methods: OAuth, personal access tokens, and CI job tokens. To get started, run glab auth login and follow the interactive setup.

When running glab auth login interactively inside a Git repository, glab automatically detects GitLab instances from your Git remotes and presents them as options. This saves you from having to manually type the hostname.

OAuth (GitLab.com)

To authenticate your installation of glab with an OAuth application connected to GitLab.com:

  1. Start interactive setup with glab auth login.
  2. For the GitLab instance you want to sign in to, select GitLab.com.
  3. For the login method, select Web to authenticate through your local browser, or Device for headless environments (such as SSH sessions or containers) where no local browser is available. The device flow displays a one-time code and a verification URL that you open on any other device with a browser.
  4. Authorize the application when prompted.
  5. Complete the authentication process in your terminal, selecting the appropriate options for your needs.

OAuth (GitLab Self-Managed, GitLab Dedicated)

Prerequisites:

  • You've created an OAuth application at the user, group, or instance level, and you have its application ID. For instructions, see how to configure GitLab as an OAuth 2.0 authentication identity provider in the GitLab documentation.
  • Your OAuth application is configured with these parameters:
    • Redirect URI is http://localhost:7171/auth/redirect. Not required if you only intend to use --device.
    • Confidential is not selected. If it's selected, glab auth login fails with an invalid_client error. For more information, see the troubleshooting section.
    • Scopes are openid, profile, read_user, write_repository, and api.
  • To use the OAuth 2.0 device authorization flow (glab auth login --device), the application must also have device_code in its allowed grant types, and the GitLab instance must be running GitLab 17.9 or later. For more information, see the device authorization grant flow documentation.

To authenticate your installation of glab with an OAuth application connected to your GitLab Self-Managed or GitLab Dedicated instance:

  1. Store the application ID with glab config set client_id <CLIENT_ID> --host <HOSTNAME>. For <CLIENT_ID>, provide your application ID.
  2. Start interactive setup with glab auth login --hostname <HOSTNAME>.
  3. For the login method, select Web to authenticate through your local browser, or Device for headless environments where no local browser is available.
  4. Follow the prompts to authorize the application:
    • For Web, complete authorization in the browser window that opens.
    • For Device, copy the displayed one-time code, open the verification URL on any device with a browser, and approve the request.
  5. Complete the authentication process in your terminal, selecting the appropriate options for your needs.

Personal access token

To authenticate your installation of glab with a personal access token:

  1. Get a GitLab personal access token with at least the api and write_repository scopes. Use the method appropriate for your instance:
    • For GitLab.com, create one at the personal access tokens page.
    • For GitLab Self-Managed and GitLab Dedicated, visit https://gitlab.example.com/-/user_settings/personal_access_tokens?scopes=api,write_repository, modifying gitlab.example.com to match the domain name of your instance.
  2. Start interactive setup: glab auth login
  3. Authenticate with the method appropriate for your GitLab instance:
    • For GitLab SaaS, authenticate against gitlab.com by reading the token from a file: glab auth login --stdin < myaccesstoken.txt
    • For GitLab Self-Managed and GitLab Dedicated, authenticate by reading from a file: glab auth login --hostname gitlab.example.com --stdin < myaccesstoken.txt. This will allow you to perform authenticated glab commands against your instance when you are in a Git repository with a remote matching your instance's host. Alternatively, set GITLAB_HOST to direct your command to your instance.
    • Authenticate with token and hostname: glab auth login --hostname gitlab.example.org --token xxxxx Not recommended for shared environments.
    • Credentials are stored in the global configuration file.

CI job token

To authenticate your installation of glab with a CI job token, the glab command must be run in a GitLab CI job. The token is automatically provided by the GitLab Runner via the CI_JOB_TOKEN environment variable.

Endpoints allowing the use of the CI job token are listed in the GitLab documentation.

Auto-login

To enable CI auto-login, set GLAB_ENABLE_CI_AUTOLOGIN=true. When enabled, glab automatically detects if it's running in a GitLab CI job and uses the predefined CI/CD variables to sign in.

GLAB_ENABLE_CI_AUTOLOGIN=true glab release list -R $CI_PROJECT_PATH

The following predefined CI/CD variables are used automatically:

Predefined CI/CD variable Equivalent glab auth login flag
CI_SERVER_FQDN --hostname
CI_JOB_TOKEN --job-token
CI_SERVER_PROTOCOL --api-protocol
CI_SERVER_SHELL_SSH_HOST --ssh-hostname

Manual login

Use manual login when the command does not support CI job tokens, or you need a personal access token:

glab auth login --job-token $CI_JOB_TOKEN --hostname $CI_SERVER_FQDN --api-protocol $CI_SERVER_PROTOCOL
GITLAB_HOST=$CI_SERVER_FQDN glab release list -R $CI_PROJECT_PATH

Troubleshooting

When authenticating with glab, you might encounter the following issues.

Error: invalid_client during OAuth login

When authenticating with an OAuth application, glab auth login might fail with an error:

Oauth2: "invalid_client" "Client authentication failed due to unknown client, no client authentication included, or unsupported authentication method.".

This happens when the OAuth application has the Confidential option enabled. glab is a public client and cannot keep a client secret, so it authenticates without one. Confidential applications require a client secret, which causes GitLab to reject the request.

To resolve this issue, edit your OAuth application and clear the Confidential checkbox.

After saving the change, run glab auth login again. For the full list of required application settings, see OAuth (GitLab Self-Managed, GitLab Dedicated).