[GitLab] Keycloak OIDC - 그룹 기반 인증 연동 설정 (w. terraform)

그룹 기반 인증의 경우 GitLab의 Premium, Ultimate 이상의 Plan부터 사용이 가능합니다.

Free Plan을 사용하신다면 그룹 기반 인증은 제외하고 참고하세요

 

Keycloak의 설정의 경우 실제 Terraform Code를 모듈화하여 사용하고 있지만, 해당 내용에서는 기본적인 코드로 작성하였습니다.

아래 작성 Terraform Code는 이런 Block을 사용하여 구성했다 정도만 참고하세요

 

 

1. Keycloak 설정 (w. terraform)

 

Keycloak - User & Group 생성

# 유저 생성
resource "keycloak_user" "user" {
  realm_id   = var.realm_id
  username   = var.user_name
  email      = var.email
  enabled    = var.user_enabled
  first_name = var.first_name
  last_name  = var.last_name

  initial_password {
    value     = var.pwd
    temporary = var.initial_password_temporary
  }

  required_actions = [
    "UPDATE_PASSWORD"
  ]

  lifecycle {
    ignore_changes = [initial_password, required_actions]
  }
}

# 그룹 생성
resource "keycloak_group" "group" {
  realm_id = var.realm_id
  name     = var.group_name
}

# 유저 그룹 매핑
resource "keycloak_user_groups" "user_groups" {
  realm_id  = var.realm_id
  user_id   = var.user_id
  group_ids = var.group_ids
}

 

 

Keycloak - OIDC Client & Mapper 생성

# Keycloak에 OIDC 클라이언트 생성
resource "keycloak_openid_client" "gitlab_oidc_client" {
  realm_id                     = module.keycloak_realm.realm_id
  client_id                    = "gitlaboidc"
  name                         = "GitLab OIDC Client"
  enabled                      = true
  standard_flow_enabled        = true
  access_type                  = "CONFIDENTIAL"
  direct_access_grants_enabled = false
  valid_redirect_uris = [
    "${var.gitlab_scheme}://${var.gitlab_addr}/users/auth/openid_connect/callback"
  ]
  login_theme = "keycloak"
}

# group membership protocol mapper 생성
resource "keycloak_openid_group_membership_protocol_mapper" "gitlab_groups_mapper" {
  realm_id            = module.keycloak_realm.realm_id
  client_id           = keycloak_openid_client.gitlab_oidc_client.id
  name                = "group-membership-mapper"
  full_path           = false
  add_to_id_token     = true
  add_to_access_token = false
  add_to_userinfo     = true
  claim_name          = "groups"
}

 

 

 

 

 

2.  GitLab 설정

GitLab - 설정 파일에 OIDC 관련 설정 추가

아래는 GitLab의 gitlab.rb 설정 파일에서 Keycloak을 OIDC로 연동할 때 필요한 설정입니다. 

• groups_attribute, admin_groups, external_groups, required_groups 등의 그룹 관련 설정은 Keycloak에서 사용자의 그룹 정보를 GitLab에 전달하고, 이를 GitLab이 수신하여 처리하는 방식으로 동작하게 됩니다.

gitlab_rails['omniauth_auto_link_user'] = ['openid_connect']
gitlab_rails['omniauth_allow_single_sign_on'] = ['openid_connect']
gitlab_rails['omniauth_block_auto_created_users'] = false
gitlab_rails['omniauth_providers'] = [
  {
    name: "openid_connect",
    label: "Keycloak",
    args: {
      name: "openid_connect",
      scope: ["openid", "profile", "email"],
      response_type: "code",
      issuer:  "https://{Keycloak-URL 입력}/realms/gitlab",
      client_auth_method: "query",
      discovery: true,
      uid_field: "preferred_username",
      pkce: true,
      client_options: {
        identifier: "gitlaboidc",
        secret: {Keycloak-Client-Secret 입력}",
        redirect_uri: "https://{GitLab-URL 입력}/users/auth/openid_connect/callback",
        gitlab: {
          groups_attribute: "groups",
          admin_groups: ["Admin"],
          external_groups: ["External"],
          required_groups: ["Developer","Admin","External"]
        }
      }
    }
  }
]

 

 

 

GitLab OIDC 관련 설정 상세 설명

gitlab_rails['omniauth_auto_link_user'] = ['openid_connect']

• 이 설정은 기존의 GitLab에 계정이 있을 경우, Keycloak OIDC를 통해 로그인할 때 자동으로 해당 계정에 연결되도록 설정합니다.
• 'openid_connect'를 사용하여 Keycloak OIDC로 로그인하는 사용자 계정을 자동으로 연결합니다.

 

gitlab_rails['omniauth_allow_single_sign_on'] = ['openid_connect']

• Single Sign-On (SSO)를 허용하는 설정
• 'openid_connect' 값을 지정하면 Keycloak OIDC를 통해 로그인할 때 SSO 기능이 활성화됩니다.

 

gitlab_rails['omniauth_block_auto_created_users'] = false

• GitLab에서 자동 생성된 사용자 계정을 차단할지 여부를 설정합니다. false로 설정하면, Keycloak에서 인증을 통해 자동으로 생성된 계정이 활성화 상태로 생성됩니다.

 

gitlab_rails['omniauth_providers'] = [
  {
    name: "openid_connect",
    label: "Keycloak",
    args: {
      name: "openid_connect",
      scope: ["openid", "profile", "email"],
      response_type: "code",
      issuer: "https://{Keycloak-URL 입력}/realms/gitlab",
      client_auth_method: "query",
      discovery: true,
      uid_field: "preferred_username",
      pkce: true,
      client_options: {
        identifier: "gitlaboidc",
        secret: "{Keycloak-Client-Secret 입력}",
        redirect_uri: "https://{GitLab-URL 입력}/users/auth/openid_connect/callback",
        gitlab: {
          groups_attribute: "groups",
          admin_groups: ["Admin"],
          external_groups: ["External"],
          required_groups: ["Developer", "Admin", "External"]
        }
      }
    }
  }
]

 

그룹 설정

• groups_attribute
  • Keycloak에서 전달하는 사용자 그룹 정보의 속성을 정의합니다.
  • Keycloak에서 groups 속성으로 그룹 정보를 전달하고, 이를 GitLab에서 참조합니다.
• admin_groups
  • GitLab의 관리자 그룹으로 설정할 Keycloak 그룹을 지정합니다.
  • Keycloak에서 Admin 그룹에 속한 사용자는 GitLab에서 관리자 권한을 가지게 됩니다.
• external_groups
  • 외부 사용자로 간주할 그룹을 지정합니다.
  • External 그룹에 속한 사용자는 GitLab에서 외부 사용자로 설정됩니다.
• required_groups
  • GitLab에 로그인하기 위해 필수로 속해야 하는 그룹을 지정합니다.
  • 해당 옵션이 없다면 Keycloak의 모든 유저로 GitLab Login이 가능합니다.
  • 예시에서는 Developer, Admin, External 그룹 중 하나에 속해야만 로그인할 수 있도록 설정되어 있습니다.

 

주의 사항: GitLab 그룹 자동 추가 불가

• 이 설정을 통해 Keycloak 그룹을 GitLab으로 전달하고, Keycloak 그룹에 따른 권한을 부여할 수 있습니다. 그러나 GitLab 그룹에 사용자를 자동으로 추가하는 기능은 제공되지 않습니다.
• 아래 사진과 같이 각각 Keycloak의 그룹에 따른 GitLab 권한을 부여받은 것을 확인
• 하지만 GitLab의 특정그룹, 또는 모든 그룹에 Member로 권한 부여는 추가되지 않습니다.

 

 

정리

이번 포스트에서는 Keycloak을 활용하여 GitLab과 OIDC SSO 연동을 설정하는 방법에 대해 다뤘습니다.

이를 통해 중앙 집중식 인증 관리를 구현하고, 사용자 접근성을 향상시키며 보안 수준을 강화할 수 있습니다.

또한, 특정 권한을 가진 사용자를 그룹 기반으로 관리할 수 있어, GitLab 내에서의 사용자 권한 설정이 더욱 유연해집니다.

 

다만, 이 기능을 통해 GitLab 그룹에 사용자를 자동으로 추가하는 기능은 제공되지 않습니다. 즉, Keycloak을 통해 인증된 사용자는 GitLab에서 권한이 부여되지만, 사용자가 GitLab 그룹에 자동으로 추가되지는 않음을 유의해야 합니다.

 

이런 방식으로 그룹 기반의 유연한 권한 관리와 GitLab의 사용자 인증을 효과적으로 결합할 수 있으니, 조직의 보안과 접근성을 동시에 높이는 방법으로 활용해 보시기 바랍니다.

 

질문이나 추가 도움이 필요하면 댓글 부탁드립니다. 감사합니다! 😁