로그인과 비밀번호

설정

사람들이 어떻게 로그인할지 정합니다. 비밀번호 길이, 홈 네트워크 바로 열기, 외부 로그인이 여기에 해당합니다. 이 설정은 소유자만 Settings > Sign-in and security(설정 > 로그인 및 보안)에서 바꿀 수 있습니다.

비밀번호 최소 길이 정하기

Settings > Sign-in and security > Passwords(설정 > 로그인 및 보안 > 비밀번호)를 여세요.
4에서 64 사이의 숫자를 입력하세요. 기본값은 8입니다.
Save(저장)를 선택하세요. 페이지를 새로 고쳐도 새 숫자가 그대로 표시됩니다.

최소 길이는 새로 만드는 모든 비밀번호에 적용됩니다. 첫 소유자, 수락한 초대, My account(내 계정)에서의 변경, holyarrs reset-owner가 모두 해당합니다. 기존 비밀번호는 다음에 바꿀 때까지 그대로 쓸 수 있습니다. 비밀번호는 최대 1024자입니다.

로컬 네트워크에서 로그인 건너뛰기

홈 네트워크에 있는 기기는 비밀번호 없이 소유자로 HolyArrs를 엽니다. 기본값은 꺼짐입니다.

Settings > Sign-in and security > Local network(설정 > 로그인 및 보안 > 로컬 네트워크)를 여세요.
네트워크를 한 줄에 하나씩, 최대 32개까지 적으세요. 범위(192.168.1.0/24, fd00::/8)나 주소 하나(192.168.1.20)를 쓸 수 있습니다.
스위치를 켜고 저장하세요. 카드에 지금 쓰는 기기의 주소가 표시됩니다.

목록이 비어 있거나 어린이 계정이 하나라도 있으면 스위치를 켤 수 없습니다. API 키 만들기, 로그인 설정 변경, 비밀 값 읽기나 교체, 백업 복원은 여전히 비밀번호를 묻습니다.

먼저 주소 확인하기

일부 구성에서는 모든 기기가 게이트웨이 주소 하나로 보입니다. Docker Desktop, rootless Docker나 Podman, Kubernetes NodePort가 그렇습니다. 흔한 주소는 172.17.0.1, 172.18.0.1 이상, 10.88.0.1, 10.89.x.1, 10.0.2.2, 192.168.65.x입니다.

이런 주소를 목록에 넣으면 HolyArrs에 접속하는 사람은 누구나 소유자로 들어옵니다. 그런 주소로 보이는 항목이 있으면 카드에 경고가 표시됩니다. 다른 기기에서 이 페이지를 열어 보세요. 같은 주소가 표시되면 스위치를 끄고 그 항목을 지우세요.

리버스 프록시 뒤에서는 HolyArrs가 HOLYARRS_TRUSTED_PROXIES에 있는 프록시가 전달한 주소만 읽습니다. 그렇지 않으면 카드에 주소가 표시되지 않고, 프록시를 신뢰하지 않는다는 안내가 나옵니다.

통합 로그인(SSO)

OpenID Connect 제공자 하나로 로그인할 수 있습니다. 로그인 페이지에 버튼으로 표시됩니다.

Settings > Sign-in and security > Single sign-on(설정 > 로그인 및 보안 > 통합 로그인)을 여세요.
제공자의 issuer를 입력하고 Test(테스트)를 선택하세요. 테스트에는 비밀 값이 전송되지 않습니다.
client id와 client secret을 입력하세요. 제공자가 비밀 값을 쓰지 않으면 Public client(공개 클라이언트)에 체크하세요.
Callback address(콜백 주소)를 복사해 제공자 쪽에 그 주소 그대로 등록하세요.
비밀번호를 입력하고, 2단계 인증을 쓰고 있다면 그 코드도 입력한 다음 Save를 선택하세요. 변경할 때마다 이 확인을 거칩니다.

그다음 내 계정을 연동하세요. 비밀번호로 로그인하고 My account를 연 뒤, Linked sign-ins(연동된 로그인) 아래에서 Link(연동)를 선택하고, 비밀번호를 확인한 다음 Single sign-on을 선택하세요.

선택 사항

새 사람이 통합 로그인으로 가입하게 하기

기본값은 꺼짐입니다. 켜면 제공자가 로그인시킨 사람은 누구나 계정을 받으므로, HolyArrs가 확인을 한 번 요청합니다. 새로 온 사람은 요청만 할 수 있는 멤버로 가입됩니다. 통합 로그인으로는 소유자나 관리자가 만들어지지 않습니다.

issuer나 client id 바꾸기

비밀 값을 다시 입력해야 합니다. 기존 연동은 지워지고, 통합 로그인을 쓰던 사람은 모두 로그아웃됩니다. 각자 My account에서 다시 연동하면 됩니다. 통합 로그인을 꺼도 로그아웃됩니다.

로그인 연동 해제하기

내 것: My account > Linked sign-ins > Unlink(내 계정 > 연동된 로그인 > 연동 해제). 최근에 비밀번호를 확인한 상태여야 하고, 그것이 유일한 로그인 방법이면 거부됩니다.
다른 사람 것: 소유자가 Settings > Users and roles(설정 > 사용자와 역할)에서 합니다. 그 사람의 유일한 로그인 방법이면 HolyArrs가 한 번 더 묻습니다.

연동을 해제하면 그 방법으로 로그인한 기기가 로그아웃됩니다. 가입이 열려 있으면 같은 사람이 새 멤버로 다시 들어올 수 있습니다. 막으려면 가입을 끄세요.

문제가 생기면

증상: HolyArrs가 비밀번호를 다시 묻습니다. 원인: 계정, 키, 설정을 바꾸려면 최근 10분 안에 비밀번호를 확인한 상태여야 하고, 2단계 인증을 설정했다면 그것도 필요합니다. 외부 로그인과 로컬 네트워크 바로 열기는 여기에 포함되지 않습니다. 해결: 비밀번호로 확인하세요. 로그아웃과 기기 연결 끊기는 확인을 묻지 않습니다.

증상: 콜백이 짧은 오류와 함께 실패하고, 로그인되지 않은 상태로 남습니다. 원인: 제공자 쪽의 콜백 주소가 HolyArrs의 주소와 다릅니다. 해결: Callback address를 다시 복사해 제공자 쪽에 그대로 붙여 넣으세요.

증상: 통합 로그인으로 만든 계정은 비밀번호를 정할 수 없습니다. 원인: 이 버전에서는 지원하지 않습니다. 해결: 로컬 소유자를 먼저 만든 다음, 통합 로그인을 그 계정에 연동하세요.

증상: HolyArrs에서 로그아웃했는데 제공자 쪽에는 로그인된 채로 남아 있습니다. 원인: HolyArrs는 자기 로그인만 끝냅니다. 해결: 여럿이 쓰는 기기에서는 제공자 쪽에서도 로그아웃하세요.

소유자 비밀번호를 잊으셨나요? 세션과 비밀번호를 보세요.

전문가용

신뢰하는 프록시 로그인

리버스 프록시가 이미 로그인을 처리하고 있다면, HolyArrs는 프록시가 넘겨주는 이름을 받아들입니다. 환경 변수로만 설정할 수 있습니다. 로그인 페이지에 버튼으로 표시되며, 헤더만으로 방문자가 바로 로그인되는 일은 없습니다.

프록시는 들어오는 Remote-User와 Remote-Name을 지우고, 로그인 후에 자기 값을 넣습니다.
Remote-User: 바뀌지 않는 이름 하나, 최대 255바이트. Remote-Name: 선택 사항인 표시 이름, 최대 200바이트.
반복된 값, 쉼표로 이어 붙인 값, 제어 문자가 들어간 값은 거부됩니다. 역할 헤더는 무시됩니다.

HolyArrs에는 그 프록시를 통해서만 접속할 수 있게 하세요. 프록시 주소를 신뢰한다는 것은 그 프록시가 보내는 모든 이름을 신뢰한다는 뜻입니다. My account > Link trusted proxy sign-in(내 계정 > 신뢰하는 프록시 로그인 연동)에서 계정에 연동하세요.

환경 변수

시작하기 전에 설정하세요. 두 방법 모두 켜지 않으면 꺼져 있습니다. 설정이 잘못되면 HolyArrs가 시작되지 않습니다. 제공자에 장애가 나도 비밀번호 로그인은 계속 됩니다. HOLYARRS_OIDC_ENABLED가 조금이라도 설정되어 있으면, 값이 false여도 통합 로그인은 환경 변수가 관리하고 설정 페이지는 보여 주기만 합니다.

변수	하는 일	기본값
`HOLYARRS_OIDC_ENABLED`	통합 로그인 켜기	`false`
`HOLYARRS_OIDC_ISSUER`	제공자의 정확한 HTTPS issuer	없음
`HOLYARRS_OIDC_CLIENT_ID`	등록한 client id	없음
`HOLYARRS_OIDC_CLIENT_SECRET_FILE`	client secret이 든 파일, 최대 4096바이트. 공개 클라이언트면 비워 두세요	없음
`HOLYARRS_OIDC_REDIRECT_URL`	정확한 HTTPS 콜백: 내 주소, URL base가 있으면 그것, 그다음 `/api/v1/auth/oidc/callback`	없음
`HOLYARRS_OIDC_ALLOW_JOIN`	새 사람이 요청만 할 수 있는 멤버로 가입	`false`
`HOLYARRS_OIDC_ALLOW_LOCAL_NETWORK`	사설 네트워크에 있는 제공자 허용	`false`
`HOLYARRS_OIDC_ALLOW_LOOPBACK_HTTP`	테스트용으로 루프백에서 일반 HTTP 허용	`false`
`HOLYARRS_FORWARD_AUTH_ENABLED`	신뢰하는 프록시 로그인 켜기	`false`
`HOLYARRS_FORWARD_AUTH_ISSUER`	이 프록시의 바뀌지 않는 HTTPS 이름. 값이 바뀌면 새 출처로 취급됩니다	없음
`HOLYARRS_FORWARD_AUTH_TRUSTED_PEERS`	쉼표로 구분한 프록시 주소나 범위. 필수. 모든 주소를 포함하는 범위는 거부됩니다	없음
`HOLYARRS_FORWARD_AUTH_ALLOW_JOIN`	프록시가 보낸 새 이름이 요청만 할 수 있는 멤버로 가입	`false`

ALLOW_LOCAL_NETWORK와 ALLOW_LOOPBACK_HTTP 두 설정은 설정 페이지에서 구성한 통합 로그인에도 적용됩니다.

통합 로그인의 동작 방식

제공자는 PKCE S256을 쓰는 authorization code 로그인과 RS256 토큰을 지원해야 하고, 모든 엔드포인트가 issuer와 같은 origin에 있어야 합니다.
계정은 제공자의 자체 계정 ID로 맞춥니다. 이메일로는 맞추지 않습니다.
제공자의 역할과 그룹은 쓰지 않습니다.
client secret은 암호화해 저장하고 다시 보여 주지 않습니다. 그대로 두려면 입력란을 비워 두세요.