Authentik을 이용하여 Matttermost에 GitLab OAuth 설정하기

작성일: 2025년 7월 8일

2025   ·   self-hosting   ·   mmlab-webmaster

현재 우리 연구실에서는 Mattermost를 협업 툴로 사용하고 있다.
최근의 연구실의 홈페이지, 웹메일, 위키, Mattermost 계정을 통합하기 위해 Authentik을 도입했다.
홈페이지, 웹메일, 위키는 모두 OIDC provider를 이용해 설정을 완료했으나, Mattermost에서 OIDC를 사용하려면 유료 라이센스를 구매해야 하는 문제점이 있었다.
Mattermost의 무료 team edition에서 지원하는 SSO provider는 GitLab OAuth뿐이다. (참고: https://docs.mattermost.com/onboard/sso-gitlab.html)

그래서, Authentik의 OIDC provider를 마치 GitLab OAuth처럼 보이도록 설정하여 Mattermost와 연동하는 방법을 정리했다.
온라인에서 몇몇 자료를 찾을 수 있었지만, Mattermost와 Authentik 버전이 다 조금씩 달라서 설정에 어려움을 겪었다.

본 글에 나온 내용은 Mattermost 10.9.1 버전과 Authentik 2025.6.3 버전을 기준으로 작성되었다.
또한, 본 튜토리얼대로 하려면 Authentik 앞에 reverse proxy를 반드시 사용해야 한다. (path rewrite 때문)
참고로 우리 연구실의 Authentik은 Caddy v2 reverse proxy를 사용하고 있고, 본 튜토리얼도 이를 기준으로 작성되었다.
Traefik이나 Nginx 등 다른 reverse proxy를 사용한다면, 그에 맞춰 설정 파일을 변형하여 작성하길 바란다.

참고: 본 튜토리얼은 Authentik OAuth2 provider의 GitHub-compatible endpoint를 활용한다.

1. Authentik 설정

Application 생성

관리자 인터페이스에서, 좌측 사이드바의 “Applications” 메뉴를 클릭한 후, “Create” 버튼을 클릭한 후, 다음과 같이 입력한다:

  • 이름: Mattermost
  • Slug: mattermost

아래쪽의 “Create” 버튼을 클릭하여 Application 생성을 완료한다.

image-20250709171158672

Provider 생성

다음으로, 좌측 사이드바의 “Providers” 메뉴를 클릭 -> “Create”를 클릭한다.

“OAuth2/OpenID Provider”를 선택하고 아래쪽의 “Finish” 버튼을 누른다.

다음 탭에서 다음 정보들을 입력하고 저장한다:

  • 이름: Provider for Mattermost (혹은 임의의 이름)
  • 인가 플로우: 임의로 설정. 저는 default-provider-authorization-explicit-consent (Authorize Application)로 설정했습니다
  • 리디렉션 URI/Origin (정규표현식)
    • https://mattermost.my.domain/signup/gitlab/complete
    • https://mattermost.my.domain/login/gitlab/complete
    • mattermost.my.domain을 자신의 mattermost 서버 도메인으로 바꿔 입력한다.
  • 고급 프로토콜 설정 > 스코프 (scopes) : 전부 다 빼도 된다. 왜냐하면 우리는 Authentik의 GitHub-compatible endpoint를 사용할 것이고 이에 따른 특별 scope들만 요청되기 때문이다.
  • 클라이언트 ID와 클라이언트 비밀은 다음 단계에서 사용될 것이기 때문에 잘 기록해 둔다.

Screenshot From 2025-07-09 17-22-42-obfuscated

Application에 Provider 추가

다시 좌측의 Applications 메뉴 -> Mattermost 선택 -> 수정 -> Provider에 “Provider for Mattermost”를 선택한다.

2. Mattermost GitLab Auth 설정

Mattermost의 관리자 UI -> Authentication -> GitLab 메뉴로 들어간다.

  • Enable authentication with GitLab: True
  • Application ID: 1단계에서 기록한 클라이언트 ID
  • Application Secret Key: 1단계에서 기록한 클라이언트 비밀
  • GitLab Site URL: Authentik URL (예: https://sso.my.domain)

저장한다.

3. Reverse Proxy 설정

Authentik의 reverse proxy 설정파일을 수정하여, path rewrite 룰을 추가한다.

아래는 Caddy reverse proxy의 경우에 사용되는 Caddyfile의 예시이다:

sso.my.domain {
    uri replace /api/v4/user /user  1 # User API Endpoint
    uri replace /oauth/authorize /login/oauth/authorize 1 # Auth Endpoint
    uri replace /oauth/token /login/oauth/access_token 1 # Token Endpoint
    uri replace /login/login/oauth /oauth 1
    reverse_proxy localhost:9000
}

4. Mattermost에서 GitLab OAuth로 로그인하기

기존 Mattermost 유저 여부에 따라서 로그인 방법이 달라진다.

기존 Mattermost 유저가 아닌 경우

Mattermost 로그인 페이지에서 “Log in with GitLab” 버튼을 클릭하여 Authentik 로그인 페이지로 이동한다.
Authentik에서 로그인한 후 (혹은 회원가입 후), Mattermost로 리디렉션된다. 이때 자동으로 Mattermost 계정이 생성된다.

기존 Mattermost 유저인 경우

대부분의 SSO를 지원하는 애플리케이션들의 경우 관리자가 일괄적으로 모든 유저들을 SSO로 전환할 수 있는 기능이 있지만… ~킹받게도~ Mattermost에는 그런 기능이 없다.
각 유저가 직접 프로필 설정에서 GitLab OAuth로 전환해야 한다.
다음은 내가 전환을 부탁하기 위해 랩 구성원들에게 보낸 메시지 내용이다. 이 내용을 참고해서 각 유저가 계정을 전환하면 된다:

  1. Mattermost(PC)의 우측 최상단의 자신의 프로필 이미지 클릭 -> Profile
  2. 좌측 사이드바의 Security/보안 클릭
  3. 우측 메뉴 맨 하단의 “Sign-in Method/접속 방식” 우측의 “Edit/편집” 클릭
  4. “Switch to Using GitLab SSO” 클릭
  5. 화면에서 시키는대로 현재 Mattermost 계정 비밀번호 입력하고 “Switch Account to Gitlab SSO” 클릭
  6. SSO 사이트로 리다이렉트되면, 자신의 SSO 아이디/비밀번호로 로그인
  7. 계정 전환이 완료되면, 이때부터는 Mattermost에서 “Log In with SSO”를 눌러서 로그인한다. (기존의 아이디, 비밀번호 사용 불가)

Tips

로그인 화면에서 GitLab 버튼 텍스트 변경하기 / 아이콘 숨기기

Mattermost 로그인 페이지에서 GitLab 로그인 버튼의 텍스트를 바꾸고 싶다면, Mattermost의 config.json 파일을 수정한다.
GitLabSettings.ButtonText 항목을 원하는 텍스트로 바꾸면 된다.
버튼 아이콘을 바꾸는 설정은 따로 없어서…. 나는 custom CSS를 이용하여 아이콘을 숨겼다.
Mattermost에는 custom CSS를 적용할 수 있는 기능이 없기 때문에 플러그인을 이용해야 한다. 나는 이 레포지토리에 있는 가이드를 가지고 플러그인을 생성했다.
적용한 CSS는 다음과 같다:

svg[aria-label="Gitlab Icon"] {
    display: none !important;
}

ID/Password 로그인 비활성화하기

모든 유저들이 전환을 완료했다면, Mattermost의 관리자 UI -> Authentication -> Email 메뉴로 들어가서 다음과 같이 설정한다:

  • Enable account creation with email: False
  • Enable sign-in with email: False
  • Enable sign-in with username: False

마치며

뭔가 마무리를 해야 할 것 같은데 뭐라 써야 할지 잘 모르겠다.
앞으로도 연구실 서버 관리 일지를 비롯하여, 이 글과 같이 나만 알기엔 아까운 다양한 팁들을 정리해보려 한다.
감사합니다.

to select to navigate esc to close move to parent