Project: Backstage (App Definition and Development / Application Definition & Image Build)
File: provider.md

id: provider title: GitLab Authentication Provider sidebar_label: GitLab description: Adding GitLab OAuth as an authentication provider in Backstage The Backstage `core-plugin-api` package comes with a GitLab authentication provider that can authenticate users using GitLab OAuth. To support GitLab authentication, you must create an Application from the . The `Redirect URI` should point to your Backstage backend auth handler. Set Application Name to `backstage-dev` or something along those lines. The Authorization Callback URL should match the redirect URI set in Backstage. Set this to `http://localhost:7007/api/auth/gitlab/handler/frame` for local development. Set this to `http://{APPFQDN}:{APPBACKEND_PORT}/api/auth/gitlab/handler/frame` for non-local deployments. Select the following scopes from the list: [x] `read_user` Grants read-only access to the authenticated user's profile through the /user API endpoint, which includes username, public email, and full name. Also grants access to read-only API endpoints under /users. [x] `read_repository` Grants read-only access to repositories on private projects using Git-over-HTTP (not using the API). [x] `write_repository` Grants read-write access to repositories on private projects using Git-over-HTTP (not using the API). [x] `openid` Grants permission to authenticate with GitLab using OpenID Connect. Also gives read-only access to the user's profile and group memberships. [x] `profile` Grants read-only access to the user's profile data using OpenID Connect. [x] `email` Grants read-only access to the user's primary email address using OpenID Connect. The provider configuration can then be added to your `app-config.yaml` under the root `auth` configuration: ```yaml auth: environment: development providers: gitlab: development: clientId: ${AUTHGITLABCLIENT_ID} clientSecret: ${AUTHGITLABCLIENT_SECRET} signIn: resolvers: resolver: emailMatchingUserEntityProfileEmail resolver: emailLocalPartMatchingUserEntityName resolver: usernameMatchingUserEntityName ``` The GitLab provider is a structure with three configuration keys: `clientId`: The Application ID that you generated on GitLab, e.g. `4928c033ab3d592845c044a653bc20583baf84f2e67b954c6fdb32a532ab76c9` `clientSecret`: The Application secret `audience` (optional): The base URL for the self-hosted GitLab instance, e.g. `https://gitlab.company.com` `callbackUrl` (optional): The URL matching the Redirect URI registered when creating your GitLab OAuth App, e.g. `https://$backstage.acme.corp/api/auth/gitlab/handler/frame` Note: Due to a peculiarity with GitLab OAuth, ensure there is no trailing `/` after 'frame' in the URL. This provider includes several resolvers out of the box that you can use: `emailMatchingUserEntityProfileEmail`: Matches the email address from the auth provider with the User entity that has a matching `spec.profile.email`. If no match is found it will throw a `NotFoundError`. `emailLocalPartMatchingUserEntityName`: Matches the of the email address from the auth provider with the User entity that has a matching `name`. If no match is found it will throw a `NotFoundError`. `usernameMatchingUserEntityName`: Matches the username from the auth provider with the User entity that has a matching `name`. If no match is found it will throw a `NotFoundError`. :::note Note The resolvers will be tried in order, but will only be skipped if they throw a `NotFoundError`. ::: If these resolvers do not fit your needs you can build a custom resolver, this is covered in the section of the Sign-in Identities and Resolvers documentation. To add the provider to the frontend, add the `gitlabAuthApi` reference and `SignInPage` component as shown in .