> For the complete documentation index, see [llms.txt](https://ayakaleaf-pro.ayaka.space/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ayakaleaf-pro.ayaka.space/on-premises/ko/configuration/overleaf-toolkit/authentication/oidc-authentication.md).

# OIDC 인증

이 기능은 다음에 의해 개발되었습니다 [yu-i-i/overleaf-cep](https://github.com/yu-i-i/overleaf-cep). 여기에서는 구성에 필요한 몇 가지 문서를 제공합니다.

### 설정

내부적으로 Overleaf OIDC 모듈은 [passport-openidconnect](https://github.com/jaredhanson/passport-openidconnect) 라이브러리를 사용합니다. OpenID Connect 구성이 잘 되지 않는다면, 다음 README를 읽어보는 것이 좋습니다: `passport-openidconnect` 예상하는 구성이 어떤 것인지 감을 잡아보세요.

환경 변수 `EXTERNAL_AUTH` OIDC 인증 모듈을 활성화하려면 필요합니다. 이 환경 변수는 어떤 외부 인증 방법이 활성화되는지를 지정합니다. 이 변수의 값은 목록입니다. 목록에 `oidc` 가 포함되어 있으면 OIDC 인증이 활성화됩니다.

예: `EXTERNAL_AUTH=ldap oidc`

OIDC 인증 방법을 사용할 때 사용자는 Identity Provider(IdP) 인증 사이트로 리디렉션됩니다. IdP가 사용자를 성공적으로 인증하면, Overleaf 사용자 데이터베이스에서 다음을 포함하는 레코드를 확인합니다. `thirdPartyIdentifiers` 다음과 같은 구조의 필드:

```
thirdPartyIdentifiers: [
  {
    externalUserId: "...",
    externalData: null,
    providerId: "..."
  }
]
```

다음 `externalUserId` 는 IdP 서버가 반환한 프로필의 사용자 ID와 일치해야 합니다(다음을 참조하세요. `OVERLEAF_OIDC_USER_ID_FIELD` 환경 변수), 그리고 `providerId` 는 OIDC 공급자의 ID와 일치해야 합니다(다음을 참조하세요. `OVERLEAF_OIDC_PROVIDER_ID`).

일치하는 레코드가 없으면, 데이터베이스에서 IdP 사용자 프로필의 이메일과 기본 이메일 주소가 일치하는 사용자를 검색합니다:

* 해당 사용자가 발견되면, `thirdPartyIdentifiers` 필드가 업데이트됩니다.
* 일치하는 사용자가 없고 JIT 계정 생성이 비활성화되어 있지 않으면, 이메일 주소와 `thirdPartyIdentifiers` 를 사용해 새 사용자가 IdP 프로필에서 생성됩니다.

두 경우 모두 해당 사용자는 외부 OIDC 사용자와 '연결됨(linked)' 상태라고 합니다. 사용자는 OIDC 공급자와의 연결을 다음에서 해제할 수 있습니다. `/user/settings` 페이지.

#### 환경 변수

다음 다섯 개 필수 변수의 값은 다음을 사용해 찾을 수 있습니다. `.well-known/openid-configuration` OpenID Provider(OP)의 엔드포인트입니다.

* `OVERLEAF_OIDC_ISSUER` **(필수)**
* `OVERLEAF_OIDC_AUTHORIZATION_URL` **(필수)**
* `OVERLEAF_OIDC_TOKEN_URL` **(필수)**
* `OVERLEAF_OIDC_USER_INFO_URL` **(필수)**
* `OVERLEAF_OIDC_LOGOUT_URL` **(필수)**

다음 두 개의 필수 변수의 값은 OP 관리자에 의해 제공됩니다

* `OVERLEAF_OIDC_CLIENT_ID` **(필수)**
* `OVERLEAF_OIDC_CLIENT_SECRET` **(필수)**
* `OVERLEAF_OIDC_SCOPE`
  * 기본값: `openid profile email`
* `OVERLEAF_OIDC_PROVIDER_ID`
  * OP의 임의 ID, 기본값: `oidc`.
* `OVERLEAF_OIDC_PROVIDER_NAME`
  * OP의 이름으로, 다음에서 사용됩니다. `연결된 계정` 섹션 `/user/settings` 페이지, 기본값: `OIDC 공급자`.
* `OVERLEAF_OIDC_IDENTITY_SERVICE_NAME`
  * 로그인 페이지에서 사용되는 신원 서비스의 표시 이름(기본값: `$OVERLEAF_OIDC_PROVIDER_NAME으로 로그인`).
* `OVERLEAF_OIDC_PROVIDER_DESCRIPTION`
  * OP 설명으로, 다음에서 사용됩니다. `연결된 계정` 섹션(기본값: `$OVERLEAF_OIDC_PROVIDER_NAME으로 로그인`).
* `OVERLEAF_OIDC_PROVIDER_INFO_LINK`
  * `자세히 알아보기` OP 설명의 URL, 기본값: 없음 `자세히 알아보기` 설명에 링크 없음.
* `OVERLEAF_OIDC_PROVIDER_HIDE_NOT_LINKED`
  * 다음 페이지에서 OP를 표시하지 마십시오. `/user/settings` 사용자 계정이 OP와 연결되어 있지 않으면, 기본값 `false`.
* `OVERLEAF_OIDC_USER_ID_FIELD`
  * 이 속성의 값은 Overleaf에서 외부 사용자 ID로 사용되며, 기본값은 `id`. 그 밖에 합리적인 가능한 값으로는 `email` 및 `사용자 이름` (다음에 해당 `preferred_username` OIDC 클레임).
* `OVERLEAF_OIDC_ALLOWED_EMAIL_DOMAINS`
  * OIDC를 통해 인증하는 사용자의 Just-in-Time(JIT) 계정 생성을 제한합니다. 쉼표로 구분된 도메인 이름 목록으로 설정하면, 사용자의 이메일 주소 도메인이 나열된 도메인 중 하나와 일치할 때만 새 계정이 생성됩니다. 도메인이 일치하지 않으면 관리자는 OIDC 사용자의 이메일 주소를 사용해 사용자 계정을 수동으로 생성해야 하며, 강력한 무작위 비밀번호를 사용하거나, 가능하면 아예 `hashedPassword` 필드 없이 생성해야 합니다. 도메인 이름에는 하위 도메인과 일치시키기 위한 선행 `*.` 와일드카드를 포함할 수 있습니다.
    * 예: 다음과 같은 이메일 주소를 가진 사용자에 대해 JIT 계정 생성을 허용하려면 `name@example.com` 및 `name@math.example.com`:\
      `OVERLEAF_OIDC_ALLOWED_EMAIL_DOMAINS=example.com, *.example.com`
    * 예: JIT 계정 생성을 완전히 비활성화하려면:\
      `OVERLEAF_OIDC_ALLOWED_EMAIL_DOMAINS=`
* `OVERLEAF_OIDC_UPDATE_USER_DETAILS_ON_LOGIN`
  * 다음으로 설정하면 `true`, 로그인 시 사용자의 `이름` 및 `성과` 필드를 업데이트하고, 다음에서 사용자 세부정보 양식을 비활성화합니다. `/user/settings` 페이지.
* `OVERLEAF_OIDC_IS_ADMIN_FIELD` 및 `OVERLEAF_OIDC_IS_ADMIN_FIELD_VALUE`
  * 두 환경 변수가 모두 설정되면, 로그인 과정에서 `user.isAdmin = true` OP가 반환한 프로필에 다음으로 지정된 속성이 포함되어 있고 `OVERLEAF_OIDC_IS_ADMIN_FIELD` 그 값이 다음과 일치하면 `OVERLEAF_OIDC_IS_ADMIN_FIELD_VALUE`을 포함하는 배열인 경우 `user.isAdmin` 은 `false`. 만약 `OVERLEAF_OIDC_IS_ADMIN_FIELD` 이 `email` 그렇다면 속성의 값 `emails[0].value` 가 일치 여부 확인에 사용됩니다.

OpenID Provider의 리디렉션 URL은 다음과 같습니다. `https://my-overleaf-instance.com/oidc/login/callback`.

<details>

<summary>샘플 variables.env 파일</summary>

{% code title="variables.env" overflow="wrap" %}

```dotenv
OVERLEAF_APP_NAME="우리 Overleaf 인스턴스"

ENABLED_LINKED_FILE_TYPES=project_file,project_output_file,url

# ImageMagick을 사용한 썸네일 생성을 활성화합니다
ENABLE_CONVERSIONS=true

# 이메일 확인 요구 사항을 비활성화합니다
EMAIL_CONFIRMATION_DISABLED=true

## Nginx
# NGINX_WORKER_PROCESSES=4
# NGINX_WORKER_CONNECTIONS=768

## nginx-proxy를 통한 TLS용으로 설정
# OVERLEAF_BEHIND_PROXY=true
# OVERLEAF_SECURE_COOKIE=true

OVERLEAF_SITE_URL=http://my-overleaf-instance.com
OVERLEAF_NAV_TITLE=우리 Overleaf 인스턴스
# OVERLEAF_HEADER_IMAGE_URL=http://somewhere.com/mylogo.png
OVERLEAF_ADMIN_EMAIL=support@example.com

OVERLEAF_LEFT_FOOTER=[{"text": "지원팀에 문의하세요", "url": "mailto:support@example.com"}]
OVERLEAF_RIGHT_FOOTER=[{"text":"안녕하세요, 저는 오른쪽에 있습니다", "url":"https://github.com/yu-i-i/overleaf-cep"}]

OVERLEAF_EMAIL_FROM_ADDRESS=team@example.com
OVERLEAF_EMAIL_SMTP_HOST=smtp.example.com
OVERLEAF_EMAIL_SMTP_PORT=587
OVERLEAF_EMAIL_SMTP_SECURE=false
# OVERLEAF_EMAIL_SMTP_USER=
# OVERLEAF_EMAIL_SMTP_PASS=
# OVERLEAF_EMAIL_SMTP_NAME=
OVERLEAF_EMAIL_SMTP_LOGGER=false
OVERLEAF_EMAIL_SMTP_TLS_REJECT_UNAUTH=true
OVERLEAF_EMAIL_SMTP_IGNORE_TLS=false
OVERLEAF_CUSTOM_EMAIL_FOOTER=이 시스템은 x 부서에서 운영합니다

OVERLEAF_PROXY_LEARN=true
NAV_HIDE_POWERED_BY=true

#################
## CE용 OIDC ##
#################

EXTERNAL_AUTH=oidc

OVERLEAF_OIDC_PROVIDER_ID=oidc
OVERLEAF_OIDC_ISSUER=https://keycloak.provider.com/realms/example
OVERLEAF_OIDC_AUTHORIZATION_URL=https://keycloak.provider.com/realms/example/protocol/openid-connect/auth
OVERLEAF_OIDC_TOKEN_URL=https://keycloak.provider.com/realms/example/protocol/openid-connect/token
OVERLEAF_OIDC_USER_INFO_URL=https://keycloak.provider.com/realms/example/protocol/openid-connect/userinfo
OVERLEAF_OIDC_LOGOUT_URL=https://keycloak.provider.com/realms/example/protocol/openid-connect/logout
OVERLEAF_OIDC_CLIENT_ID=Overleaf-OIDC
OVERLEAF_OIDC_CLIENT_SECRET=DoNotUseThisATGgaAcTgCcATgGATTACAagGtTCaGcGTAG
OVERLEAF_OIDC_IDENTITY_SERVICE_NAME='Keycloak OIDC 공급자로 로그인'
OVERLEAF_OIDC_PROVIDER_NAME=OIDC Keycloak 공급자
OVERLEAF_OIDC_PROVIDER_INFO_LINK=https://openid.net
OVERLEAF_OIDC_IS_ADMIN_FIELD=email
OVERLEAF_OIDC_IS_ADMIN_FIELD_VALUE=overleaf.admin@example.com
OVERLEAF_OIDC_UPDATE_USER_DETAILS_ON_LOGIN=false
```

{% endcode %}

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://ayakaleaf-pro.ayaka.space/on-premises/ko/configuration/overleaf-toolkit/authentication/oidc-authentication.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.