Generic OAuth2 gem 을 OAuth 2.0 인증 공급자로 사용하기

요약

공급자가 OpenID 사양을 지원한다면 인증 공급자로 omniauth-openid-connect를 사용합니다. omniauth-oauth2-generic gem을 사용하면 GitLab과 OAuth 2.0 공급자 간, 또는 이 gem과 호환되는 모든 OAuth 2.0 공급자와의 싱글 사인온(SSO)을 구성할 수 있습니다.

Note

공급자가 OpenID 사양을 지원한다면 인증 공급자로 omniauth-openid-connect를 사용합니다.

omniauth-oauth2-generic gem을 사용하면 GitLab과 OAuth 2.0 공급자 간, 또는 이 gem과 호환되는 모든 OAuth 2.0 공급자와의 싱글 사인온(SSO)을 구성할 수 있습니다.

이 전략을 사용하면 다음과 같은 OmniAuth SSO 프로세스를 구성할 수 있습니다.

전략이 지정된 ID와 키를 사용해 클라이언트를 (설정 가능한) 인증 URL로 안내합니다.
OAuth 2.0 공급자가 요청과 사용자의 인증을 처리하고, (선택적으로) 사용자 프로필에 접근하기 위한 권한 부여를 처리합니다.
OAuth 2.0 공급자가 클라이언트를 다시 GitLab으로 안내하며, 여기서 전략이 액세스 토큰을 가져옵니다.
전략이 액세스 토큰을 사용해 설정 가능한 "사용자 프로필" URL에서 사용자 정보를 요청합니다.
전략이 설정 가능한 형식을 사용해 응답에서 사용자 정보를 파싱합니다.
GitLab 이 반환된 사용자를 찾거나 생성한 뒤 로그인시킵니다.

이 전략은 다음과 같은 특성을 갖습니다.

싱글 사인온에만 사용할 수 있으며, OAuth 2.0 공급자가 부여하는 다른 접근 권한은 제공하지 않습니다. 예를 들어 프로젝트나 사용자를 가져오는 기능은 지원하지 않습니다.
GitLab과 같은 클라이언트-서버 애플리케이션에서 가장 흔히 쓰이는 Authorization Grant 흐름만 지원합니다.
둘 이상의 URL에서 사용자 정보를 가져올 수 없습니다.
JWT 형식의 액세스 토큰에서 사용자 정보를 가져올 수 없습니다.
JSON을 제외한 사용자 정보 형식으로는 테스트되지 않았습니다.

OAuth 2.0 공급자 구성하기#

공급자를 구성하려면 다음 단계를 따릅니다.

인증에 사용할 OAuth 2.0 공급자에 애플리케이션을 등록합니다.

애플리케이션을 등록할 때 입력하는 리디렉션 URI는 다음과 같아야 합니다.
```
http://your-gitlab.host.com/users/auth/oauth2_generic/callback
```
이제 클라이언트 ID와 클라이언트 시크릿을 확인할 수 있습니다. 이 값이 표시되는 위치는 공급자마다 다릅니다. 애플리케이션 ID와 애플리케이션 시크릿으로 불리기도 합니다.
GitLab 서버에서 다음 단계를 완료합니다.

공통 설정을 구성해 oauth2_generic을 싱글 사인온 공급자로 추가합니다. 이렇게 하면 기존 GitLab 계정이 없는 사용자에 대해 JIT(Just-In-Time) 계정 프로비저닝이 활성화됩니다.

/etc/gitlab/gitlab.rb를 편집해 공급자 설정을 추가합니다. 예를 들면 다음과 같습니다.

gitlab_rails['omniauth_providers'] = [
  {
    name: "oauth2_generic",
    label: "Provider name", # optional label for login button, defaults to "Oauth2 Generic"
    app_id: "<your_app_client_id>",
    app_secret: "<your_app_client_secret>",
    args: {
      client_options: {
        site: "<your_auth_server_url>",
        user_info_url: "/oauth2/v1/userinfo",
        authorize_url: "/oauth2/v1/authorize",
        token_url: "/oauth2/v1/token"
      },
      user_response_structure: {
        root_path: [],
        id_path: ["sub"],
        attributes: {
          email: "email",
          name: "name"
        }
      },
      authorize_params: {
        scope: "openid profile email"
      },
      strategy_class: "OmniAuth::Strategies::OAuth2Generic"
    }
  }
]

파일을 저장하고 GitLab을 재구성합니다.
```
sudo gitlab-ctl reconfigure
```

Helm 값을 내보냅니다.

helm get values gitlab > gitlab_values.yaml

다음 내용을 Kubernetes Secret으로 사용할 oauth2_generic.yaml이라는 파일에 저장합니다.

name: "oauth2_generic"
label: "Provider name" # optional label for login button defaults to "Oauth2 Generic"
app_id: "<your_app_client_id>"
app_secret: "<your_app_client_secret>"
args:
  client_options:
    site: "<your_auth_server_url>"
    user_info_url: "/oauth2/v1/userinfo"
    authorize_url: "/oauth2/v1/authorize"
    token_url: "/oauth2/v1/token"
  user_response_structure:
    root_path: []
    id_path: ["sub"]
    attributes:
      email: "email"
      name: "name"
  authorize_params:
    scope: "openid profile email"
  strategy_class: "OmniAuth::Strategies::OAuth2Generic"

Kubernetes Secret을 생성합니다.

kubectl create secret generic -n <namespace> gitlab-oauth2-generic --from-file=provider=oauth2_generic.yaml

gitlab_values.yaml을 편집해 공급자 설정을 추가합니다.

global:
  appConfig:
    omniauth:
      providers:
        - secret: gitlab-oauth2-generic

파일을 저장하고 새 값을 적용합니다.

helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

/home/git/gitlab/config/gitlab.yml을 편집합니다.

production: &base
  omniauth:
    providers:
      - { name: "oauth2_generic",
          label: "Provider name", # optional label for login button, defaults to "Oauth2 Generic"
          app_id: "<your_app_client_id>",
          app_secret: "<your_app_client_secret>",
          args: {
            client_options: {
              site: "<your_auth_server_url>",
              user_info_url: "/oauth2/v1/userinfo",
              authorize_url: "/oauth2/v1/authorize",
              token_url: "/oauth2/v1/token"
            },
            user_response_structure: {
              root_path: [],
              id_path: ["sub"],
              attributes: {
                email: "email",
                name: "name"
              }
            },
            authorize_params: {
              scope: "openid profile email"
            },
            strategy_class: "OmniAuth::Strategies::OAuth2Generic"
          }
        }

파일을 저장하고 GitLab을 재시작합니다.

# For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

이제 로그인 페이지의 일반 로그인 폼 아래에 새 아이콘이 표시됩니다. 이 아이콘을 선택하면 공급자의 인증 프로세스가 시작됩니다. 이렇게 하면 브라우저가 OAuth 2.0 공급자의 인증 페이지로 이동합니다. 모든 과정이 정상적으로 완료되면 GitLab 인스턴스로 돌아와 로그인됩니다.

Generic OAuth2 gem 을 OAuth 2.0 인증 공급자로 사용하기

GitLab v19.5

Tier: Free, Premium, Ultimate
Offering: GitLab Self-Managed

원문 보기

번역일: 2026-09-18

요약

Note

공급자가 OpenID 사양을 지원한다면 인증 공급자로 omniauth-openid-connect를 사용합니다.

omniauth-oauth2-generic gem을 사용하면 GitLab과 OAuth 2.0 공급자 간, 또는 이 gem과 호환되는 모든 OAuth 2.0 공급자와의 싱글 사인온(SSO)을 구성할 수 있습니다.

이 전략을 사용하면 다음과 같은 OmniAuth SSO 프로세스를 구성할 수 있습니다.

전략이 지정된 ID와 키를 사용해 클라이언트를 (설정 가능한) 인증 URL로 안내합니다.
OAuth 2.0 공급자가 요청과 사용자의 인증을 처리하고, (선택적으로) 사용자 프로필에 접근하기 위한 권한 부여를 처리합니다.
OAuth 2.0 공급자가 클라이언트를 다시 GitLab으로 안내하며, 여기서 전략이 액세스 토큰을 가져옵니다.
전략이 액세스 토큰을 사용해 설정 가능한 "사용자 프로필" URL에서 사용자 정보를 요청합니다.
전략이 설정 가능한 형식을 사용해 응답에서 사용자 정보를 파싱합니다.
GitLab 이 반환된 사용자를 찾거나 생성한 뒤 로그인시킵니다.

이 전략은 다음과 같은 특성을 갖습니다.

싱글 사인온에만 사용할 수 있으며, OAuth 2.0 공급자가 부여하는 다른 접근 권한은 제공하지 않습니다. 예를 들어 프로젝트나 사용자를 가져오는 기능은 지원하지 않습니다.
GitLab과 같은 클라이언트-서버 애플리케이션에서 가장 흔히 쓰이는 Authorization Grant 흐름만 지원합니다.
둘 이상의 URL에서 사용자 정보를 가져올 수 없습니다.
JWT 형식의 액세스 토큰에서 사용자 정보를 가져올 수 없습니다.
JSON을 제외한 사용자 정보 형식으로는 테스트되지 않았습니다.

OAuth 2.0 공급자 구성하기#

공급자를 구성하려면 다음 단계를 따릅니다.

인증에 사용할 OAuth 2.0 공급자에 애플리케이션을 등록합니다.

애플리케이션을 등록할 때 입력하는 리디렉션 URI는 다음과 같아야 합니다.
```
http://your-gitlab.host.com/users/auth/oauth2_generic/callback
```
이제 클라이언트 ID와 클라이언트 시크릿을 확인할 수 있습니다. 이 값이 표시되는 위치는 공급자마다 다릅니다. 애플리케이션 ID와 애플리케이션 시크릿으로 불리기도 합니다.
GitLab 서버에서 다음 단계를 완료합니다.

/etc/gitlab/gitlab.rb를 편집해 공급자 설정을 추가합니다. 예를 들면 다음과 같습니다.

gitlab_rails['omniauth_providers'] = [
  {
    name: "oauth2_generic",
    label: "Provider name", # optional label for login button, defaults to "Oauth2 Generic"
    app_id: "<your_app_client_id>",
    app_secret: "<your_app_client_secret>",
    args: {
      client_options: {
        site: "<your_auth_server_url>",
        user_info_url: "/oauth2/v1/userinfo",
        authorize_url: "/oauth2/v1/authorize",
        token_url: "/oauth2/v1/token"
      },
      user_response_structure: {
        root_path: [],
        id_path: ["sub"],
        attributes: {
          email: "email",
          name: "name"
        }
      },
      authorize_params: {
        scope: "openid profile email"
      },
      strategy_class: "OmniAuth::Strategies::OAuth2Generic"
    }
  }
]

파일을 저장하고 GitLab을 재구성합니다.
```
sudo gitlab-ctl reconfigure
```

Helm 값을 내보냅니다.

helm get values gitlab > gitlab_values.yaml

다음 내용을 Kubernetes Secret으로 사용할 oauth2_generic.yaml이라는 파일에 저장합니다.

name: "oauth2_generic"
label: "Provider name" # optional label for login button defaults to "Oauth2 Generic"
app_id: "<your_app_client_id>"
app_secret: "<your_app_client_secret>"
args:
  client_options:
    site: "<your_auth_server_url>"
    user_info_url: "/oauth2/v1/userinfo"
    authorize_url: "/oauth2/v1/authorize"
    token_url: "/oauth2/v1/token"
  user_response_structure:
    root_path: []
    id_path: ["sub"]
    attributes:
      email: "email"
      name: "name"
  authorize_params:
    scope: "openid profile email"
  strategy_class: "OmniAuth::Strategies::OAuth2Generic"

Kubernetes Secret을 생성합니다.

kubectl create secret generic -n <namespace> gitlab-oauth2-generic --from-file=provider=oauth2_generic.yaml

gitlab_values.yaml을 편집해 공급자 설정을 추가합니다.

global:
  appConfig:
    omniauth:
      providers:
        - secret: gitlab-oauth2-generic

파일을 저장하고 새 값을 적용합니다.

helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

/home/git/gitlab/config/gitlab.yml을 편집합니다.

production: &base
  omniauth:
    providers:
      - { name: "oauth2_generic",
          label: "Provider name", # optional label for login button, defaults to "Oauth2 Generic"
          app_id: "<your_app_client_id>",
          app_secret: "<your_app_client_secret>",
          args: {
            client_options: {
              site: "<your_auth_server_url>",
              user_info_url: "/oauth2/v1/userinfo",
              authorize_url: "/oauth2/v1/authorize",
              token_url: "/oauth2/v1/token"
            },
            user_response_structure: {
              root_path: [],
              id_path: ["sub"],
              attributes: {
                email: "email",
                name: "name"
              }
            },
            authorize_params: {
              scope: "openid profile email"
            },
            strategy_class: "OmniAuth::Strategies::OAuth2Generic"
          }
        }

파일을 저장하고 GitLab을 재시작합니다.

# For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart