Authentik으로 홈서버 SSO 구현하기 (3) – OAuth/OpenID

개요

LDAP는 있으면 좋지만, 이것만으로는 번거로운 로그인 과정을 전부 해결할 수는 없습니다.

이번 글에서는 OAuth / OpenID Provider를 설정하는 방법을 적어 보겠습니다.

LDAP가 조직 내부 네트워크 인증에 쓰인다면, OAuth는 서드파티 애플리케이션이 사용자 대신 자원에 접근할 수 있도록 리소스 접근 권한을 부여하고, OpenID는 ID제공자와 이용자를 분리하여 분산형 인증을 통해 이를 처리해주는 형식입니다. 이 과정은 JWT(JSON Web Token)이라고 하는 ID토큰을 base64 형식으로 인코딩, 서명 및 암호화하는 것을 통해 이루어집니다.

OAuth / OpenID는 사용하려는 앱의 Redirect URI에 맞추어 Provider를 생성해야 하므로, 몇 가지 예시로 작성해 보겠습니다.

연결 가능한 앱 목록과 방법은 공식 문서에서 참조할 수 있습니다.

 

Immich와 연동하기

리버스 프록시 연결

운용중인 Immich 서비스가 있다는 가정 하에 도메인을 연결해 줍니다. 예시 글에서는 immichsample.fentanest.com을 사용하겠습니다.

 

애플리케이션, Provider 생성하기

애플리케이션 – 공급자 – 생성 – OAuth2/OpenID Provider를 선택합니다.

이름을 정해준 뒤, 인증 플로우는 default-authentication-flow, 인가 플로우는 default-provider-authorization-explict-consent를 선택합니다(implict 무관).

클라이언트 유형은 기밀, 클라이언트ID와 비밀 Immich에 입력할 때 필요합니다.

리디렉션 URI에는 아래의 3개 주소를 입력합니다.

서명 키는 인증서를 선택해 주면 됩니다. 이후 ‘마침’을 클릭해 생성 과정을 완료합니다.

이후 애플리케이션 – 애플리케이션 – 생성 클릭 후 아래와 같이 입력 및 생성을 완료합니다.

• 이름 : immich
• 슬러그 : immch
• 공급자 : immich(방금 위에서 생성한 것)

이제 다시 공급자로 돌아가서 immich를 확인해보면 아래와 같이 구성 발급자를 비롯해 필요한 URL이 모두 구성된 것을 확인할 수 있습니다.

 

Immich 설정하기

Immich에서 관리자 메뉴 – Settings – Authentication Settings – OAuth – Enable을 순차적으로 클릭하면 OAuth 구성 정보를 입력하는 칸이 나타납니다.

아래 표의 내용대로 채워 넣습니다.

최하단에 AUTO REGISTER는 OAuth/OpenID로 로그인 시도하는 계정이 없을 경우 자동으로 계정을 생성해주는 옵션입니다.

비활성화시킬 경우 로컬에 매칭되는 계정이 없다면, 로그인이 차단됩니다.

모든 작업을 완료 후, immichsample.fentanest.com으로 접속해서 로그인을 시도하면 OAuth로그인 버튼을 확인할 수 있고, Authentik을 경유해 성공적으로 로그인할 수 있게 됩니다.

 

추가 속성 매핑 (immich_quota)

Immich는 immich_quota 값을 통해 OAuth/OpenID로 생성되는 계정에 용량 제한을 설정할 수 있습니다.

관심 없으실 경우 넘겨도 무방합니다.

이 기능은, 해당 계정이 처음 생성될 때만 적용되고, 생성된 이후에는 이 값이 변하더라도 동기화되지 않습니다.

Customization – 속성 매핑 – 생성 – Scope Mapping을 순차적으로 클릭합니다.

이후 표현식에 아래와 같이 입력합니다.

return {
    "immich_quota": user.group_attributes().get("immich_quota", None),
}

범위 이름은 immich_quota, 이름은 자유롭게 지정하실 수 있지만, 가시성을 위해 연관성이 있도록 짓는게 좋습니다.

‘기술’ 항목은 로그인하는 유저에게 권한 관련 알림을 출력할 때 같이 출력되는 항목입니다. 예시 글에서는 Default Storage라고 간단하게 기입하겠습니다.

이후 immich 공급자를 확인해보면 immich storage limit이 추가되어 있는 것을 확인할 수 있습니다. 선택해서 추가하여 준 후, 특정 유저의 특성(Attributes)에 immich_quota를 정의합니다.

해당 속성은 GB단위입니다.

이후 해당 유저로 로그인을 새롭게 시도하면 아래처럼 새로운 권한을 요구하며, 위에서 적었던 “Default Storage” 문구가 함께 출력되는 것을 확인할 수 있으며,

좌측 하단의 Storage에 설정한 용량만큼 quota설정이 된 것을 확인할 수 있습니다.

이 설정은 immich 아이디 생성 과정에서만 적용되는 특성이기 때문에, 개별 유저마다 사전에 정의하기보다는 특정 그룹의 특성으로 정의해서 사용하는 방식이 유용할 것으로 보입니다.

 

Nextcloud와 연동하기

OpenID Connect user backend를 사용하는 경우

리버스 프록시 연결

https로 접속하지 않으면 Nextcloud에서 이 기능을 통한 로그인을 거부합니다.

예시글에서는 nextsample.fentanest.com 주소를 사용하겠습니다.

또한, nextcloud의 config.php에서 리버스 프록시 주소를 신뢰하는 도메인으로 추가해야 합니다.

 

애플리케이션, Provider 생성하기

OAuth/OpenID Provider를 생성합니다.

Nextcloud에 사용할 공급자의 이름을 지정한 뒤, 인증 플로우는 default-authentication-flow, 인가 플로우는 default-provider-authorization-explict-consent를 선택합니다.

클라이언트 유형은 기밀로 설정되어야 합니다.

Nextcloud의 Known Issue로 클라이언트 시크릿이 64자리까지만 지원됩니다. 그래서 적당한 자리에서 잘라주셔야 합니다.

리디렉션 URI는 아래 3가지를 테스트하여 오류가 발생하지 않는 것을 사용합니다.

일반적으로, 첫 번째 주소로 바로 사용할 수 있으나 하단에서 기술할 내용을 적용했다면 3번 주소를 사용하셔야 합니다.

• https://{Nextcloud주소}/apps/user_oidc/code
• https://{Nextcloud주소}/index.php/apps/user_oidc/code
• https://{Nextcloud주소}:443/apps/user_oidc/code

이후, 스크롤을 내려 Subject 모드를 UUID기반으로 선택한 뒤, id_token에 요청 포함 항목을 활성화 해 줍니다.

Provider를 생성한 뒤 애플리케이션도 같이 하나 생성해 줍니다.

 

Nextcloud 설정하기

config.php에 다음 두 줄을 추가해야 합니다.

'allow_local_remote_servers' => true,
'overwriteprotocol' => 'https',

앱 – 소셜 및 통신 목록 중 OpenID Connect user backend를 설치해 줍니다.

이후 관리자 설정 – OpenID Connect 메뉴가 활성화됩니다.

Registered Providers의 + 버튼을 누르면 아래와 같은 창이 나타납니다.

필수적으로 입력해야 하는 항목은 아래 5가지입니다. 이 외에는 기본값으로 설정해도 문제 없습니다.

Use unique user id 옵션은 로그인 시 넘겨받은 해쉬값을 각각의 사용자ID로 사용하는 옵션입니다. Authentik외에도 다른 로그인 인증 수단을 같이 겸해서 사용하는 상황에서 사용자를 구별하기 좋은 옵션이며, 해당 옵션을 해제하면 Authenik에서 사용하는 ID를 넘겨 받습니다.

입력을 완료하면 최하단의 Submit버튼을 클릭해 완료해 줍니다.

이후 로그인 화면에 Login with Authentik 버튼이 활성화되며, 문제 없이 로그인 할 수 있게 됩니다.

 

Social Login을 사용하는 경우

해외의 많은 가이드들이 OpenID Connect user backend 플러그인을 사용하여 구성하는 가이드를 작성했는데, Social Login 플러그인도 사용해보니 좋은 것 같아 함께 소개합니다.

 

애플리케이션, Provider 설정하기

위의 OpenID Connect user backend와 동일하게 설정하되 Redirect URI만 변경됩니다.

이 역시 3가지 중 에러 없는 것을 사용하면 됩니다.

• https://{Nextcloud 주소}/apps/sociallogin/custom_oidc/{internal name}
• https://{Nextcloud 주소}/index.php/apps/sociallogin/custom_oidc/{internal name}
• https://{Nextcloud 주소}:443/apps/sociallogin/custom_oidc/{internal name}

예시에서는 아래와 같이 작성됩니다.

https://nextsample.fentanest.com:443/apps/sociallogin/custom_oidc/authentik

 

Nextcloud 설정하기

앱 – 소셜 및 통신에 Social Login을 설치하면, 관리자 설정 – Social Login 탭이 생성됩니다.

Custom OpenID Connect를 클릭합니다.

아래와 같은 창이 나타나는데, 모두 Authentik에서 긁어올 수 있는 주소입니다.

각각에 맞게 붙여넣어 줍니다.

이후 로그인 화면에 Login with Authentik 버튼이 생성된 것을 확인할 수 있고, 로그인도 잘 작동됩니다.

 

추가 속성 매핑

이 단계를 거치면,

• 위의 Immich처럼 OAuth/OpenID를 통해 생성된 계정의 할당 용량을 제한하거나
• Authentik에 지정되어 있는 그룹을 매핑하여 Nextcloud에 동일하게 생성하거나
• (기존에 이미 생성되어 있는) 계정에 연동시키는 것이 가능합니다.

상기 기능이 필요하지 않거나 고려하지 않을 경우 이 단계는 건너뛰어도 무관합니다.

Customization – 속성 매핑 – 생성 – Scope Mapping 을 순차적으로 따라갑니다.

범위 이름에 profile, 표현식에는 아래 내용을 복사 붙여넣기 해 줍니다.

이름의 경우 식별 가능하게 취향대로 정하면 되고, 기술 항목의 경우 위의 Immich처럼 사용자에게 표시될 권한 요청 설명입니다.

groups = [group.name for group in user.ak_groups.all()]
if user.is_superuser and "admin" not in groups:
    groups.append("admin")
return {
    "name": request.user.name,
    "groups": groups,
    "quota": user.group_attributes().get("nextcloud_quota", None),
    "user_id": user.attributes.get("nextcloud_user_id", str(user.uuid)),
}

속성 매핑 생성을 완료하였다면, Provider에서 해당 속성을 추가합니다.

이 과정을 통해 사용할 수 있는 scope는 총 4개입니다. nextcloud_quota(계정 할당 용량), name(이름), groups(그룹), nextcloud_user_id(기생성된 Nextcloud 계정)

이 중 groups는 Authentik에 사전 정의된 그룹을 따라가고, user_id는 필요한 경우에만 사용하는 속성이므로, quota와 name만 Authentik에서 정의하면 됩니다.

quota는 유저 혹은 그룹의 특성(Attributes)에서 지정할 수 있습니다. 단위가 byte이기 때문에, 25를 입력하면 25B, 25G를 입력하면 25GB가 됩니다.

name은 각 유저의 표시 이름을 사용합니다.

Nextcloud의 Social Login이나 OpenID Connect user backend에서 관련 scope를 포함해 줍니다.

(Social Login 플러그인의 경우 quota를 기입해도 매칭항목이 구성되어 있지 않아 용량 제한은 적용되지 않습니다.)

• OpenID Connect user backend

• Social Login

(OpenID Connect user backend 플러그인의 경우) User ID mapping의 기본값은 sub입니다. sub는 subject의 약자로, Provider에서 subject모드로 지정하는 값입니다.

ID기반일 경우 sub에 숫자가 출력되며, Authentik 공식 권장사항은 UUID입니다.

그러나 UUID로 설정할 경우 federated cloud ID가 심각하게 길어지는 문제가 있어, subject 모드를 사용자이름 기반으로 사용하거나,

바로 위의 스크린샷처럼 User ID mapping에 name을 매핑시킬 수도 있습니다.

단, 이 경우 Authentik에서 사용자가 ID를 변경할 수 있을 경우, 보안 상 위험을 초래할 수 있으므로 아이디 변경 허용 옵션을 비활성화 해 주어야 합니다.

 

로그인하면, 자동으로 그룹이 생성되고 테스트 계정이 해당 그룹에 속하는 것을 볼 수 있으며 사용자 이름과 계정 할당 용량까지 잘 적용되는 것을 확인할 수 있습니다.

 

Portainer와 연동하기

리버스 프록시 연결하기

예시로는 portainer.fentanest.com을 사용하겠습니다.

 

애플리케이션, Provider 생성하기

애플리케이션 – 공급자 – 생성 – OAuth2/OpenID Provider를 선택하여 생성해 줍니다.

서명 키는 아무 인증서나 사용할 수 있고, 리디렉션 URI는 리버스 프록시 주소를 입력하면 됩니다.

이 글에서는 https://portainer.fentanest.com이 됩니다.

애플리케이션 – 애플리케이션으로 이동해 portainer 연동에 사용할 애플리케이션을 생성합니다.

 

Portainer 설정하기

User-related 메뉴로 진입해 연동된 유저의 기본 팀(그룹)을 생성해 줍니다.

Settings – Authentication 메뉴로 진입합니다.

OAuth, Single Sign-On, Automatic user provisioning을 선택합니다.

Provider는 Custom을 클릭한 뒤 아래 내용에 맞춰 항목을 채워주면 됩니다.

• Client ID : 클라이언트 ID
• Client Secret : 클라이언트 비밀
• Authorization URL : 인가 URL
• Access token URL : 토큰 URL
• Resource URL : 사용자정보 URL
• Redirect URL : https://{portainer 주소}
• Logout URL : 로그아웃 URL
• User identifier : preferred_username
• Scopes : email openid profile

로그아웃 후 portainer에 다시 접속하면 로그인 창이 변경된 것을 확인할 수 있습니다.

Login with OAuth를 클릭해 Authentik을 통한 로그인을 수행할 수 있습니다.

 

Komga와 연동하기

리버스 프록시 연결하기

예시로는 komgasample.fentanest.com을 사용하겠습니다.

 

애플리케이션, Provider 생성하기

애플리케이션 – 공급자 – 생성 – OAuth2/OpenID Provider를 선택하여 생성해 줍니다.

Redirect URI는 https://{komga 주소}/login/oauth2/code/authentik을 입력하면 됩니다.

Subject모드는 사용자이름 기반으로 설정합니다.

애플리케이션도 같이 생성합니다.

 

Komga 설정하기

아래 글을 참조해 komga config폴더 내부에 application.yml을 생성하고 아래와 같이 입력합니다.

웹 만화책 뷰어 Komga 소셜로그인 구성해서 사용하기

spring:
  security:
    oauth2:
      client:
        registration:
          authentik:
            provider: authentik
            client-id: {client-id} #Authentik의 클라이언트 ID
            client-secret: {client-secret} #Authentik의 클라이언트 비밀
            client-name: Authentik
            scope: openid,email
            authorization-grant-type: authorization_code
            redirect-uri: "{baseUrl}/{action}/oauth2/code/{registrationId}" #{}안의 값은 수정하지 마세요!
        provider:
          authentik:
            user-name-attribute: sub
            issuer-uri: https://authsample.fentanest.com/application/o/komga/

또한, environment에 아래 값이 정의되어 있어야 합니다.

이후 Komga를 재시작하면 메인 화면에 SIGN IN WITH AUTHENTIK버튼을 통해 성공적으로 로그인 할 수 있게 됩니다.

 

그 외 앱 연동 예시

아래 링크를 클릭하면 해당하는 문단으로 이동합니다.

Jellyfin

오라클 클라우드에 Jellyfin으로 나만의 넷플릭스 구축하기

 

Alist

다목적 웹 기반 파일 매니저 AList 구축하기

 

Synology DSM

Authentik으로 홈서버 SSO 구현하기 (7) – 시놀로지 회원 가입(계정 자동 생성) 구현하기

 

Cloudflare에 인증 수단으로 사용하기

Authentik은 OpenID유형의 공급자를 설정할 수 있고, Cloudflare도 이를 지원하기 때문에, OpenID를 통해 연결해보겠습니다.

이 설정을 완료하면, Cloudflare에서 사전에 설정한 App에 접근하기 위한 인증 수단으로 Authentik을 사용할 수 있게 됩니다.

먼저, Cloudflare에 연결된 도메인에서 Zero Trust – Settings – Custom Page를 클릭합니다.

여기서, Team Domain이 필요합니다. 정확히는 맨 앞 CNAME부분만 있으면 됩니다.

클라우드플레어를 통해 Authentication을 설정했던 분이라면 미리 설정이 되어 있을 겁니다.

이제 Authentik으로 돌아와서 애플리케이션 – 공급자를 클릭한 후 OpenID를 선택합니다.

이름과 인증 플로우, 인가 플로우 등을 설정합니다.

리디렉션 URI/Origin에는 아래와 같이 입력합니다. <your-team-name>에 위에서 알아왔던 Team Domain의 앞부분을 적어줍니다.

Team Domain이 sample.cloudflareaccess.com이었다면 sample이 됩니다.

https://<your-team-name>.cloudflareaccess.com/cdn-cgi/access/callback

서명 키는 자체서명키를 사용해도 되고, 가지고 온 인증서를 사용해도 됩니다.

이번엔, 애플리케이션 – 애플리케이션에서 생성을 클릭해 애플리케이션을 하나 생성해 줍니다. 이름에 큰 의미는 없고 본인이 식별할 수 있으면 됩니다.

이후 공급자를 위에서 만든 Cloudflare를 선택해 줍니다.

다시 Cloudflare에서 Zero Trust – Settings – Authentication을 클릭합니다.

Login Method의 Add new, OpenID Connect를 선택합니다.

그러면 아래와 같은 창을 확인할 수 있습니다. 입력해야 할 내용은 아래와 같습니다.

• App ID : 아래 Authentik에서 확인한 클라이언트 ID
• Client secret : Authentik에서 확인한 클라이언트 비밀

• Auth URL : https://<domain>/application/o/authorize/
• Token URL : https://<domain>/application/o/token/
• Certificate URL : https://<domain>/application/o/cloudflare/jwks/

그리고 스크롤을 내려 최하단에 아래 두 개를 입력해 줍니다.

입력 후 최하단의 Test를 클릭하면 아래와 같이 테스트가 정상적으로 이루어지는 것을 확인할 수 있습니다.

 

문제 해결(Trouble Shooting)

TrueNAS + Nextcloud에서 Local IP로 Overwrite될 때

TrueNAS에서 Nextcloud를 설치할 때, TrueNAS 기본 인증서를 선택하면 pods에 Nginx컨테이너도 같이 생성됨과 동시에 config.php에 접속 주소를 overwrite하는 옵션이 생성됩니다.

해당 옵션 때문에, 외부 도메인 주소로 접속해도 내부 IP로 리다이렉트 되며 외부 환경에서 접속 장애를 유발합니다.

이 경우 TrueNAS상의 Nextcloud옵션 중 Local IP로 적혀있던 Host를 도메인 주소로 바꾸고 Use different port for URL rewrites 옵션을 활성화하고 443포트를 적어서 강제로 리다이렉트 시켜주면 됩니다.

단, 이렇게 구성할 경우 Provider에서 Redirect URI 지정 시 포트를 명시하여야 합니다.

https://{Nextcloud주소}:443

 

---

 

관련 글

2025.01.23 - [Apps] - Authentik으로 홈서버 SSO 구현하기 (1) – 설치

Authentik으로 홈서버 SSO 구현하기 (1) – 설치

2025.01.23 - [Apps] - Authentik으로 홈서버 SSO 구현하기 (2) – LDAP

Authentik으로 홈서버 SSO 구현하기 (2) – LDAP

2025.01.23 - [Apps] - Authentik으로 홈서버 SSO 구현하기 (4) – SAML

Authentik으로 홈서버 SSO 구현하기 (4) – SAML

2025.01.23 - [Apps] - Authentik으로 홈서버 SSO 구현하기 (5) - Proxy

Authentik으로 홈서버 SSO 구현하기 (5) - Proxy

2025.01.23 - [Apps] - Authentik으로 홈서버 SSO 구현하기 (6) – 회원 가입, 초대 코드, 소셜 로그인

Authentik으로 홈서버 SSO 구현하기 (6) – 회원 가입, 초대 코드, 소셜 로그인

2025.01.23 - [Apps] - Authentik으로 홈서버 SSO 구현하기 (7) – 시놀로지 회원 가입(계정 자동 생성) 구현하기

Authentik으로 홈서버 SSO 구현하기 (7) – 시놀로지 회원 가입(계정 자동 생성) 구현하기

 

---

 

출처

1. https://docs.goauthentik.io/integrations/services/

Integrate with Applications | authentik

2. https://developers.cloudflare.com/cloudflare-one/identity/idp-integration/generic-oidc/

Generic OIDC · Cloudflare Zero Trust docs