GitLab authentication strategy for Passport

License: MIT

Language: JavaScript


The original Passport-GitLab module has not been maintained for a long time. Due to the unclear license situation and issues in the code, this library was rewritten based on Passport-Facebook and published under the MIT license.

npm version Build Status Coverage Status Code Climate Dependency Status

Passport strategy for authenticating with GitLab using the OAuth2 authentication provider service.

This module lets you authenticate using GitLab in your Node.js applications. By plugging into Passport, GitLab authentication can be easily and unobtrusively integrated into any application or framework that supports Connect-style middleware, including Express.


$ npm install passport-gitlab2


Passport-GitLab requires GitLab 9.0.0 or higher to work. Before using the OAuth2 authentication provider service, you have register a new application in your user profile or in the administrator portal. GitLab will then issue an application ID and a secret, which need to be provided to the strategy. You will also need to configure a redirect URI which matches the route in your application.

Configure Strategy

The GitLab authentication strategy authenticates users using a GitLab account and OAuth 2.0 tokens. The app ID and secret obtained when creating an application are supplied as options when creating the strategy. The strategy also requires a verify callback, which receives the access token and optional refresh token, as well as profile which contains the authenticated user's GitLab profile. The verify callback must call cb providing a user to complete authentication.

passport.use(new GitLabStrategy({
    clientID: GITLAB_APP_ID,
    clientSecret: GITLAB_APP_SECRET,
    callbackURL: "http://localhost:3000/auth/gitlab/callback"
  function(accessToken, refreshToken, profile, cb) {
    User.findOrCreate({gitlabId: profile.id}, function (err, user) {
      return cb(err, user);

Authenticate Requests

Use passport.authenticate(), specifying the 'gitlab' strategy, to authenticate requests.

For example, as route middleware in an Express application:

app.get('/auth/gitlab', passport.authenticate('gitlab'));

  passport.authenticate('gitlab', {
    failureRedirect: '/login'
  function(req, res) {
    // Successful authentication, redirect home.


How do I use my own GitLab instance rather than gitlab.com?

Passport-GitLab automatically uses GitLab.com as authentication endpoint when not configured otherwise. You can use the baseURL parameter to point to any other GitLab instance as following:

new GitLabStrategy({
  clientID: GITLAB_APP_ID,
  clientSecret: GITLAB_APP_SECRET,
  callbackURL: "http://localhost:3000/auth/gitlab/callback",
  baseURL: "https://gitlab.example.com/"
}), ...)

All URLs (e.g. token-url, authorization-url, profile-url) are automatically adapted to utilize the configured instance. You can of course overwrite all URLs manually if needed.

How do I change permissions / scope when obtaining a user profile?

GitLab supports multiple scopes at the moment like read_user and api. By default, the read_user scope is used. Changing the OAuth2 scope to api works as following:

  passport.authenticate('gitlab', {
    scope: ['api']

More information can be found in the official GitLab documentation.


We appreciate contributions in several forms, e.g. documentation, testing, coding, issues, etc. Please follow the best practice contribution guide as mentioned below when submitting code changes:

Code style

This module uses the Google JavaScript Code-Style and enforces it using JSCS as additional linter beneath JSHint. These measures ensuring a high level of code quality and easy maintainability of it. You can test if your changes comply with the code style by executing:

$ make lint


The test suite is located in the test/ directory. All new features are expected to have corresponding test cases. Ensure that the complete test suite passes by executing:

$ make test


The test suite covers 100% of the code base. All new feature development is expected to maintain that level. Coverage reports can be viewed by executing:

$ make coverage-view


The MIT License

Copyright (c) 2016-2019 Fabio Huser fabio@fh1.ch

Copyright (c) 2011-2016 Jared Hanson <http://jaredhanson.net/>

Project Statistics

Sourcerank 7
Repository Size 245 KB
Stars 28
Forks 6
Watchers 2
Open issues 1
Dependencies 153
Contributors 22
Tags 19
Last updated
Last pushed

Top Contributors See all

Jared Hanson Fabio Huser Stepan Stolyarov aymanosman Peter deHaan Marcin Jekot niftylettuce Jason Jarrett Rob DiMarco Matias Woloski Fernando Lores Fernando Piancastelli Andrew Chaa Pascal Bach Ryan Fonger lester Matt Blair Sam Gruse Dan Silver

Packages Referencing this Repo

GitLab authentication strategy for Passport.
Latest release 5.0.0 - Updated - 28 stars

Recent Tags See all

v5.0.0 February 10, 2019
v4.0.0 June 10, 2018
v3.0.0 April 02, 2017
v2.2.0 April 02, 2017
v0.2.0 May 01, 2016
v2.1.0 February 02, 2016
v2.0.0 March 03, 2015
v1.0.3 March 09, 2014
v1.0.2 November 08, 2013
v1.0.1 September 11, 2013
v1.0.0 August 15, 2013
v0.1.6 August 15, 2013
v0.1.6 August 15, 2013
v0.1.5 February 10, 2013
v0.1.4 June 26, 2012

Something wrong with this page? Make a suggestion

Last synced: 2019-02-10 08:56:41 UTC

Login to resync this repository