SAML SSO 인테그레이션
GitLab v19.1Offering: GitLab Self-Managed, GitLab Dedicated
- Offering: GitLab Self-Managed 이 페이지에서는 GitLab Self-Managed에서 인스턴스 전체에 적용되는 SAML 싱글 사인온(SSO)을 설정하는 방법을 설명합니다. GitLab을 SAML 서비스 프로바이더(SP)로 구성할 수 있습니다.
-
Tier: Free, Premium, Ultimate
- Offering: GitLab Self-Managed
GitLab.com의 경우 [GitLab.com 그룹용 SAML SSO](/19.0/user/group/saml_sso/)를 참조하세요.
이 페이지에서는 GitLab Self-Managed에서 인스턴스 전체에 적용되는 SAML 싱글 사인온(SSO)을 설정하는 방법을 설명합니다.
GitLab을 SAML 서비스 프로바이더(SP)로 구성할 수 있습니다. 이를 통해 GitLab은 Okta 같은 SAML 아이덴티티 프로바이더(IdP)의 어설션(assertion)을 소비하여 사용자를 인증합니다.
자세한 내용은 다음을 참조하세요.
-
OmniAuth 프로바이더 설정은 OmniAuth 문서를 참조하세요.
-
자주 사용되는 용어는 용어집을 참조하세요.
GitLab에서 SAML 지원 구성#
Linux package (Omnibus)
GitLab이 HTTPS로 구성되어 있는지 확인하세요.
공통 설정을 구성하여
saml을 싱글 사인온 프로바이더로 추가하세요. 이렇게 하면 기존 GitLab 계정이 없는
사용자에 대해 Just-In-Time 계정 프로비저닝이 활성화됩니다.
사용자가 수동으로 계정을 먼저 생성하지 않고 SAML을 사용하여 가입할 수 있도록 하려면
/etc/gitlab/gitlab.rb를 편집하세요:
gitlab_rails['omniauth_allow_single_sign_on'] = ['saml']
gitlab_rails['omniauth_block_auto_created_users'] = false
선택 사항. 이메일 주소가 일치하는 경우 첫 번째 SAML 로그인을 기존 GitLab 사용자와 자동으로 연결할 수 있습니다. 이를 위해 /etc/gitlab/gitlab.rb에 다음 설정을 추가하세요:
gitlab_rails['omniauth_auto_link_saml_user'] = true
SAML 응답의 이메일과 비교 시 GitLab 계정의 기본 이메일 주소만 사용됩니다.
또는 사용자가 기존 사용자에 대해 OmniAuth 활성화를 통해 SAML 아이덴티티를 기존 GitLab 계정에 수동으로 연결할 수 있습니다.
SAML 사용자가 변경할 수 없도록 다음 속성을 구성하세요.
omniauth_auto_link_saml_user와 함께 사용할 때의Email.
사용자가 이러한 속성을 변경할 수 있으면 다른 인가된 사용자로 로그인할 수 있습니다. 이러한 속성을 변경 불가능하게 만드는 방법은 SAML IdP 문서를 참조하세요.
/etc/gitlab/gitlab.rb를 편집하여 프로바이더 구성을 추가하세요:
gitlab_rails['omniauth_providers'] = [
{
name: "saml", # This must be lowercase.
label: "Provider name", # optional label for login button, defaults to "Saml"
args: {
assertion_consumer_service_url: "https://gitlab.example.com/users/auth/saml/callback",
idp_cert_fingerprint: "2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6",
idp_sso_target_url: "https://login.example.com/idp",
issuer: "https://gitlab.example.com",
name_identifier_format: "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent"
}
}
]
| 인수 | 설명 |
|---|---|
| assertion_consumer_service_url | GitLab HTTPS 엔드포인트 (GitLab 설치의 HTTPS URL에 /users/auth/saml/callback 추가). |
| idp_cert_fingerprint | IdP 값. 인증서에서 SHA256 지문을 생성하는 방법은 지문 계산을 참조하세요. |
| idp_sso_target_url | IdP 값. |
| issuer | IdP에서 애플리케이션을 식별하는 고유한 이름으로 변경하세요. |
| name_identifier_format | IdP 값. |
이 값들에 대한 자세한 내용은 OmniAuth SAML 문서를 참조하세요. 다른 구성 설정에 대한 자세한 내용은 IdP에서 SAML 구성을 참조하세요.
파일을 저장하고 GitLab을 재구성하세요:
sudo gitlab-ctl reconfigure
Helm chart (Kubernetes)
GitLab이 HTTPS로 구성되어 있는지 확인하세요.
공통 설정을 구성하여
saml을 싱글 사인온 프로바이더로 추가하세요. 이렇게 하면 기존 GitLab 계정이 없는
사용자에 대해 Just-In-Time 계정 프로비저닝이 활성화됩니다.
Helm 값을 내보내세요:
helm get values gitlab > gitlab_values.yaml
사용자가 수동으로 계정을 먼저 생성하지 않고 SAML을 사용하여 가입할 수 있도록 하려면
gitlab_values.yaml을 편집하세요:
global:
appConfig:
omniauth:
enabled: true
allowSingleSignOn: ['saml']
blockAutoCreatedUsers: false
선택 사항. gitlab_values.yaml에 다음 설정을 추가하면 이메일 주소가 일치하는 경우 SAML 사용자를 기존 GitLab 사용자와 자동으로 연결할 수 있습니다:
global:
appConfig:
omniauth:
autoLinkSamlUser: true
또는 사용자가 기존 사용자에 대해 OmniAuth 활성화를 통해 SAML 아이덴티티를 기존 GitLab 계정에 수동으로 연결할 수 있습니다.
SAML 사용자가 변경할 수 없도록 다음 속성을 구성하세요.
omniauth_auto_link_saml_user와 함께 사용할 때의Email.
사용자가 이러한 속성을 변경할 수 있으면 다른 인가된 사용자로 로그인할 수 있습니다. 이러한 속성을 변경 불가능하게 만드는 방법은 SAML IdP 문서를 참조하세요.
다음 내용을 saml.yaml 파일에 저장하여 Kubernetes Secret으로 사용하세요:
name: 'saml'
label: 'Provider name' # optional label for login button, defaults to "Saml"
args:
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback'
idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6'
idp_sso_target_url: 'https://login.example.com/idp'
issuer: 'https://gitlab.example.com'
name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent'
| 인수 | 설명 |
|---|---|
| assertion_consumer_service_url | GitLab HTTPS 엔드포인트 (GitLab 설치의 HTTPS URL에 /users/auth/saml/callback 추가). |
| idp_cert_fingerprint | IdP 값. 인증서에서 SHA256 지문을 생성하는 방법은 지문 계산을 참조하세요. |
| idp_sso_target_url | IdP 값. |
| issuer | IdP에서 애플리케이션을 식별하는 고유한 이름으로 변경하세요. |
| name_identifier_format | IdP 값. |
이 값들에 대한 자세한 내용은 OmniAuth SAML 문서를 참조하세요. 다른 구성 설정에 대한 자세한 내용은 IdP에서 SAML 구성을 참조하세요.
Kubernetes Secret을 생성하세요:
kubectl create secret generic -n <namespace> gitlab-saml --from-file=provider=saml.yaml
gitlab_values.yaml을 편집하여 프로바이더 구성을 추가하세요:
global:
appConfig:
omniauth:
providers:
- secret: gitlab-saml
파일을 저장하고 새 값을 적용하세요:
helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
Docker
GitLab이 HTTPS로 구성되어 있는지 확인하세요.
공통 설정을 구성하여
saml을 싱글 사인온 프로바이더로 추가하세요. 이렇게 하면 기존 GitLab 계정이 없는
사용자에 대해 Just-In-Time 계정 프로비저닝이 활성화됩니다.
사용자가 수동으로 계정을 먼저 생성하지 않고 SAML을 사용하여 가입할 수 있도록 하려면
docker-compose.yml을 편집하세요:
version: "3.6"
services:
gitlab:
environment:
GITLAB_OMNIBUS_CONFIG: |
gitlab_rails['omniauth_allow_single_sign_on'] = ['saml']
gitlab_rails['omniauth_block_auto_created_users'] = false
선택 사항. docker-compose.yml에 다음 설정을 추가하면 이메일 주소가 일치하는 경우 SAML 사용자를 기존 GitLab 사용자와 자동으로 연결할 수 있습니다:
version: "3.6"
services:
gitlab:
environment:
GITLAB_OMNIBUS_CONFIG: |
gitlab_rails['omniauth_auto_link_saml_user'] = true
또는 사용자가 기존 사용자에 대해 OmniAuth 활성화를 통해 SAML 아이덴티티를 기존 GitLab 계정에 수동으로 연결할 수 있습니다.
SAML 사용자가 변경할 수 없도록 다음 속성을 구성하세요.
omniauth_auto_link_saml_user와 함께 사용할 때의Email.
사용자가 이러한 속성을 변경할 수 있으면 다른 인가된 사용자로 로그인할 수 있습니다. 이러한 속성을 변경 불가능하게 만드는 방법은 SAML IdP 문서를 참조하세요.
docker-compose.yml을 편집하여 프로바이더 구성을 추가하세요:
version: "3.6"
services:
gitlab:
environment:
GITLAB_OMNIBUS_CONFIG: |
gitlab_rails['omniauth_providers'] = [
{
name: "saml",
label: "Provider name", # optional label for login button, defaults to "Saml"
args: {
assertion_consumer_service_url: "https://gitlab.example.com/users/auth/saml/callback",
idp_cert_fingerprint: "2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6",
idp_sso_target_url: "https://login.example.com/idp",
issuer: "https://gitlab.example.com",
name_identifier_format: "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent"
}
}
]
| 인수 | 설명 |
|---|---|
| assertion_consumer_service_url | GitLab HTTPS 엔드포인트 (GitLab 설치의 HTTPS URL에 /users/auth/saml/callback 추가). |
| idp_cert_fingerprint | IdP 값. 인증서에서 SHA256 지문을 생성하는 방법은 지문 계산을 참조하세요. |
| idp_sso_target_url | IdP 값. |
| issuer | IdP에서 애플리케이션을 식별하는 고유한 이름으로 변경하세요. |
| name_identifier_format | IdP 값. |
이 값들에 대한 자세한 내용은 OmniAuth SAML 문서를 참조하세요. 다른 구성 설정에 대한 자세한 내용은 IdP에서 SAML 구성을 참조하세요.
파일을 저장하고 GitLab을 재시작하세요:
docker compose up -d
Self-compiled (source)
GitLab이 HTTPS로 구성되어 있는지 확인하세요.
공통 설정을 구성하여
saml을 싱글 사인온 프로바이더로 추가하세요. 이렇게 하면 기존 GitLab 계정이 없는
사용자에 대해 Just-In-Time 계정 프로비저닝이 활성화됩니다.
사용자가 수동으로 계정을 먼저 생성하지 않고 SAML을 사용하여 가입할 수 있도록 하려면
/home/git/gitlab/config/gitlab.yml을 편집하세요:
production: &base
omniauth:
enabled: true
allow_single_sign_on: ["saml"]
block_auto_created_users: false
선택 사항. /home/git/gitlab/config/gitlab.yml에 다음 설정을 추가하면 이메일 주소가 일치하는 경우 SAML 사용자를 기존 GitLab 사용자와 자동으로 연결할 수 있습니다:
production: &base
omniauth:
auto_link_saml_user: true
또는 사용자가 기존 사용자에 대해 OmniAuth 활성화를 통해 SAML 아이덴티티를 기존 GitLab 계정에 수동으로 연결할 수 있습니다.
SAML 사용자가 변경할 수 없도록 다음 속성을 구성하세요.
omniauth_auto_link_saml_user와 함께 사용할 때의Email.
사용자가 이러한 속성을 변경할 수 있으면 다른 인가된 사용자로 로그인할 수 있습니다. 이러한 속성을 변경 불가능하게 만드는 방법은 SAML IdP 문서를 참조하세요.
/home/git/gitlab/config/gitlab.yml을 편집하여 프로바이더 구성을 추가하세요:
omniauth:
providers:
- {
name: 'saml',
label: 'Provider name', # optional label for login button, defaults to "Saml"
args: {
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
idp_sso_target_url: 'https://login.example.com/idp',
issuer: 'https://gitlab.example.com',
name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent'
}
}
| 인수 | 설명 |
|---|---|
| assertion_consumer_service_url | GitLab HTTPS 엔드포인트 (GitLab 설치의 HTTPS URL에 /users/auth/saml/callback 추가). |
| idp_cert_fingerprint | IdP 값. 인증서에서 SHA256 지문을 생성하는 방법은 지문 계산을 참조하세요. |
| idp_sso_target_url | IdP 값. |
| issuer | IdP에서 애플리케이션을 식별하는 고유한 이름으로 변경하세요. |
| name_identifier_format | IdP 값. |
이 값들에 대한 자세한 내용은 OmniAuth SAML 문서를 참조하세요. 다른 구성 설정에 대한 자세한 내용은 IdP에서 SAML 구성을 참조하세요.
파일을 저장하고 GitLab을 재시작하세요:
# For systems running systemd
sudo systemctl restart gitlab.target
# For systems running SysV init
sudo service gitlab restart
SAML IdP에 GitLab 등록#
issuer에 지정한 애플리케이션 이름을 사용하여 SAML IdP에 GitLab SP를 등록하세요.
IdP에 구성 정보를 제공하려면 애플리케이션의 메타데이터 URL을 만드세요. GitLab의 메타데이터 URL을 만들려면 GitLab 설치의 HTTPS URL에 users/auth/saml/metadata를 추가하세요. 예를 들면 다음과 같습니다:
https://gitlab.example.com/users/auth/saml/metadata
IdP는 최소한 email 또는 mail을 사용하여 사용자의 이메일 주소가 포함된 클레임을 반드시 제공해야 합니다. 다른 사용 가능한 클레임에 대한 자세한 내용은 어설션 구성을 참조하세요.
이제 로그인 페이지에서 일반 로그인 폼 아래에 SAML 아이콘이 표시됩니다. 해당 아이콘을 선택하여 인증 프로세스를 시작하세요. 인증에 성공하면 GitLab으로 돌아와 로그인됩니다.
IdP에서 SAML 구성#
IdP에서 SAML 애플리케이션을 구성하려면 최소한 다음 정보가 필요합니다.
-
Assertion consumer service URL (어설션 컨슈머 서비스 URL).
-
Issuer (발급자).
구성 예시는 아이덴티티 프로바이더 설정을 참조하세요.
IdP에 추가 구성이 필요할 수 있습니다. 자세한 내용은 IdP의 SAML 앱에 대한 추가 구성을 참조하세요.
여러 SAML IdP를 사용하도록 GitLab 구성#
다음 조건을 충족하는 경우 GitLab에서 여러 SAML IdP를 사용하도록 구성할 수 있습니다.
-
각 프로바이더에
args에 설정된 이름과 일치하는 고유한 이름이 설정되어 있어야 합니다. -
프로바이더 이름은 다음 용도로 사용됩니다.
프로바이더 이름을 기반으로 한 속성에 대한 OmniAuth 구성. 예를 들어,
allowBypassTwoFactor, allowSingleSignOn, syncProfileFromProvider.
-
추가 아이덴티티로서 각 기존 사용자와의 연결.
-
assertion_consumer_service_url이 프로바이더 이름과 일치해야 합니다. -
strategy_class는 프로바이더 이름에서 추론할 수 없으므로 명시적으로 설정해야 합니다.여러 SAML IdP를 구성할 때 SAML 그룹 링크가 작동하도록 하려면 모든 SAML IdP가 SAML 응답에 그룹 속성을 포함하도록 구성해야 합니다. 자세한 내용은 SAML 그룹 링크를 참조하세요.
여러 SAML IdP를 설정하려면 다음을 수행하세요:
Linux package (Omnibus)
/etc/gitlab/gitlab.rb를 편집하세요:
gitlab_rails['omniauth_providers'] = [
{
name: 'saml', # This must match the following name configuration parameter
label: 'Provider 1' # Differentiate the two buttons and providers in the UI
args: {
name: 'saml', # This is mandatory and must match the provider name
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', # URL must match the name of the provider
strategy_class: 'OmniAuth::Strategies::SAML',
# Include all required arguments similar to a single provider
},
},
{
name: 'saml_2', # This must match the following name configuration parameter
label: 'Provider 2' # Differentiate the two buttons and providers in the UI
args: {
name: 'saml_2', # This is mandatory and must match the provider name
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml_2/callback', # URL must match the name of the provider
strategy_class: 'OmniAuth::Strategies::SAML',
# Include all required arguments similar to a single provider
},
}
]
어느 프로바이더에서든 사용자가 수동으로 계정을 먼저 생성하지 않고 SAML을 사용하여 가입할 수 있도록 하려면 구성에 다음 값을 추가하세요:
gitlab_rails['omniauth_allow_single_sign_on'] = ['saml', 'saml_2']
파일을 저장하고 GitLab을 재구성하세요:
sudo gitlab-ctl reconfigure
Helm chart (Kubernetes)
다음 내용을 saml.yaml 파일에 저장하여 첫 번째 SAML 프로바이더에 대한
Kubernetes Secret으로 사용하세요:
name: 'saml' # At least one provider must be named 'saml'
label: 'Provider 1' # Differentiate the two buttons and providers in the UI
args:
name: 'saml' # This is mandatory and must match the provider name
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback' # URL must match the name of the provider
strategy_class: 'OmniAuth::Strategies::SAML' # Mandatory
# Include all required arguments similar to a single provider
다음 내용을 saml_2.yaml 파일에 저장하여 두 번째 SAML 프로바이더에 대한
Kubernetes Secret으로 사용하세요:
name: 'saml_2'
label: 'Provider 2' # Differentiate the two buttons and providers in the UI
args:
name: 'saml_2' # This is mandatory and must match the provider name
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml_2/callback' # URL must match the name of the provider
strategy_class: 'OmniAuth::Strategies::SAML' # Mandatory
# Include all required arguments similar to a single provider
선택 사항. 같은 단계를 따라 추가 SAML 프로바이더를 설정하세요.
Kubernetes Secret을 생성하세요:
kubectl create secret generic -n <namespace> gitlab-saml \
--from-file=saml=saml.yaml \
--from-file=saml_2=saml_2.yaml
Helm 값을 내보내세요:
helm get values gitlab > gitlab_values.yaml
gitlab_values.yaml를 편집하세요:
global:
appConfig:
omniauth:
providers:
- secret: gitlab-saml
key: saml
- secret: gitlab-saml
key: saml_2
어느 프로바이더에서든 사용자가 수동으로 계정을 먼저 생성하지 않고 SAML을 사용하여 가입할 수 있도록 하려면 구성에 다음 값을 추가하세요:
global:
appConfig:
omniauth:
allowSingleSignOn: ['saml', 'saml_2']
파일을 저장하고 새 값을 적용하세요:
helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
Docker
docker-compose.yml을 편집하세요:
version: "3.6"
services:
gitlab:
environment:
GITLAB_OMNIBUS_CONFIG: |
gitlab_rails['omniauth_allow_single_sign_on'] = ['saml', 'saml1']
gitlab_rails['omniauth_providers'] = [
{
name: 'saml', # This must match the following name configuration parameter
label: 'Provider 1' # Differentiate the two buttons and providers in the UI
args: {
name: 'saml', # This is mandatory and must match the provider name
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', # URL must match the name of the provider
strategy_class: 'OmniAuth::Strategies::SAML',
# Include all required arguments similar to a single provider
},
},
{
name: 'saml_2', # This must match the following name configuration parameter
label: 'Provider 2' # Differentiate the two buttons and providers in the UI
args: {
name: 'saml_2', # This is mandatory and must match the provider name
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml_2/callback', # URL must match the name of the provider
strategy_class: 'OmniAuth::Strategies::SAML',
# Include all required arguments similar to a single provider
},
}
]
어느 프로바이더에서든 사용자가 수동으로 계정을 먼저 생성하지 않고 SAML을 사용하여 가입할 수 있도록 하려면 구성에 다음 값을 추가하세요:
version: "3.6"
services:
gitlab:
environment:
GITLAB_OMNIBUS_CONFIG: |
gitlab_rails['omniauth_allow_single_sign_on'] = ['saml', 'saml_2']
파일을 저장하고 GitLab을 재시작하세요:
docker compose up -d
Self-compiled (source)
/home/git/gitlab/config/gitlab.yml을 편집하세요:
production: &base
omniauth:
providers:
- {
name: 'saml', # This must match the following name configuration parameter
label: 'Provider 1' # Differentiate the two buttons and providers in the UI
args: {
name: 'saml', # This is mandatory and must match the provider name
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', # URL must match the name of the provider
strategy_class: 'OmniAuth::Strategies::SAML',
# Include all required arguments similar to a single provider
},
}
- {
name: 'saml_2', # This must match the following name configuration parameter
label: 'Provider 2' # Differentiate the two buttons and providers in the UI
args: {
name: 'saml_2', # This is mandatory and must match the provider name
strategy_class: 'OmniAuth::Strategies::SAML',
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml_2/callback', # URL must match the name of the provider
# Include all required arguments similar to a single provider
},
}
어느 프로바이더에서든 사용자가 수동으로 계정을 먼저 생성하지 않고 SAML을 사용하여 가입할 수 있도록 하려면 구성에 다음 값을 추가하세요:
production: &base
omniauth:
allow_single_sign_on: ["saml", "saml_2"]
파일을 저장하고 GitLab을 재시작하세요:
# For systems running systemd
sudo systemctl restart gitlab.target
# For systems running SysV init
sudo service gitlab restart
아이덴티티 프로바이더 설정#
GitLab의 SAML 지원을 통해 다양한 IdP로 GitLab에 로그인할 수 있습니다.
GitLab은 Okta 및 Google Workspace IdP 설정에 관한 다음 내용을 참고용으로만 제공합니다. 이러한 IdP 구성에 관해 질문이 있으면 해당 프로바이더의 지원팀에 문의하세요.
Okta 설정#
-
Okta 관리자 섹션에서 Applications을 선택하세요.
-
앱 화면에서 Create App Integration을 선택하고 다음 화면에서 SAML 2.0을 선택하세요.
-
선택 사항. GitLab Press에서 로고를 선택하여 추가하세요. 로고를 자르고 크기를 조정해야 합니다.
-
SAML 일반 구성을 완료하세요. 다음을 입력하세요.
"Single sign-on URL": Assertion consumer service URL을 사용하세요.
-
"Audience URI": Issuer를 사용하세요. -
어설션.
-
피드백 섹션에서 고객이며 내부 사용을 위한 앱을 만들고 있다고 입력하세요.
-
새 앱 프로필 상단에서 SAML 2.0 configuration instructions을 선택하세요.
-
Identity Provider Single Sign-On URL을 메모하세요. GitLab 구성 파일의
idp_sso_target_url에 이 URL을 사용하세요. -
Okta에서 로그아웃하기 전에 사용자와 그룹이 있는 경우 추가했는지 확인하세요.
Google Workspace 설정#
사전 요구 사항:
- Google Workspace 슈퍼 관리자 계정에 대한 액세스 권한이 있는지 확인하세요.
Google Workspace를 설정하려면 다음을 수행하세요.
다음 정보를 참고하고, Google Workspace에서 사용자 지정 SAML 애플리케이션 설정의 지침을 따르세요.
| 일반적인 값 | 설명 | |
|---|---|---|
| Name of SAML App | GitLab | 다른 이름도 사용 가능합니다. |
| ACS URL | https:///users/auth/saml/callback | Assertion Consumer Service URL. |
| GITLAB_DOMAIN | gitlab.example.com | GitLab 인스턴스 도메인. |
| Entity ID | https://gitlab.example.com | SAML 애플리케이션에 고유한 값. GitLab 구성의 issuer로 설정하세요. |
| Name ID format | 필수 값. name_identifier_format이라고도 합니다. | |
| Name ID | Primary email address | 이메일 주소. 해당 주소로 전송된 콘텐츠를 수신하는 사람이 있는지 확인하세요. |
| First name | first_name | 이름. GitLab과 통신하기 위해 필요한 값. |
| Last name | last_name | 성. GitLab과 통신하기 위해 필요한 값. |
다음 SAML 속성 매핑을 설정하세요.
| Google 디렉터리 속성 | 앱 속성 |
|---|---|
| Basic information > Email | |
| Basic Information > First name | first_name |
| Basic Information > Last name | last_name |
GitLab에서 SAML 지원 구성 시 이 정보의 일부를 사용할 수 있습니다.
Google Workspace SAML 애플리케이션을 구성할 때 다음 정보를 기록하세요.
| 값 | 설명 | |
|---|---|---|
| SSO URL | 설치에 따라 다름 | Google 아이덴티티 프로바이더 세부 정보. GitLab idp_sso_target_url 설정으로 지정하세요. |
| Certificate | 다운로드 가능 | Google SAML 인증서. |
| SHA256 fingerprint | 설치에 따라 다름 | 인증서를 다운로드할 때 확인 가능. 인증서에서 SHA256 지문을 생성하는 방법은 지문 계산을 참조하세요. |
Google Workspace 관리자는 IdP 메타데이터, Entity ID 및 SHA-256 지문도 제공합니다. 그러나 GitLab은 Google Workspace SAML 애플리케이션에 연결하기 위해 이 정보가 필요하지 않습니다.
Microsoft Entra ID 설정#
Microsoft Entra 관리 센터에 로그인하세요.
gitlab.rb 파일의 다음 설정이 Microsoft Entra ID 필드에 해당합니다.
| gitlab.rb 설정 | Microsoft Entra ID 필드 |
|---|---|
| issuer | Identifier (Entity ID) |
| assertion_consumer_service_url | Reply URL (Assertion Consumer Service URL) |
| idp_sso_target_url | Login URL |
| idp_cert_fingerprint | Thumbprint |
다음 속성을 설정하세요.
**Unique User Identifier (Name ID)**를 user.objectID로 설정하세요.
Name identifier format을 persistent로 설정하세요. 자세한 내용은 사용자 SAML 아이덴티티 관리 방법을 참조하세요.
- Additional claims를 지원되는 속성으로 설정하세요.
자세한 내용은 구성 예시 페이지를 참조하세요.
기타 IdP 설정#
일부 IdP에는 SAML 구성에서 해당 IdP를 사용하는 방법에 대한 문서가 있습니다. 예를 들면 다음과 같습니다.
SAML 구성에서 IdP 구성에 관해 질문이 있으면 해당 프로바이더의 지원팀에 문의하세요.
어설션 구성#
-
Offering: GitLab.com, GitLab Self-Managed
History
-
Microsoft Azure/Entra ID 속성 지원이 GitLab 16.7에서 도입되었습니다.
이러한 속성은 대소문자를 구분합니다.
| 필드 | 지원되는 기본 키 |
|---|---|
| Email (필수) | email, mail, http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress, http://schemas.microsoft.com/ws/2008/06/identity/claims/emailaddress, http://schemas.xmlsoap.org/ws/2005/05/identity/claims/email, http://schemas.microsoft.com/ws/2008/06/identity/claims/email, urn:oid:0.9.2342.19200300.100.1.3 |
| Full Name | name, http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name, http://schemas.microsoft.com/ws/2008/06/identity/claims/name, urn:oid:2.16.840.1.113730.3.1.241, urn:oid:2.5.4.3 |
| First Name | first_name, firstname, firstName, http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname, http://schemas.microsoft.com/ws/2008/06/identity/claims/givenname, urn:oid:2.5.4.42 |
| Last Name | last_name, lastname, lastName, http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname, http://schemas.microsoft.com/ws/2008/06/identity/claims/surname, urn:oid:2.5.4.4 |
GitLab이 SAML SSO 프로바이더로부터 SAML 응답을 받으면, GitLab은 속성 name 필드에서 다음 값을 찾습니다:
-
"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname" -
"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname" -
"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress" -
firstname -
lastname -
email
GitLab이 SAML 응답을 파싱할 수 있도록 속성 Name 필드에 이러한 값을 올바르게 포함해야 합니다. 예를 들어 GitLab은 다음 SAML 응답 스니펫을 파싱할 수 있습니다.
이전 테이블의 필수 값 중 하나로 Name 속성이 설정되어 있어 허용됩니다.
Alvin</AttributeValue>
</Attribute>
Test</AttributeValue>
</Attribute>
alvintest@example.com</AttributeValue>
</Attribute>
이전 테이블의 값 중 하나와 Name 속성이 일치하여 허용됩니다.
Alvin</AttributeValue>
</Attribute>
Test</AttributeValue>
</Attribute>
alvintest@example.com</AttributeValue>
</Attribute>
그러나 GitLab은 다음 SAML 응답 스니펫을 파싱할 수 없습니다.
Name 속성의 값이 이전 테이블에서 지원되는 값 중 하나가 아니므로 허용되지 않습니다.
Alvin</AttributeValue>
</Attribute>
Test</AttributeValue>
</Attribute>
alvintest@example.com</AttributeValue>
</Attribute>
FriendlyName에 지원되는 값이 있어도 Name 속성에 없으므로 실패합니다.
Alvin</AttributeValue>
</Attribute>
Test</AttributeValue>
</Attribute>
alvintest@example.com</AttributeValue>
</Attribute>
다음 내용은 attribute_statements를 참조하세요.
-
사용자 정의 어설션 구성 예시.
-
사용자 정의 사용자 이름 속성 구성 방법.
지원되는 어설션의 전체 목록은 OmniAuth SAML gem을 참조하세요.
SAML 그룹 멤버십을 기반으로 사용자 구성#
다음을 수행할 수 있습니다.
GitLab은 각 SAML 로그인 시 이러한 그룹을 확인하고 필요에 따라 사용자 속성을 업데이트합니다. 이 기능은 사용자를 GitLab 그룹에 자동으로 추가하는 것을 허용하지 않습니다.
이러한 그룹에 대한 지원은 다음에 따라 다릅니다.
-
구독.
| 그룹 | 티어 | GitLab Enterprise Edition (EE) 전용? |
|---|---|---|
| Required | Free, Premium, Ultimate | Yes |
| External | Free, Premium, Ultimate | No |
| Admin | Free, Premium, Ultimate | Yes |
| Auditor | Premium, Ultimate | Yes |
사전 요구 사항:
GitLab에 그룹 정보를 찾을 위치를 알려야 합니다. 이를 위해
IdP 서버가 일반 SAML 응답과 함께 특정 AttributeStatement를 보내는지 확인하세요. 예를 들면 다음과 같습니다:
<saml:AttributeStatement>
<saml:Attribute Name="Groups">
<saml:AttributeValue xsi:type="xs:string">Developers</saml:AttributeValue>
<saml:AttributeValue xsi:type="xs:string">Freelancers</saml:AttributeValue>
<saml:AttributeValue xsi:type="xs:string">Admins</saml:AttributeValue>
<saml:AttributeValue xsi:type="xs:string">Auditors</saml:AttributeValue>
</saml:Attribute>
</saml:AttributeStatement>
속성의 이름에는 사용자가 속한 그룹이 포함되어야 합니다.
GitLab에 이러한 그룹을 찾을 위치를 알려주려면 SAML 설정에 groups_attribute:
요소를 추가하세요. 이 속성은 대소문자를 구분합니다.
필수 그룹#
IdP는 SAML 응답에서 GitLab에 그룹 정보를 전달합니다. 이 응답을 사용하려면 GitLab이 다음을 식별하도록 구성하세요.
-
groups_attribute설정을 사용하여 SAML 응답에서 그룹을 찾을 위치. -
그룹 설정을 사용하여 그룹 또는 사용자에 대한 정보.
required_groups 설정을 사용하여 로그인에 필요한 그룹 멤버십을 GitLab이 식별하도록 구성하세요.
required_groups를 설정하지 않거나 비워 두면 적절한 인증을 가진 모든 사람이 서비스를 사용할 수 있습니다.
groups_attribute에 지정된 속성이 올바르지 않거나 누락된 경우 모든 사용자가 차단됩니다.
Linux package (Omnibus)
/etc/gitlab/gitlab.rb를 편집하세요:
gitlab_rails['omniauth_providers'] = [
{ name: 'saml',
label: 'Our SAML Provider',
groups_attribute: 'Groups',
required_groups: ['Developers', 'Freelancers', 'Admins', 'Auditors'],
args: {
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
idp_sso_target_url: 'https://login.example.com/idp',
issuer: 'https://gitlab.example.com',
name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent'
}
}
]
파일을 저장하고 GitLab을 재구성하세요:
sudo gitlab-ctl reconfigure
Helm chart (Kubernetes)
다음 내용을 Kubernetes Secret으로 사용할 saml.yaml 파일에 저장하세요:
name: 'saml'
label: 'Our SAML Provider'
groups_attribute: 'Groups'
required_groups: ['Developers', 'Freelancers', 'Admins', 'Auditors']
args:
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback'
idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6'
idp_sso_target_url: 'https://login.example.com/idp'
issuer: 'https://gitlab.example.com'
name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent'
Kubernetes Secret을 생성하세요:
kubectl create secret generic -n <namespace> gitlab-saml --from-file=provider=saml.yaml
Helm 값을 내보내세요:
helm get values gitlab > gitlab_values.yaml
gitlab_values.yaml를 편집하세요:
global:
appConfig:
omniauth:
providers:
- secret: gitlab-saml
파일을 저장하고 새 값을 적용하세요:
helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
Docker
docker-compose.yml을 편집하세요:
version: "3.6"
services:
gitlab:
environment:
GITLAB_OMNIBUS_CONFIG: |
gitlab_rails['omniauth_providers'] = [
{ name: 'saml',
label: 'Our SAML Provider',
groups_attribute: 'Groups',
required_groups: ['Developers', 'Freelancers', 'Admins', 'Auditors'],
args: {
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
idp_sso_target_url: 'https://login.example.com/idp',
issuer: 'https://gitlab.example.com',
name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent'
}
}
]
파일을 저장하고 GitLab을 재시작하세요:
docker compose up -d
Self-compiled (source)
/home/git/gitlab/config/gitlab.yml을 편집하세요:
production: &base
omniauth:
providers:
- { name: 'saml',
label: 'Our SAML Provider',
groups_attribute: 'Groups',
required_groups: ['Developers', 'Freelancers', 'Admins', 'Auditors'],
args: {
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
idp_sso_target_url: 'https://login.example.com/idp',
issuer: 'https://gitlab.example.com',
name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent'
}
}
파일을 저장하고 GitLab을 재시작하세요:
# For systems running systemd
sudo systemctl restart gitlab.target
# For systems running SysV init
sudo service gitlab restart
외부 그룹#
IdP는 SAML 응답에서 GitLab에 그룹 정보를 전달합니다. 이 응답을 사용하려면 GitLab이 다음을 식별하도록 구성하세요.
-
groups_attribute설정을 사용하여 SAML 응답에서 그룹을 찾을 위치. -
그룹 설정을 사용하여 그룹 또는 사용자에 대한 정보.
SAML은 external_groups 설정을 기반으로 사용자를 외부 사용자로 자동 식별할 수 있습니다.
`groups_attribute`에 지정된 속성이 올바르지 않거나 누락된 경우 사용자는 일반 사용자로 액세스합니다.
구성 예시:
Linux package (Omnibus)
/etc/gitlab/gitlab.rb를 편집하세요:
gitlab_rails['omniauth_providers'] = [
{ name: 'saml',
label: 'Our SAML Provider',
groups_attribute: 'Groups',
external_groups: ['Freelancers'],
args: {
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
# or
# idp_cert: '-----BEGIN CERTIFICATE-----\n ... \n-----END CERTIFICATE-----',
idp_sso_target_url: 'https://login.example.com/idp',
issuer: 'https://gitlab.example.com',
name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent'
}
}
]
파일을 저장하고 GitLab을 재구성하세요:
sudo gitlab-ctl reconfigure
Helm chart (Kubernetes)
다음 내용을 Kubernetes Secret으로 사용할 saml.yaml 파일에 저장하세요:
name: 'saml'
label: 'Our SAML Provider'
groups_attribute: 'Groups'
external_groups: ['Freelancers']
args:
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback'
idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6'
# or
# idp_cert: '-----BEGIN CERTIFICATE-----\n ... \n-----END CERTIFICATE-----',
idp_sso_target_url: 'https://login.example.com/idp'
issuer: 'https://gitlab.example.com'
name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent'
Kubernetes Secret을 생성하세요:
kubectl create secret generic -n <namespace> gitlab-saml --from-file=provider=saml.yaml
Helm 값을 내보내세요:
helm get values gitlab > gitlab_values.yaml
gitlab_values.yaml를 편집하세요:
global:
appConfig:
omniauth:
providers:
- secret: gitlab-saml
파일을 저장하고 새 값을 적용하세요:
helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
Docker
docker-compose.yml을 편집하세요:
version: "3.6"
services:
gitlab:
environment:
GITLAB_OMNIBUS_CONFIG: |
gitlab_rails['omniauth_providers'] = [
{ name: 'saml',
label: 'Our SAML Provider',
groups_attribute: 'Groups',
external_groups: ['Freelancers'],
args: {
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
idp_sso_target_url: 'https://login.example.com/idp',
issuer: 'https://gitlab.example.com',
name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent'
}
}
]
파일을 저장하고 GitLab을 재시작하세요:
docker compose up -d
Self-compiled (source)
/home/git/gitlab/config/gitlab.yml을 편집하세요:
production: &base
omniauth:
providers:
- { name: 'saml',
label: 'Our SAML Provider',
groups_attribute: 'Groups',
external_groups: ['Freelancers'],
args: {
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
idp_sso_target_url: 'https://login.example.com/idp',
issuer: 'https://gitlab.example.com',
name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent'
}
}
파일을 저장하고 GitLab을 재시작하세요:
# For systems running systemd
sudo systemctl restart gitlab.target
# For systems running SysV init
sudo service gitlab restart
관리자 그룹#
IdP는 SAML 응답에서 GitLab에 그룹 정보를 전달합니다. 이 응답을 사용하려면 GitLab이 다음을 식별하도록 구성하세요.
-
groups_attribute설정을 사용하여 SAML 응답에서 그룹을 찾을 위치. -
그룹 설정을 사용하여 그룹 또는 사용자에 대한 정보.
admin_groups 설정을 사용하여 사용자에게 관리자 액세스 권한을 부여하는 그룹을 GitLab이 식별하도록 구성하세요.
groups_attribute에 지정된 속성이 올바르지 않거나 누락된 경우 사용자는 관리자 액세스 권한을 잃게 됩니다.
구성 예시:
Linux package (Omnibus)
/etc/gitlab/gitlab.rb를 편집하세요:
gitlab_rails['omniauth_providers'] = [
{ name: 'saml',
label: 'Our SAML Provider',
groups_attribute: 'Groups',
admin_groups: ['Admins'],
args: {
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
# or
# idp_cert: '-----BEGIN CERTIFICATE-----\n ... \n-----END CERTIFICATE-----',
idp_sso_target_url: 'https://login.example.com/idp',
issuer: 'https://gitlab.example.com',
name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent'
}
}
]
파일을 저장하고 GitLab을 재구성하세요:
sudo gitlab-ctl reconfigure
Helm chart (Kubernetes)
다음 내용을 Kubernetes Secret으로 사용할 saml.yaml 파일에 저장하세요:
name: 'saml'
label: 'Our SAML Provider'
groups_attribute: 'Groups'
admin_groups: ['Admins']
args:
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback'
idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6'
idp_sso_target_url: 'https://login.example.com/idp'
issuer: 'https://gitlab.example.com'
name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent'
Kubernetes Secret을 생성하세요:
kubectl create secret generic -n <namespace> gitlab-saml --from-file=provider=saml.yaml
Helm 값을 내보내세요:
helm get values gitlab > gitlab_values.yaml
gitlab_values.yaml를 편집하세요:
global:
appConfig:
omniauth:
providers:
- secret: gitlab-saml
파일을 저장하고 새 값을 적용하세요:
helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
Docker
docker-compose.yml을 편집하세요:
version: "3.6"
services:
gitlab:
environment:
GITLAB_OMNIBUS_CONFIG: |
gitlab_rails['omniauth_providers'] = [
{ name: 'saml',
label: 'Our SAML Provider',
groups_attribute: 'Groups',
admin_groups: ['Admins'],
args: {
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
idp_sso_target_url: 'https://login.example.com/idp',
issuer: 'https://gitlab.example.com',
name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent'
}
}
]
파일을 저장하고 GitLab을 재시작하세요:
docker compose up -d
Self-compiled (source)
/home/git/gitlab/config/gitlab.yml을 편집하세요:
production: &base
omniauth:
providers:
- { name: 'saml',
label: 'Our SAML Provider',
groups_attribute: 'Groups',
admin_groups: ['Admins'],
args: {
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
idp_sso_target_url: 'https://login.example.com/idp',
issuer: 'https://gitlab.example.com',
name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent'
}
}
파일을 저장하고 GitLab을 재시작하세요:
# For systems running systemd
sudo systemctl restart gitlab.target
# For systems running SysV init
sudo service gitlab restart
감사자 그룹#
IdP는 SAML 응답에서 GitLab에 그룹 정보를 전달합니다. 이 응답을 사용하려면 GitLab이 다음을 식별하도록 구성하세요.
-
groups_attribute설정을 사용하여 SAML 응답에서 그룹을 찾을 위치. -
그룹 설정을 사용하여 그룹 또는 사용자에 대한 정보.
auditor_groups 설정을 사용하여 감사자 액세스 권한을 가진 사용자가 포함된 그룹을 GitLab이 식별하도록 구성하세요.
groups_attribute에 지정된 속성이 올바르지 않거나 누락된 경우 사용자는 감사자 액세스 권한을 잃게 됩니다.
구성 예시:
Linux package (Omnibus)
/etc/gitlab/gitlab.rb를 편집하세요:
gitlab_rails['omniauth_providers'] = [
{ name: 'saml',
label: 'Our SAML Provider',
groups_attribute: 'Groups',
auditor_groups: ['Auditors'],
args: {
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
idp_sso_target_url: 'https://login.example.com/idp',
issuer: 'https://gitlab.example.com',
name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent'
}
}
]
파일을 저장하고 GitLab을 재구성하세요:
sudo gitlab-ctl reconfigure
Helm chart (Kubernetes)
다음 내용을 Kubernetes Secret으로 사용할 saml.yaml 파일에 저장하세요:
name: 'saml'
label: 'Our SAML Provider'
groups_attribute: 'Groups'
auditor_groups: ['Auditors']
args:
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback'
idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6'
idp_sso_target_url: 'https://login.example.com/idp'
issuer: 'https://gitlab.example.com'
name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent'
Kubernetes Secret을 생성하세요:
kubectl create secret generic -n <namespace> gitlab-saml --from-file=provider=saml.yaml
Helm 값을 내보내세요:
helm get values gitlab > gitlab_values.yaml
gitlab_values.yaml를 편집하세요:
global:
appConfig:
omniauth:
providers:
- secret: gitlab-saml
파일을 저장하고 새 값을 적용하세요:
helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
Docker
docker-compose.yml을 편집하세요:
version: "3.6"
services:
gitlab:
environment:
GITLAB_OMNIBUS_CONFIG: |
gitlab_rails['omniauth_providers'] = [
{ name: 'saml',
label: 'Our SAML Provider',
groups_attribute: 'Groups',
auditor_groups: ['Auditors'],
args: {
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
idp_sso_target_url: 'https://login.example.com/idp',
issuer: 'https://gitlab.example.com',
name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent'
}
}
]
파일을 저장하고 GitLab을 재시작하세요:
docker compose up -d
Self-compiled (source)
/home/git/gitlab/config/gitlab.yml을 편집하세요:
production: &base
omniauth:
providers:
- { name: 'saml',
label: 'Our SAML Provider',
groups_attribute: 'Groups',
auditor_groups: ['Auditors'],
args: {
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
idp_sso_target_url: 'https://login.example.com/idp',
issuer: 'https://gitlab.example.com',
name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent'
}
}
파일을 저장하고 GitLab을 재시작하세요:
# For systems running systemd
sudo systemctl restart gitlab.target
# For systems running SysV init
sudo service gitlab restart
SAML 그룹 동기화 자동 관리#
GitLab 그룹 멤버십을 자동으로 관리하는 방법에 대한 자세한 내용은 SAML 그룹 동기화를 참조하세요.
SAML 세션 타임아웃 사용자 정의#
History
기본적으로 GitLab은 24시간 후 SAML 세션을 종료합니다. SAML2 AuthnStatement의 SessionNotOnOrAfter 속성으로 이 기간을 사용자 정의할 수 있습니다. 이 속성에는 사용자 세션을 종료할 시기를 나타내는 ISO 8601 타임스탬프 값이 포함됩니다. 지정된 경우 이 값은 기본 SAML 세션 타임아웃 24시간을 재정의합니다.
인스턴스에 SessionNotOnOrAfter 타임스탬프보다 이전인 사용자 정의 세션 기간이 구성된 경우 사용자는 GitLab 사용자 세션이 종료될 때 다시 인증해야 합니다.
이중 인증 우회#
History
-
2FA 적용 우회가 GitLab 16.1에서
by_pass_two_factor_current_session플래그와 함께 도입되었습니다. -
GitLab 17.8에서 활성화되었습니다.
세션별로 SAML 인증 방법이 이중 인증(2FA)으로 간주되도록 구성하려면 upstream_two_factor_authn_contexts 목록에 해당 방법을 등록하세요.
IdP가 AuthnContext를 반환하는지 확인하세요. 예를 들면 다음과 같습니다:
<saml:AuthnStatement>
<saml:AuthnContext>
<saml:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:MediumStrongCertificateProtectedTransport</saml:AuthnContextClassRef>
</saml:AuthnContext>
</saml:AuthnStatement>
설치 구성을 편집하여 upstream_two_factor_authn_contexts 목록에 SAML 인증 방법을 등록하세요. SAML 응답의 AuthnContext를 입력해야 합니다.
Linux package (Omnibus)
/etc/gitlab/gitlab.rb를 편집하세요:
gitlab_rails['omniauth_providers'] = [
{ name: 'saml',
label: 'Our SAML Provider',
args: {
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
idp_sso_target_url: 'https://login.example.com/idp',
issuer: 'https://gitlab.example.com',
name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent',
upstream_two_factor_authn_contexts:
%w(
urn:oasis:names:tc:SAML:2.0:ac:classes:CertificateProtectedTransport
urn:oasis:names:tc:SAML:2.0:ac:classes:SecondFactorOTPSMS
urn:oasis:names:tc:SAML:2.0:ac:classes:SecondFactorIGTOKEN
),
}
}
]
파일을 저장하고 GitLab을 재구성하세요:
sudo gitlab-ctl reconfigure
Helm chart (Kubernetes)
다음 내용을 Kubernetes Secret으로 사용할 saml.yaml 파일에 저장하세요:
name: 'saml'
label: 'Our SAML Provider'
args:
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback'
idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6'
idp_sso_target_url: 'https://login.example.com/idp'
issuer: 'https://gitlab.example.com'
name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent'
upstream_two_factor_authn_contexts:
- 'urn:oasis:names:tc:SAML:2.0:ac:classes:CertificateProtectedTransport'
- 'urn:oasis:names:tc:SAML:2.0:ac:classes:SecondFactorOTPSMS'
- 'urn:oasis:names:tc:SAML:2.0:ac:classes:SecondFactorIGTOKEN'
Kubernetes Secret을 생성하세요:
kubectl create secret generic -n <namespace> gitlab-saml --from-file=provider=saml.yaml
Helm 값을 내보내세요:
helm get values gitlab > gitlab_values.yaml
gitlab_values.yaml를 편집하세요:
global:
appConfig:
omniauth:
providers:
- secret: gitlab-saml
파일을 저장하고 새 값을 적용하세요:
helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
Docker
docker-compose.yml을 편집하세요:
version: "3.6"
services:
gitlab:
environment:
GITLAB_OMNIBUS_CONFIG: |
gitlab_rails['omniauth_providers'] = [
{ name: 'saml',
label: 'Our SAML Provider',
args: {
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
idp_sso_target_url: 'https://login.example.com/idp',
issuer: 'https://gitlab.example.com',
name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent'
upstream_two_factor_authn_contexts:
%w(
urn:oasis:names:tc:SAML:2.0:ac:classes:CertificateProtectedTransport
urn:oasis:names:tc:SAML:2.0:ac:classes:SecondFactorOTPSMS
urn:oasis:names:tc:SAML:2.0:ac:classes:SecondFactorIGTOKEN
)
}
}
]
파일을 저장하고 GitLab을 재시작하세요:
docker compose up -d
Self-compiled (source)
/home/git/gitlab/config/gitlab.yml을 편집하세요:
production: &base
omniauth:
providers:
- { name: 'saml',
label: 'Our SAML Provider',
args: {
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
idp_sso_target_url: 'https://login.example.com/idp',
issuer: 'https://gitlab.example.com',
name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent'
upstream_two_factor_authn_contexts:
[
'urn:oasis:names:tc:SAML:2.0:ac:classes:CertificateProtectedTransport',
'urn:oasis:names:tc:SAML:2.0:ac:classes:SecondFactorOTPSMS',
'urn:oasis:names:tc:SAML:2.0:ac:classes:SecondFactorIGTOKEN'
]
}
}
파일을 저장하고 GitLab을 재시작하세요:
# For systems running systemd
sudo systemctl restart gitlab.target
# For systems running SysV init
sudo service gitlab restart
응답 서명 유효성 검사#
IdP는 어설션이 변조되지 않았음을 보장하기 위해 SAML 응답에 서명해야 합니다.
이는 특정 그룹 멤버십이 필요한 경우 사용자 가장 및 권한 상승을 방지합니다.
idp_cert_fingerprint 사용#
idp_cert_fingerprint를 사용하여 응답 서명 유효성 검사를 구성할 수 있습니다.
구성 예시:
Linux package (Omnibus)
/etc/gitlab/gitlab.rb를 편집하세요:
gitlab_rails['omniauth_providers'] = [
{ name: 'saml',
label: 'Our SAML Provider',
args: {
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
idp_sso_target_url: 'https://login.example.com/idp',
issuer: 'https://gitlab.example.com',
name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent'
}
}
]
파일을 저장하고 GitLab을 재구성하세요:
sudo gitlab-ctl reconfigure
Helm chart (Kubernetes)
다음 내용을 Kubernetes Secret으로 사용할 saml.yaml 파일에 저장하세요:
name: 'saml'
label: 'Our SAML Provider'
args:
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback'
idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6'
idp_sso_target_url: 'https://login.example.com/idp'
issuer: 'https://gitlab.example.com'
name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent'
Kubernetes Secret을 생성하세요:
kubectl create secret generic -n <namespace> gitlab-saml --from-file=provider=saml.yaml
Helm 값을 내보내세요:
helm get values gitlab > gitlab_values.yaml
gitlab_values.yaml를 편집하세요:
global:
appConfig:
omniauth:
providers:
- secret: gitlab-saml
파일을 저장하고 새 값을 적용하세요:
helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
Docker
docker-compose.yml을 편집하세요:
version: "3.6"
services:
gitlab:
environment:
GITLAB_OMNIBUS_CONFIG: |
gitlab_rails['omniauth_providers'] = [
{ name: 'saml',
label: 'Our SAML Provider',
args: {
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
idp_sso_target_url: 'https://login.example.com/idp',
issuer: 'https://gitlab.example.com',
name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent'
}
}
]
파일을 저장하고 GitLab을 재시작하세요:
docker compose up -d
Self-compiled (source)
/home/git/gitlab/config/gitlab.yml을 편집하세요:
production: &base
omniauth:
providers:
- { name: 'saml',
label: 'Our SAML Provider',
args: {
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
idp_sso_target_url: 'https://login.example.com/idp',
issuer: 'https://gitlab.example.com',
name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent'
}
}
파일을 저장하고 GitLab을 재시작하세요:
# For systems running systemd
sudo systemctl restart gitlab.target
# For systems running SysV init
sudo service gitlab restart
idp_cert 사용#
idp_cert를 사용하여 GitLab을 직접 구성할 수도 있습니다.
구성 예시:
Linux package (Omnibus)
/etc/gitlab/gitlab.rb를 편집하세요:
gitlab_rails['omniauth_providers'] = [
{ name: 'saml',
label: 'Our SAML Provider',
args: {
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
idp_cert: '-----BEGIN CERTIFICATE-----
<redacted>
-----END CERTIFICATE-----',
idp_sso_target_url: 'https://login.example.com/idp',
issuer: 'https://gitlab.example.com',
name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent'
}
}
]
파일을 저장하고 GitLab을 재구성하세요:
sudo gitlab-ctl reconfigure
Helm chart (Kubernetes)
다음 내용을 Kubernetes Secret으로 사용할 saml.yaml 파일에 저장하세요:
name: 'saml'
label: 'Our SAML Provider'
args:
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback'
idp_cert: |
-----BEGIN CERTIFICATE-----
<redacted>
-----END CERTIFICATE-----
idp_sso_target_url: 'https://login.example.com/idp'
issuer: 'https://gitlab.example.com'
name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent'
Kubernetes Secret을 생성하세요:
kubectl create secret generic -n <namespace> gitlab-saml --from-file=provider=saml.yaml
Helm 값을 내보내세요:
helm get values gitlab > gitlab_values.yaml
gitlab_values.yaml를 편집하세요:
global:
appConfig:
omniauth:
providers:
- secret: gitlab-saml
파일을 저장하고 새 값을 적용하세요:
helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
Docker
docker-compose.yml을 편집하세요:
version: "3.6"
services:
gitlab:
environment:
GITLAB_OMNIBUS_CONFIG: |
gitlab_rails['omniauth_providers'] = [
{ name: 'saml',
label: 'Our SAML Provider',
args: {
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
idp_cert: '-----BEGIN CERTIFICATE-----
<redacted>
-----END CERTIFICATE-----',
idp_sso_target_url: 'https://login.example.com/idp',
issuer: 'https://gitlab.example.com',
name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent'
}
}
]
파일을 저장하고 GitLab을 재시작하세요:
docker compose up -d
Self-compiled (source)
/home/git/gitlab/config/gitlab.yml을 편집하세요:
production: &base
omniauth:
providers:
- { name: 'saml',
label: 'Our SAML Provider',
args: {
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
idp_cert: '-----BEGIN CERTIFICATE-----
<redacted>
-----END CERTIFICATE-----',
idp_sso_target_url: 'https://login.example.com/idp',
issuer: 'https://gitlab.example.com',
name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent'
}
}
파일을 저장하고 GitLab을 재시작하세요:
# For systems running systemd
sudo systemctl restart gitlab.target
# For systems running SysV init
sudo service gitlab restart
응답 서명 유효성 검사를 잘못 구성한 경우 다음과 같은 오류 메시지가 표시될 수 있습니다.
-
키 유효성 검사 오류.
-
다이제스트 불일치.
-
지문 불일치.
이러한 오류를 해결하는 방법에 대한 자세한 내용은 SAML 트러블슈팅 가이드를 참조하세요.
SAML 설정 사용자 정의#
인증을 위해 SAML 서버로 사용자 리디렉션#
GitLab 구성에 auto_sign_in_with_provider 설정을 추가하면 인증을 위해 SAML 서버로 자동으로 리디렉션됩니다. 이렇게 하면 실제로 로그인하기 전에 요소를 선택해야 하는 요구 사항이 제거됩니다.
Linux package (Omnibus)
/etc/gitlab/gitlab.rb를 편집하세요:
gitlab_rails['omniauth_auto_sign_in_with_provider'] = 'saml'
파일을 저장하고 GitLab을 재구성하세요:
sudo gitlab-ctl reconfigure
Helm chart (Kubernetes)
Helm 값을 내보내세요:
helm get values gitlab > gitlab_values.yaml
gitlab_values.yaml를 편집하세요:
global:
appConfig:
omniauth:
autoSignInWithProvider: 'saml'
파일을 저장하고 새 값을 적용하세요:
helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
Docker
docker-compose.yml을 편집하세요:
version: "3.6"
services:
gitlab:
environment:
GITLAB_OMNIBUS_CONFIG: |
gitlab_rails['omniauth_auto_sign_in_with_provider'] = 'saml'
파일을 저장하고 GitLab을 재시작하세요:
docker compose up -d
Self-compiled (source)
/home/git/gitlab/config/gitlab.yml을 편집하세요:
production: &base
omniauth:
auto_sign_in_with_provider: 'saml'
파일을 저장하고 GitLab을 재시작하세요:
# For systems running systemd
sudo systemctl restart gitlab.target
# For systems running SysV init
sudo service gitlab restart
모든 로그인 시도는 SAML 서버로 리디렉션되므로 로컬 자격 증명을 사용하여 로그인할 수 없습니다. SAML 사용자 중 최소 한 명이 관리자 액세스 권한을 가지고 있는지 확인하세요.
자동 로그인 설정을 우회하려면 로그인 URL에 `?auto_sign_in=false`를 추가하세요.
예: https://gitlab.example.com/users/sign_in?auto_sign_in=false.
SAML 응답 속성 이름 매핑#
Offering: GitLab Self-Managed, GitLab Dedicated
attribute_statements를 사용하여 SAML 응답의 속성 이름을 OmniAuth info 해시의 항목에 매핑할 수 있습니다.
OmniAuth `info` 해시 스키마의 일부인 속성을 매핑하는 데만 이 설정을 사용하세요.
예를 들어 SAMLResponse에 EmailAddress라는 속성이 포함된 경우
{ email: ['EmailAddress'] }를 지정하여 속성을 info 해시의 해당 키에 매핑하세요. URI로 이름이 지정된 속성도 지원됩니다. 예를 들면
{ email: ['http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress'] }.
이 설정을 사용하여 계정을 생성하는 데 필요한 특정 속성을 찾을 위치를 GitLab에 알려주세요. 예를 들어 IdP가 사용자의 이메일 주소를 email 대신 EmailAddress로 보내는 경우 구성에서 설정하여 GitLab에 알려주세요:
Linux package (Omnibus)
/etc/gitlab/gitlab.rb를 편집하세요:
gitlab_rails['omniauth_providers'] = [
{ name: 'saml',
label: 'Our SAML Provider',
args: {
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
idp_sso_target_url: 'https://login.example.com/idp',
issuer: 'https://gitlab.example.com',
name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent',
attribute_statements: { email: ['EmailAddress'] }
}
}
]
파일을 저장하고 GitLab을 재구성하세요:
sudo gitlab-ctl reconfigure
Helm chart (Kubernetes)
다음 내용을 Kubernetes Secret으로 사용할 saml.yaml 파일에 저장하세요:
name: 'saml'
label: 'Our SAML Provider'
args:
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback'
idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6'
idp_sso_target_url: 'https://login.example.com/idp'
issuer: 'https://gitlab.example.com'
name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent'
attribute_statements:
email: ['EmailAddress']
Kubernetes Secret을 생성하세요:
kubectl create secret generic -n <namespace> gitlab-saml --from-file=provider=saml.yaml
Helm 값을 내보내세요:
helm get values gitlab > gitlab_values.yaml
gitlab_values.yaml를 편집하세요:
global:
appConfig:
omniauth:
providers:
- secret: gitlab-saml
파일을 저장하고 새 값을 적용하세요:
helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
Docker
docker-compose.yml을 편집하세요:
version: "3.6"
services:
gitlab:
environment:
GITLAB_OMNIBUS_CONFIG: |
gitlab_rails['omniauth_providers'] = [
{ name: 'saml',
label: 'Our SAML Provider',
args: {
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
idp_sso_target_url: 'https://login.example.com/idp',
issuer: 'https://gitlab.example.com',
name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent',
attribute_statements: { email: ['EmailAddress'] }
}
}
]
파일을 저장하고 GitLab을 재시작하세요:
docker compose up -d
Self-compiled (source)
/home/git/gitlab/config/gitlab.yml을 편집하세요:
production: &base
omniauth:
providers:
- { name: 'saml',
label: 'Our SAML Provider',
args: {
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
idp_sso_target_url: 'https://login.example.com/idp',
issuer: 'https://gitlab.example.com',
name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent',
attribute_statements: { email: ['EmailAddress'] }
}
}
파일을 저장하고 GitLab을 재시작하세요:
# For systems running systemd
sudo systemctl restart gitlab.target
# For systems running SysV init
sudo service gitlab restart
사용자 이름 설정#
기본적으로 SAML 응답의 이메일 주소 로컬 파트가 사용자의 GitLab 사용자 이름을 생성하는 데 사용됩니다.
attribute_statements에서 username 또는 nickname을 구성하여 사용자가 원하는 사용자 이름이 포함된 하나 이상의 속성을 지정하세요:
Linux package (Omnibus)
/etc/gitlab/gitlab.rb를 편집하세요:
gitlab_rails['omniauth_providers'] = [
{ name: 'saml',
label: 'Our SAML Provider',
args: {
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
idp_sso_target_url: 'https://login.example.com/idp',
issuer: 'https://gitlab.example.com',
name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent',
attribute_statements: { nickname: ['username'] }
}
}
]
파일을 저장하고 GitLab을 재구성하세요:
sudo gitlab-ctl reconfigure
Helm chart (Kubernetes)
다음 내용을 Kubernetes Secret으로 사용할 saml.yaml 파일에 저장하세요:
name: 'saml'
label: 'Our SAML Provider'
args:
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback'
idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6'
idp_sso_target_url: 'https://login.example.com/idp'
issuer: 'https://gitlab.example.com'
name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent'
attribute_statements:
nickname: ['username']
Kubernetes Secret을 생성하세요:
kubectl create secret generic -n <namespace> gitlab-saml --from-file=provider=saml.yaml
Helm 값을 내보내세요:
helm get values gitlab > gitlab_values.yaml
gitlab_values.yaml를 편집하세요:
global:
appConfig:
omniauth:
providers:
- secret: gitlab-saml
파일을 저장하고 새 값을 적용하세요:
helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
Docker
docker-compose.yml을 편집하세요:
version: "3.6"
services:
gitlab:
environment:
GITLAB_OMNIBUS_CONFIG: |
gitlab_rails['omniauth_providers'] = [
{ name: 'saml',
label: 'Our SAML Provider',
groups_attribute: 'Groups',
required_groups: ['Developers', 'Freelancers', 'Admins', 'Auditors'],
args: {
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
idp_sso_target_url: 'https://login.example.com/idp',
issuer: 'https://gitlab.example.com',
name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent',
attribute_statements: { nickname: ['username'] }
}
}
]
파일을 저장하고 GitLab을 재시작하세요:
docker compose up -d
Self-compiled (source)
/home/git/gitlab/config/gitlab.yml을 편집하세요:
production: &base
omniauth:
providers:
- { name: 'saml',
label: 'Our SAML Provider',
groups_attribute: 'Groups',
required_groups: ['Developers', 'Freelancers', 'Admins', 'Auditors'],
args: {
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
idp_sso_target_url: 'https://login.example.com/idp',
issuer: 'https://gitlab.example.com',
name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent',
attribute_statements: { nickname: ['username'] }
}
}
파일을 저장하고 GitLab을 재시작하세요:
# For systems running systemd
sudo systemctl restart gitlab.target
# For systems running SysV init
sudo service gitlab restart
이렇게 하면 SAML 응답의 username 속성이 GitLab의 사용자 이름으로도 설정됩니다.
프로필 속성 매핑#
History
- GitLab 17.8에서
job_title및organization속성이 도입되었습니다.
SAML 프로바이더의 프로필 정보를 동기화하려면 이러한 속성을 매핑하도록 attribute_statements를 구성해야 합니다.
지원되는 프로필 속성은 다음과 같습니다.
-
job_title -
organization
이러한 속성에는 기본 매핑이 없으며 명시적으로 구성하지 않으면 동기화되지 않습니다.
Linux package (Omnibus)
원하는 속성을 동기화하도록 OmniAuth를 구성하세요.
/etc/gitlab/gitlab.rb를 편집하세요:
gitlab_rails['omniauth_providers'] = [
{ name: 'saml',
label: 'Our SAML Provider',
args: {
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
idp_sso_target_url: 'https://login.example.com/idp',
issuer: 'https://gitlab.example.com',
name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent',
attribute_statements: {
organization: ['organization'],
job_title: ['job_title']
}
}
}
]
파일을 저장하고 GitLab을 재구성하세요:
sudo gitlab-ctl reconfigure
Helm chart (Kubernetes)
원하는 속성을 동기화하도록 OmniAuth를 구성하세요.
다음 YAML 내용을 Kubernetes Secret으로 사용할 saml.yaml 파일에 저장하세요:
name: 'saml'
label: 'Our SAML Provider'
args:
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback'
idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6'
idp_sso_target_url: 'https://login.example.com/idp'
issuer: 'https://gitlab.example.com'
name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent'
attribute_statements:
organization: ['organization']
job_title: ['job_title']
Kubernetes Secret을 생성하세요:
kubectl create secret generic -n <namespace> gitlab-saml --from-file=provider=saml.yaml
Helm 값을 내보내세요:
helm get values gitlab > gitlab_values.yaml
gitlab_values.yaml를 편집하세요:
global:
appConfig:
omniauth:
providers:
- secret: gitlab-saml
파일을 저장하고 새 값을 적용하세요:
helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
Docker
원하는 속성을 동기화하도록 OmniAuth를 구성하세요.
docker-compose.yml을 편집하세요:
version: "3.6"
services:
gitlab:
environment:
GITLAB_OMNIBUS_CONFIG: |
gitlab_rails['omniauth_providers'] = [
{ name: 'saml',
label: 'Our SAML Provider',
args: {
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
idp_sso_target_url: 'https://login.example.com/idp',
issuer: 'https://gitlab.example.com',
name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent',
attribute_statements: {
organization: ['organization'],
job_title: ['job_title']
}
}
}
]
파일을 저장하고 GitLab을 재시작하세요:
docker compose up -d
Self-compiled (source)
원하는 속성을 동기화하도록 OmniAuth를 구성하세요.
/home/git/gitlab/config/gitlab.yml을 편집하세요:
production: &base
omniauth:
providers:
- { name: 'saml',
label: 'Our SAML Provider',
args: {
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
idp_sso_target_url: 'https://login.example.com/idp',
issuer: 'https://gitlab.example.com',
name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent',
attribute_statements: {
organization: ['organization'],
job_title: ['job_title']
}
}
}
파일을 저장하고 GitLab을 재시작하세요:
# For systems running systemd
sudo systemctl restart gitlab.target
# For systems running SysV init
sudo service gitlab restart
클록 드리프트 허용#
IdP의 클록이 시스템 클록보다 약간 앞서 있을 수 있습니다.
소량의 클록 드리프트를 허용하려면 설정에서 allowed_clock_drift를 사용하세요.
파라미터 값은 초 단위의 숫자와 소수로 입력해야 합니다.
입력한 값은 응답이 유효성 검사되는 현재 시간에 추가됩니다.
Linux package (Omnibus)
/etc/gitlab/gitlab.rb를 편집하세요:
gitlab_rails['omniauth_providers'] = [
{ name: 'saml',
label: 'Our SAML Provider',
groups_attribute: 'Groups',
required_groups: ['Developers', 'Freelancers', 'Admins', 'Auditors'],
args: {
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
idp_sso_target_url: 'https://login.example.com/idp',
issuer: 'https://gitlab.example.com',
name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent',
allowed_clock_drift: 1 # for one second clock drift
}
}
]
파일을 저장하고 GitLab을 재구성하세요:
sudo gitlab-ctl reconfigure
Helm chart (Kubernetes)
다음 내용을 Kubernetes Secret으로 사용할 saml.yaml 파일에 저장하세요:
name: 'saml'
label: 'Our SAML Provider'
groups_attribute: 'Groups'
required_groups: ['Developers', 'Freelancers', 'Admins', 'Auditors']
args:
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback'
idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6'
idp_sso_target_url: 'https://login.example.com/idp'
issuer: 'https://gitlab.example.com'
name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent'
allowed_clock_drift: 1 # for one second clock drift
Kubernetes Secret을 생성하세요:
kubectl create secret generic -n <namespace> gitlab-saml --from-file=provider=saml.yaml
Helm 값을 내보내세요:
helm get values gitlab > gitlab_values.yaml
gitlab_values.yaml를 편집하세요:
global:
appConfig:
omniauth:
providers:
- secret: gitlab-saml
파일을 저장하고 새 값을 적용하세요:
helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
Docker
docker-compose.yml을 편집하세요:
version: "3.6"
services:
gitlab:
environment:
GITLAB_OMNIBUS_CONFIG: |
gitlab_rails['omniauth_providers'] = [
{ name: 'saml',
label: 'Our SAML Provider',
groups_attribute: 'Groups',
required_groups: ['Developers', 'Freelancers', 'Admins', 'Auditors'],
args: {
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
idp_sso_target_url: 'https://login.example.com/idp',
issuer: 'https://gitlab.example.com',
name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent',
allowed_clock_drift: 1 # for one second clock drift
}
}
]
파일을 저장하고 GitLab을 재시작하세요:
docker compose up -d
Self-compiled (source)
/home/git/gitlab/config/gitlab.yml을 편집하세요:
production: &base
omniauth:
providers:
- { name: 'saml',
label: 'Our SAML Provider',
groups_attribute: 'Groups',
required_groups: ['Developers', 'Freelancers', 'Admins', 'Auditors'],
args: {
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
idp_sso_target_url: 'https://login.example.com/idp',
issuer: 'https://gitlab.example.com',
name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent',
allowed_clock_drift: 1 # for one second clock drift
}
}
파일을 저장하고 GitLab을 재시작하세요:
# For systems running systemd
sudo systemctl restart gitlab.target
# For systems running SysV init
sudo service gitlab restart
uid에 고유 속성 지정 (선택 사항)#
기본적으로 사용자의 uid는 SAML 응답에서 NameID 속성으로 설정됩니다. uid에 다른 속성을 지정하려면 uid_attribute를 설정하면 됩니다.
uid를 고유 속성으로 설정하기 전에, SAML 사용자가 변경할 수 없도록 다음 속성이 구성되어 있는지 확인하세요:
-
omniauth_auto_link_saml_user와 함께 사용할 경우Email.
사용자가 이러한 속성을 변경할 수 있으면 다른 승인된 사용자로 로그인할 수 있습니다.
이러한 속성을 변경 불가능하게 만드는 방법은 SAML IdP 문서를 참조하세요.
다음 예시에서는 SAML 응답의 uid 속성 값이 uid_attribute로 설정됩니다.
Linux package (Omnibus)
/etc/gitlab/gitlab.rb를 편집하세요:
gitlab_rails['omniauth_providers'] = [
{ name: 'saml',
label: 'Our SAML Provider',
args: {
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
idp_sso_target_url: 'https://login.example.com/idp',
issuer: 'https://gitlab.example.com',
name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent',
uid_attribute: 'uid'
}
}
]
파일을 저장하고 GitLab을 재구성하세요:
sudo gitlab-ctl reconfigure
Helm chart (Kubernetes)
다음 내용을 Kubernetes Secret으로 사용할 saml.yaml 파일에 저장하세요:
name: 'saml'
label: 'Our SAML Provider'
groups_attribute: 'Groups'
required_groups: ['Developers', 'Freelancers', 'Admins', 'Auditors']
args:
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback'
idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6'
idp_sso_target_url: 'https://login.example.com/idp'
issuer: 'https://gitlab.example.com'
name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent'
uid_attribute: 'uid'
Kubernetes Secret을 생성하세요:
kubectl create secret generic -n <namespace> gitlab-saml --from-file=provider=saml.yaml
Helm 값을 내보내세요:
helm get values gitlab > gitlab_values.yaml
gitlab_values.yaml를 편집하세요:
global:
appConfig:
omniauth:
providers:
- secret: gitlab-saml
파일을 저장하고 새 값을 적용하세요:
helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
Docker
docker-compose.yml을 편집하세요:
version: "3.6"
services:
gitlab:
environment:
GITLAB_OMNIBUS_CONFIG: |
gitlab_rails['omniauth_providers'] = [
{ name: 'saml',
label: 'Our SAML Provider',
groups_attribute: 'Groups',
required_groups: ['Developers', 'Freelancers', 'Admins', 'Auditors'],
args: {
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
idp_sso_target_url: 'https://login.example.com/idp',
issuer: 'https://gitlab.example.com',
name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent',
uid_attribute: 'uid'
}
}
]
파일을 저장하고 GitLab을 재시작하세요:
docker compose up -d
Self-compiled (source)
/home/git/gitlab/config/gitlab.yml을 편집하세요:
production: &base
omniauth:
providers:
- { name: 'saml',
label: 'Our SAML Provider',
groups_attribute: 'Groups',
required_groups: ['Developers', 'Freelancers', 'Admins', 'Auditors'],
args: {
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
idp_sso_target_url: 'https://login.example.com/idp',
issuer: 'https://gitlab.example.com',
name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent',
uid_attribute: 'uid'
}
}
파일을 저장하고 GitLab을 재시작하세요:
# For systems running systemd
sudo systemctl restart gitlab.target
# For systems running SysV init
sudo service gitlab restart
어설션 암호화 (선택 사항)#
SAML 어설션 암호화는 선택 사항이지만 권장됩니다. 이는 암호화되지 않은 데이터가 악의적인 행위자에 의해 로깅되거나 가로채지는 것을 방지하는 추가 보호 계층을 제공합니다.
이 통합은 어설션 암호화와 요청 서명 모두에 `certificate` 및 `private_key` 설정을 사용합니다.
SAML 어설션을 암호화하려면 GitLab SAML 설정에서 개인 키와 공개 인증서를 정의하세요. IdP는 공개 인증서로 어설션을 암호화하고 GitLab은 개인 키로 어설션을 복호화합니다.
키와 인증서를 정의할 때 키 파일의 모든 줄바꿈을 \n으로 교체하세요.
이렇게 하면 키 파일이 줄바꿈 없는 하나의 긴 문자열이 됩니다.
Linux package (Omnibus)
/etc/gitlab/gitlab.rb를 편집하세요:
gitlab_rails['omniauth_providers'] = [
{ name: 'saml',
label: 'Our SAML Provider',
groups_attribute: 'Groups',
required_groups: ['Developers', 'Freelancers', 'Admins', 'Auditors'],
args: {
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
idp_sso_target_url: 'https://login.example.com/idp',
issuer: 'https://gitlab.example.com',
name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent',
certificate:|
-----BEGIN CERTIFICATE-----
<redacted>
-----END CERTIFICATE-----,
private_key:|
-----BEGIN PRIVATE KEY-----
<redacted>
-----END PRIVATE KEY-----
}
}
]
파일을 저장하고 GitLab을 재구성하세요:
sudo gitlab-ctl reconfigure
Helm chart (Kubernetes)
다음 내용을 Kubernetes Secret으로 사용할 saml.yaml 파일에 저장하세요:
name: 'saml'
label: 'Our SAML Provider'
groups_attribute: 'Groups'
required_groups: ['Developers', 'Freelancers', 'Admins', 'Auditors']
args:
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback'
idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6'
idp_sso_target_url: 'https://login.example.com/idp'
issuer: 'https://gitlab.example.com'
name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent'
certificate:|
-----BEGIN CERTIFICATE-----
<redacted>
----END CERTIFICATE-----,
private_key:|
-----BEGIN PRIVATE KEY-----
<redacted>
-----END PRIVATE KEY-----
Kubernetes Secret을 생성하세요:
kubectl create secret generic -n <namespace> gitlab-saml --from-file=provider=saml.yaml
Helm 값을 내보내세요:
helm get values gitlab > gitlab_values.yaml
gitlab_values.yaml를 편집하세요:
global:
appConfig:
omniauth:
providers:
- secret: gitlab-saml
파일을 저장하고 새 값을 적용하세요:
helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
Docker
docker-compose.yml을 편집하세요:
version: "3.6"
services:
gitlab:
environment:
GITLAB_OMNIBUS_CONFIG: |
gitlab_rails['omniauth_providers'] = [
{ name: 'saml',
label: 'Our SAML Provider',
groups_attribute: 'Groups',
required_groups: ['Developers', 'Freelancers', 'Admins', 'Auditors'],
args: {
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
idp_sso_target_url: 'https://login.example.com/idp',
issuer: 'https://gitlab.example.com',
name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent',
certificate:|
-----BEGIN CERTIFICATE-----
<redacted>
-----END CERTIFICATE-----,
private_key:|
-----BEGIN PRIVATE KEY-----
<redacted>
-----END PRIVATE KEY-----
}
}
]
파일을 저장하고 GitLab을 재시작하세요:
docker compose up -d
Self-compiled (source)
/home/git/gitlab/config/gitlab.yml을 편집하세요:
production: &base
omniauth:
providers:
- { name: 'saml',
label: 'Our SAML Provider',
groups_attribute: 'Groups',
required_groups: ['Developers', 'Freelancers', 'Admins', 'Auditors'],
args: {
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
idp_sso_target_url: 'https://login.example.com/idp',
issuer: 'https://gitlab.example.com',
name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent',
certificate: '-----BEGIN CERTIFICATE-----\n<redacted>\n-----END CERTIFICATE-----',
private_key: '-----BEGIN PRIVATE KEY-----\n<redacted>\n-----END PRIVATE KEY-----'
}
}
파일을 저장하고 GitLab을 재시작하세요:
# For systems running systemd
sudo systemctl restart gitlab.target
# For systems running SysV init
sudo service gitlab restart
SAML 인증 요청 서명 (선택 사항)#
GitLab이 SAML 인증 요청에 서명하도록 구성할 수 있습니다. GitLab SAML 요청은 SAML 리디렉션 바인딩을 사용하므로 이 구성은 선택 사항입니다.
서명을 구현하려면:
GitLab 인스턴스가 SAML에 사용할 개인 키와 공개 인증서 쌍을 생성하세요.
구성의 security 섹션에서 서명 설정을 구성하세요.
예시:
Linux package (Omnibus)
/etc/gitlab/gitlab.rb를 편집하세요:
gitlab_rails['omniauth_providers'] = [
{ name: 'saml',
label: 'Our SAML Provider',
args: {
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
idp_sso_target_url: 'https://login.example.com/idp',
issuer: 'https://gitlab.example.com',
name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent',
certificate: '-----BEGIN CERTIFICATE-----\n<redacted>\n-----END CERTIFICATE-----',
private_key: '-----BEGIN PRIVATE KEY-----\n<redacted>\n-----END PRIVATE KEY-----',
security: {
authn_requests_signed: true, # enable signature on AuthNRequest
want_assertions_signed: true, # enable the requirement of signed assertion
want_assertions_encrypted: false, # enable the requirement of encrypted assertion
metadata_signed: false, # enable signature on Metadata
signature_method: 'http://www.w3.org/2001/04/xmldsig-more#rsa-sha256',
digest_method: 'http://www.w3.org/2001/04/xmlenc#sha256',
}
}
}
]
파일을 저장하고 GitLab을 재구성하세요:
sudo gitlab-ctl reconfigure
Helm chart (Kubernetes)
다음 내용을 Kubernetes Secret으로 사용할 saml.yaml 파일에 저장하세요:
name: 'saml'
label: 'Our SAML Provider'
args:
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback'
idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6'
idp_sso_target_url: 'https://login.example.com/idp'
issuer: 'https://gitlab.example.com'
name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent'
certificate: '-----BEGIN CERTIFICATE-----\n<redacted>\n-----END CERTIFICATE-----'
private_key: '-----BEGIN PRIVATE KEY-----\n<redacted>\n-----END PRIVATE KEY-----'
security:
authn_requests_signed: true # enable signature on AuthNRequest
want_assertions_signed: true # enable the requirement of signed assertion
want_assertions_encrypted: false # enable the requirement of encrypted assertion
metadata_signed: false # enable signature on Metadata
signature_method: 'http://www.w3.org/2001/04/xmldsig-more#rsa-sha256'
digest_method: 'http://www.w3.org/2001/04/xmlenc#sha256'
Kubernetes Secret을 생성하세요:
kubectl create secret generic -n <namespace> gitlab-saml --from-file=provider=saml.yaml
Helm 값을 내보내세요:
helm get values gitlab > gitlab_values.yaml
gitlab_values.yaml를 편집하세요:
global:
appConfig:
omniauth:
providers:
- secret: gitlab-saml
파일을 저장하고 새 값을 적용하세요:
helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
Docker
docker-compose.yml을 편집하세요:
version: "3.6"
services:
gitlab:
environment:
GITLAB_OMNIBUS_CONFIG: |
gitlab_rails['omniauth_providers'] = [
{ name: 'saml',
label: 'Our SAML Provider',
args: {
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
idp_sso_target_url: 'https://login.example.com/idp',
issuer: 'https://gitlab.example.com',
name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent',
certificate: '-----BEGIN CERTIFICATE-----\n<redacted>\n-----END CERTIFICATE-----',
private_key: '-----BEGIN PRIVATE KEY-----\n<redacted>\n-----END PRIVATE KEY-----',
security: {
authn_requests_signed: true, # enable signature on AuthNRequest
want_assertions_signed: true, # enable the requirement of signed assertion
want_assertions_encrypted: false, # enable the requirement of encrypted assertion
metadata_signed: false, # enable signature on Metadata
signature_method: 'http://www.w3.org/2001/04/xmldsig-more#rsa-sha256',
digest_method: 'http://www.w3.org/2001/04/xmlenc#sha256',
}
}
}
]
파일을 저장하고 GitLab을 재시작하세요:
docker compose up -d
Self-compiled (source)
/home/git/gitlab/config/gitlab.yml을 편집하세요:
production: &base
omniauth:
providers:
- { name: 'saml',
label: 'Our SAML Provider',
args: {
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
idp_sso_target_url: 'https://login.example.com/idp',
issuer: 'https://gitlab.example.com',
name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent',
certificate: '-----BEGIN CERTIFICATE-----\n<redacted>\n-----END CERTIFICATE-----',
private_key: '-----BEGIN PRIVATE KEY-----\n<redacted>\n-----END PRIVATE KEY-----',
security: {
authn_requests_signed: true, # enable signature on AuthNRequest
want_assertions_signed: true, # enable the requirement of signed assertion
want_assertions_encrypted: false, # enable the requirement of encrypted assertion
metadata_signed: false, # enable signature on Metadata
signature_method: 'http://www.w3.org/2001/04/xmldsig-more#rsa-sha256',
digest_method: 'http://www.w3.org/2001/04/xmlenc#sha256',
}
}
}
파일을 저장하고 GitLab을 재시작하세요:
# For systems running systemd
sudo systemctl restart gitlab.target
# For systems running SysV init
sudo service gitlab restart
GitLab은 이후 다음을 수행합니다:
-
제공된 개인 키로 요청에 서명합니다.
-
IdP가 수신된 요청의 서명을 검증할 수 있도록 구성된 공개 x500 인증서를 메타데이터에 포함합니다.
이 옵션에 대한 자세한 내용은 Ruby SAML gem 문서를 참조하세요.
Ruby SAML gem은 OmniAuth SAML gem에서 SAML 인증의 클라이언트 측을 구현하는 데 사용됩니다.
SAML 리디렉션 바인딩은 SAML POST 바인딩과 다릅니다. POST 바인딩에서는 중간자가 요청을 변조하는 것을 방지하기 위해 서명이 필요합니다.
SAML을 통해 생성된 사용자의 비밀번호 생성#
GitLab은 SAML을 통해 생성된 사용자의 비밀번호를 생성하고 설정합니다.
SSO 또는 SAML로 인증된 사용자는 HTTPS를 통한 Git 작업에 비밀번호를 사용해서는 안 됩니다. 이러한 사용자는 대신 다음을 사용할 수 있습니다:
-
OAuth 자격 증명 헬퍼 사용.
기존 사용자의 SAML 아이덴티티 연결#
관리자는 SAML 사용자를 기존 GitLab 사용자와 자동으로 연결하도록 GitLab을 구성할 수 있습니다. 자세한 내용은 GitLab에서 SAML 지원 구성을 참조하세요.
사용자는 SAML 아이덴티티를 기존 GitLab 계정에 수동으로 연결할 수 있습니다. 자세한 내용은 기존 사용자에 대해 OmniAuth 활성화를 참조하세요.
GitLab Self-Managed에서 그룹 SAML SSO 구성#
Offering: GitLab Self-Managed, GitLab Dedicated
GitLab Self-Managed 인스턴스에서 여러 SAML IdP를 통한 액세스를 허용해야 하는 경우 그룹 SAML SSO를 사용하세요.
그룹 SAML SSO를 구성하려면:
Linux package (Omnibus)
GitLab이 HTTPS로 구성되어 있는지 확인하세요.
/etc/gitlab/gitlab.rb를 편집하여 OmniAuth와 group_saml 프로바이더를 활성화하세요:
gitlab_rails['omniauth_enabled'] = true
gitlab_rails['omniauth_providers'] = [{ name: 'group_saml' }]
파일을 저장하고 GitLab을 재구성하세요:
sudo gitlab-ctl reconfigure
Helm chart (Kubernetes)
GitLab이 HTTPS로 구성되어 있는지 확인하세요.
다음 내용을 Kubernetes Secret으로 사용할 group_saml.yaml 파일에 저장하세요:
name: 'group_saml'
Kubernetes Secret을 생성하세요:
kubectl create secret generic -n <namespace> gitlab-group-saml --from-file=provider=group_saml.yaml
Helm 값을 내보내세요:
helm get values gitlab > gitlab_values.yaml
gitlab_values.yaml를 편집하여 OmniAuth와 group_saml 프로바이더를 활성화하세요:
global:
appConfig:
omniauth:
enabled: true
providers:
- secret: gitlab-group-saml
파일을 저장하고 새 값을 적용하세요:
helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
Docker
GitLab이 HTTPS로 구성되어 있는지 확인하세요.
docker-compose.yml을 편집하여 OmniAuth와 group_saml 프로바이더를 활성화하세요:
version: "3.6"
services:
gitlab:
environment:
GITLAB_OMNIBUS_CONFIG: |
gitlab_rails['omniauth_enabled'] = true
gitlab_rails['omniauth_providers'] = [{ name: 'group_saml' }]
파일을 저장하고 GitLab을 재시작하세요:
docker compose up -d
Self-compiled (source)
GitLab이 HTTPS로 구성되어 있는지 확인하세요.
/home/git/gitlab/config/gitlab.yml을 편집하여 OmniAuth와 group_saml 프로바이더를 활성화하세요:
production: &base
omniauth:
enabled: true
providers:
- { name: 'group_saml' }
파일을 저장하고 GitLab을 재시작하세요:
# For systems running systemd
sudo systemctl restart gitlab.target
# For systems running SysV init
sudo service gitlab restart
멀티 테넌트 솔루션으로서 GitLab Self-Managed의 그룹 SAML은 권장되는 인스턴스 전체 SAML에 비해 제한적입니다. 다음 기능을 활용하려면 인스턴스 전체 SAML을 사용하세요:
IdP의 SAML 앱에 대한 추가 구성#
IdP에서 SAML 앱을 구성할 때 다음과 같은 추가 구성이 필요할 수 있습니다:
| 필드 | 값 | 참고 |
|---|---|---|
| SAML profile | Web browser SSO profile | GitLab은 SAML을 사용하여 브라우저를 통해 사용자를 로그인시킵니다. IdP에 직접 요청하지 않습니다. |
| SAML request binding | HTTP Redirect | GitLab(SP)은 base64 인코딩된 SAMLRequest HTTP 파라미터와 함께 사용자를 IdP로 리디렉션합니다. |
| SAML response binding | HTTP POST | IdP가 SAML 토큰을 전송하는 방법을 지정합니다. 사용자의 브라우저가 GitLab에 다시 제출하는 SAMLResponse를 포함합니다. |
| Sign SAML response | Required | 변조를 방지합니다. |
| X.509 certificate in response | Required | 응답에 서명하고 제공된 지문에 대해 응답을 확인합니다. |
| Fingerprint algorithm | SHA-1 | GitLab은 SAML 응답 서명에 인증서의 SHA-1 해시를 사용합니다. |
| Signature algorithm | SHA-1/SHA-256/SHA-384/SHA-512 | 응답 서명 방법을 결정합니다. 다이제스트 메서드라고도 하며 SAML 응답에서 지정할 수 있습니다. |
| Encrypt SAML assertion | Optional | 아이덴티티 프로바이더, 사용자의 브라우저, GitLab 간에 TLS를 사용합니다. |
| Sign SAML assertion | Optional | SAML 어설션의 무결성을 검증합니다. 활성화되면 전체 응답에 서명합니다. |
| Check SAML request signature | Optional | SAML 응답의 서명을 확인합니다. |
| Default RelayState | Optional | IdP에서 SAML을 통해 성공적으로 로그인한 후 사용자가 도달해야 하는 기본 URL의 하위 경로를 지정합니다. |
| NameID format | Persistent | NameID 형식 세부 정보를 참조하세요. |
| Additional URLs | Optional | 일부 프로바이더의 다른 필드에 발급자, 식별자 또는 어설션 컨슈머 서비스 URL이 포함될 수 있습니다. |
구성 예시는 특정 프로바이더 참고 사항을 참조하세요.
Geo에서 SAML 구성#
Geo에서 SAML을 구성하려면 인스턴스 전체 SAML 구성을 참조하세요.
자세한 내용은 Single Sign-On(SSO)을 사용하는 Geo를 참조하세요.
트러블슈팅#
SAML 트러블슈팅 가이드를 참조하세요.