--- stage: Manage group: Authentication and Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Use GitHub as an authentication provider **(FREE SELF)** You can integrate your GitLab instance with GitHub.com and GitHub Enterprise. You can import projects from GitHub, or sign in to GitLab with your GitHub credentials. ## Create an OAuth app in GitHub To enable the GitHub OmniAuth provider, you need an OAuth 2.0 client ID and client secret from GitHub: 1. Sign in to GitHub. 1. [Create an OAuth App](https://docs.github.com/en/developers/apps/building-oauth-apps/creating-an-oauth-app) and provide the following information: - The URL of your GitLab instance, such as `https://gitlab.example.com`. - The authorization callback URL, such as, `https://gitlab.example.com/users/auth`. Include the port number if your GitLab instance uses a non-default port. ### Check for security vulnerabilities For some integrations, the [OAuth 2 covert redirect](https://oauth.net/advisories/2014-1-covert-redirect/) vulnerability can compromise GitLab accounts. To mitigate this vulnerability, append `/users/auth` to the authorization callback URL. However, as far as we know, GitHub does not validate the subdomain part of the `redirect_uri`. Therefore, a subdomain takeover, an XSS, or an open redirect on any subdomain of your website could enable the covert redirect attack. ## Enable GitHub OAuth in GitLab 1. Configure the [common settings](omniauth.md#configure-common-settings) to add `github` as a single sign-on provider. This enables Just-In-Time account provisioning for users who do not have an existing GitLab account. 1. Edit the GitLab configuration file using the following information: | GitHub setting | Value in the GitLab configuration file | Description | |----------------|----------------------------------------|-------------------------| | Client ID | `YOUR_APP_ID` | OAuth 2.0 client ID | | Client secret | `YOUR_APP_SECRET` | OAuth 2.0 client secret | | URL | `https://github.example.com/` | GitHub deployment URL | - **For Omnibus installations** 1. Open the `/etc/gitlab/gitlab.rb` file. For GitHub.com, update the following section: ```ruby gitlab_rails['omniauth_providers'] = [ { name: "github", # label: "Provider name", # optional label for login button, defaults to "GitHub" app_id: "YOUR_APP_ID", app_secret: "YOUR_APP_SECRET", args: { scope: "user:email" } } ] ``` For GitHub Enterprise, update the following section and replace `https://github.example.com/` with your GitHub URL: ```ruby gitlab_rails['omniauth_providers'] = [ { name: "github", # label: "Provider name", # optional label for login button, defaults to "GitHub" app_id: "YOUR_APP_ID", app_secret: "YOUR_APP_SECRET", url: "https://github.example.com/", args: { scope: "user:email" } } ] ``` 1. Save the file and [reconfigure](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) GitLab. - **For installations from source** 1. Open the `config/gitlab.yml` file. For GitHub.com, update the following section: ```yaml - { name: 'github', # label: 'Provider name', # optional label for login button, defaults to "GitHub" app_id: 'YOUR_APP_ID', app_secret: 'YOUR_APP_SECRET', args: { scope: 'user:email' } } ``` For GitHub Enterprise, update the following section and replace `https://github.example.com/` with your GitHub URL: ```yaml - { name: 'github', # label: 'Provider name', # optional label for login button, defaults to "GitHub" app_id: 'YOUR_APP_ID', app_secret: 'YOUR_APP_SECRET', url: "https://github.example.com/", args: { scope: 'user:email' } } ``` 1. Save the file and [restart](../administration/restart_gitlab.md#installations-from-source) GitLab. 1. Refresh the GitLab sign-in page. A GitHub icon should display below the sign-in form. 1. Select the icon. Sign in to GitHub and authorize the GitLab application. ## Troubleshooting ### Imports from GitHub Enterprise with a self-signed certificate fail When you import projects from GitHub Enterprise using a self-signed certificate, the imports fail. To fix this issue, you must disable SSL verification: 1. Set `verify_ssl` to `false` in the configuration file. - **For Omnibus installations** ```ruby gitlab_rails['omniauth_providers'] = [ { name: "github", # label: "Provider name", # optional label for login button, defaults to "GitHub" app_id: "YOUR_APP_ID", app_secret: "YOUR_APP_SECRET", url: "https://github.example.com/", verify_ssl: false, args: { scope: "user:email" } } ] ``` - **For installations from source** ```yaml - { name: 'github', # label: 'Provider name', # optional label for login button, defaults to "GitHub" app_id: 'YOUR_APP_ID', app_secret: 'YOUR_APP_SECRET', url: "https://github.example.com/", verify_ssl: false, args: { scope: 'user:email' } } ``` 1. Change the global Git `sslVerify` option to `false` on the GitLab server. - **For Omnibus installations in [GitLab 15.3](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/6800) and later**: ```ruby gitaly['gitconfig'] = [ {key: "http.sslVerify", value: "false"}, ] ``` - **For Omnibus installations in GitLab 15.2 and earlier (legacy method)**: ```ruby omnibus_gitconfig['system'] = { "http" => ["sslVerify = false"] } ``` - **For installations from source in [GitLab 15.3](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/6800) and later**, edit the Gitaly configuration (`gitaly.toml`): ```toml [[git.config]] key = "http.sslVerify" value = "false" ``` - **For installations from source in GitLab 15.2 and earlier (legacy method)**: ```shell git config --global http.sslVerify false ``` 1. [Reconfigure GitLab](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) if you installed using Omnibus, or [restart GitLab](../administration/restart_gitlab.md#installations-from-source) if you installed from source. ### Signing in using GitHub Enterprise returns a 500 error This error can occur because of a network connectivity issue between your GitLab instance and GitHub Enterprise. To check for a connectivity issue: 1. Go to the [`production.log`](../administration/logs/index.md#productionlog) on your GitLab server and look for the following error: ``` plaintext Faraday::ConnectionFailed (execution expired) ``` 1. [Start the rails console](../administration/operations/rails_console.md#starting-a-rails-console-session) and run the following commands. Replace `` with the URL of your GitHub Enterprise instance: ```ruby uri = URI.parse("https://") # replace `GitHub-URL` with the real one here http = Net::HTTP.new(uri.host, uri.port) http.use_ssl = true http.verify_mode = 1 response = http.request(Net::HTTP::Get.new(uri.request_uri)) ``` 1. If a similar `execution expired` error is returned, this confirms the error is caused by a connectivity issue. Make sure the GitLab server can reach your GitHub Enterprise instance. ### Signing in using your GitHub account without a pre-existing GitLab account is not allowed When you sign in to GitLab, you get the following error: ```plaintext Signing in using your GitHub account without a pre-existing GitLab account is not allowed. Create a GitLab account first, and then connect it to your GitHub account ``` To fix this issue, you must activate GitHub sign-in in GitLab: 1. On the top bar, in the upper-right corner, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **Account**. 1. In the **Service sign-in** section, select **Connect to GitHub**.