Microsoft Azure를 OAuth 2.0 인증 제공자로 사용하기

Tier: Free, Premium, Ultimate Offering: Self-managed

Microsoft Azure OAuth 2.0 OmniAuth 제공자를 활성화하고 Microsoft Azure 자격 증명으로 GitLab에 로그인할 수 있습니다. 이전 Azure Active Directory v1.0 엔드포인트 또는 v2.0 엔드포인트를 사용하는 제공자를 구성할 수 있습니다.

새로운 프로젝트의 경우, Microsoft는 Microsoft 신원 플랫폼(v2.0) 엔드포인트를 사용하는 OpenID Connect 프로토콜을 사용할 것을 권장합니다.

OpenID Connect 프로토콜로 마이그레이션

OpenID Connect 프로토콜로 마이그레이션하려면 여러 개의 OpenID Connect 제공자 구성을 참조하십시오.

여러 제공자 간에 다른 uid_field를 설정해야 합니다:

제공자	`uid`	비고
`omniauth-azure-oauth2`	`sub`	추가 속성 `oid`, `tid`는 info 객체 내에서 제공됩니다.
`omniauth-azure-activedirectory-v2`	`oid`	마이그레이션 시 `oid`를 `uid_field`로 구성해야 합니다.
`omniauth_openid_connect`	`sub`	다른 필드를 사용하려면 `uid_field`를 지정해야 합니다.

예를 들어, omniauth-azure-oauth2에서 omniauth_openid_connect로 마이그레이션하려면 구성을 변경해야 합니다.

Linux 패키지 (Omnibus)

기존 구성의 일부를 제거하고 아래와 같이 새로운 구성을 추가합니다.

gitlab_rails['omniauth_providers'] = [
  {
    name: "azure_oauth2",
    # label: "제공자 이름", # 선택적 로그인 버튼 레이블, 기본값은 "Azure AD"
    args: {
+      name: "azure_oauth2",
+      strategy_class: "OmniAuth::Strategies::OpenIDConnect",
+      scope: ["openid", "profile", "email"],
+      response_type: "code",
+      issuer:  "https://login.microsoftonline.com/<tenant_id>/v2.0",
+      client_auth_method: "query",
+      discovery: true,
+      uid_field: "sub",
+      client_options: {
+        identifier: "<client_id>",
+        secret: "<client_secret>",
+        redirect_uri: "https://gitlab.example.com/users/auth/azure_oauth2/callback"
+      }
-      client_id: "<client_id>",
-      client_secret: "<client_secret>",
-      tenant_id: "<tenant_id>",
    }
  }
]

직접 컴파일한 경우 (소스)

기존 구성의 일부를 제거하고 아래와 같이 새로운 구성을 추가합니다.

  - { name: 'azure_oauth2',
      # label: '제공자 이름', # 선택적 로그인 버튼 레이블, 기본값은 "Azure AD"
-      args: { client_id: '<client_id>',
-              client_secret: '<client_secret>',
-              tenant_id: '<tenant_id>' } }
+      icon: "<custom_provider_icon>",
+      args: {
+        name: "azure_oauth2",
+        strategy_class: "OmniAuth::Strategies::OpenIDConnect",
+        scope: ["openid","profile","email"],
+        response_type: "code",
+        issuer: 'https://login.microsoftonline.com/<tenant_id>/v2.0',
+        discovery: true,
+        client_auth_method: 'query',
+        uid_field: 'sub',
+        send_scope_to_token_endpoint: "false",
+        client_options: {
+          identifier: "<client_id>",
+          secret: "<client_secret>",
+          redirect_uri: "<your_gitlab_url>/users/auth/azure_oauth2/callback"
+        }
+      }
    }

예를 들어, omniauth-azure-activedirectory-v2에서 omniauth_openid_connect로 마이그레이션하려면 구성을 변경해야 합니다.

Linux 패키지 (Omnibus)

기존 구성의 일부를 제거하고 아래와 같이 새로운 구성을 추가합니다.

gitlab_rails['omniauth_providers'] = [
  {
 -    name: "azure_activedirectory_v2",
    # label: "제공자 이름", # 선택적 로그인 버튼 레이블, 기본값은 "Azure AD v2"
    args: {
+      name: "azure_activedirectory_v2",
+      strategy_class: "OmniAuth::Strategies::OpenIDConnect",
+      scope: ["openid", "profile", "email"],
+      response_type: "code",
+      issuer:  "https://login.microsoftonline.com/<tenant_id>/v2.0",
+      client_auth_method: "query",
+      discovery: true,
+      uid_field: "oid",
+      client_options: {
+        identifier: "<client_id>",
+        secret: "<client_secret>",
+        redirect_uri: "https://gitlab.example.com/users/auth/azure_activedirectory_v2/callback"
+      }
-      client_id: "<client_id>",
-      client_secret: "<client_secret>",
-      tenant_id: "<tenant_id>",
    }
  }
]

직접 컴파일한 경우 (소스)

기존 구성의 일부를 제거하고 아래와 같이 새로운 구성을 추가합니다.

  - { name: 'azure_activedirectory_v2',
      # label: '제공자 이름', # 선택적 로로그인 버튼 레이블, 기본값은 "Azure AD v2"
-      args: { client_id: '<client_id>',
-              client_secret: '<client_secret>',
-              tenant_id: '<tenant_id>' } }
+      icon: "<custom_provider_icon>",
+      args: {
+        name: "azure_activedirectory_v2",
+        strategy_class: "OmniAuth::Strategies::OpenIDConnect",
+        scope: ["openid","profile","email"],
+        response_type: "code",
+        issuer: 'https://login.microsoftonline.com/<tenant_id>/v2.0',
+        discovery: true,
+        client_auth_method: 'query',
+        uid_field: 'oid',
+        send_scope_to_token_endpoint: "false",
+        client_options: {
+          identifier: "<client_id>",
+          secret: "<client_secret>",
+          redirect_uri: "<your_gitlab_url>/users/auth/azure_activedirectory_v2/callback"
+        }
+      }
    }

기타 사용자 정의에 대한 자세한 정보는 gitlab_username_claim을 참조하세요.

Azure 애플리케이션 등록

Microsoft Azure OAuth 2.0 OmniAuth 공급자를 활성화하려면 Azure 애플리케이션을 등록하고 클라이언트 ID 및 비밀 키를 가져와야 합니다.

Azure 포털에 로그인합니다.
여러 Azure Active Directory 테넌트가 있는 경우 원하는 테넌트로 전환합니다. 테넌트 ID를 기록합니다.
애플리케이션 등록을 하고 다음 정보를 제공합니다:
- Azure OAuth 콜백의 URL이 필요한 리디렉트 URI. 예:
  - v1.0 엔드포인트의 경우: https://gitlab.example.com/users/auth/azure_oauth2/callback.
  - v2.0 엔드포인트의 경우: https://gitlab.example.com/users/auth/azure_activedirectory_v2/callback.
- Web으로 설정해야 하는 애플리케이션 유형.
클라이언트 ID 및 클라이언트 비밀을 저장합니다. 클라이언트 비밀은 한 번만 표시됩니다.
필요한 경우 새 애플리케이션 비밀을 생성할 수 있습니다.

클라이언트 ID와 클라이언트 비밀은 OAuth 2.0과 관련된 용어입니다. 일부 Microsoft 설명서에서는 이 용어를 애플리케이션 ID와 애플리케이션 비밀로 지칭합니다.

API 권한 (범위) 추가

v2.0 엔드포인트를 사용하는 경우, 애플리케이션을 생성한 후 웹 API 노출을 구성합니다. Microsoft Graph API에서 다음 위임된 권한을 추가합니다:

email
openid
profile

또는 User.Read.All 애플리케이션 권한을 추가합니다.

GitLab에서 Microsoft OAuth 활성화

GitLab 서버에서 구성 파일을 엽니다.
- Linux 패키지 설치의 경우:
```
sudo editor /etc/gitlab/gitlab.rb
```
- 자체 컴파일한 설치의 경우:
```
cd /home/git/gitlab
     
sudo -u git -H editor config/gitlab.yml
```
공통 설정을 구성하여 azure_oauth2를 단일 사인온 공급자로 추가합니다. 이렇게 함으로써 기존 GitLab 계정이 없는 사용자의 Just-In-Time 계정 프로비저닝이 가능해집니다.

공급자 구성을 추가합니다. Azure 애플리케이션을 등록할 때 얻은 값으로 <client_id>, <client_secret>, <tenant_id>를 대체합니다.

Linux 패키지 설치의 경우:

v1.0 엔드포인트의 경우:

gitlab_rails['omniauth_providers'] = [
  {
    name: "azure_oauth2",
    # label: "공급자 이름", # 선택 사항, 로그인 버튼에 대한 기본값은 "Azure AD"
    args: {
      client_id: "<client_id>",
      client_secret: "<client_secret>",
      tenant_id: "<tenant_id>",
    }
  }
]

v2.0 엔드포인트의 경우:

gitlab_rails['omniauth_providers'] = [
  {
    "name" => "azure_activedirectory_v2",
    "label" => "공급자 이름", # 선택 사항, 로그인 버튼에 대한 기본값은 "Azure AD v2"
    "args" => {
      "client_id" => "<client_id>",
      "client_secret" => "<client_secret>",
      "tenant_id" => "<tenant_id>",
    }
  }
]

대체 Azure 클라우드를 사용하는 경우, args 섹션 아래에 base_azure_url을 구성합니다. 예를 들어 Azure Government Community Cloud (GCC)의 경우:

gitlab_rails['omniauth_providers'] = [
  {
    "name" => "azure_activedirectory_v2",
    "label" => "공급자 이름", # 선택 사항, 로그인 버튼에 대한 기본값은 "Azure AD v2"
    "args" => {
      "client_id" => "<client_id>",
      "client_secret" => "<client_secret>",
      "tenant_id" => "<tenant_id>",
      "base_azure_url" => "https://login.microsoftonline.us"
    }
  }
]

자체 컴파일한 설치의 경우:

v1.0 엔드포인트의 경우:

- { name: 'azure_oauth2',
    # label: '공급자 이름', # 로그인 버튼에 대한 선택 사항, 기본값은 "Azure AD"
    args: { client_id: '<client_id>',
            client_secret: '<client_secret>',
            tenant_id: '<tenant_id>' } }

v2.0 엔드포인트의 경우:

- { name: 'azure_activedirectory_v2',
    label: '공급자 이름', # 로그인 버튼에 대한 선택 사항, 기본값은 "Azure AD v2"
    args: { client_id: "<client_id>",
            client_secret: "<client_secret>",
            tenant_id: "<tenant_id>" } }

대체 Azure 클라우드를 사용하는 경우, args 섹션 아래에 base_azure_url을 구성합니다. 예를 들어 Azure Government Community Cloud (GCC)의 경우:

- { name: 'azure_activedirectory_v2',
    label: '공급자 이름', # 로그인 버튼에 대한 선택 사항, 기본값은 "Azure AD v2"
    args: { client_id: "<client_id>",
            client_secret: "<client_secret>",
            tenant_id: "<tenant_id>",
            base_azure_url: "https://login.microsoftonline.us" } }

또는 args 섹션에 OAuth 2.0 스코프를 위한 scope를 선택적으로 추가할 수 있습니다. 기본값은 openid profile email입니다.

구성 파일을 저장합니다.
Linux 패키지를 사용하여 설치한 경우 GitLab 다시 구성을 하거나, 자체 컴파일한 설치의 경우 GitLab 다시 시작을 합니다.
GitLab 로그인 페이지를 새로고침합니다. Microsoft 아이콘이 로그인 양식 아래에 표시됩니다.
아이콘을 선택합니다. Microsoft에 로그인하고 GitLab 애플리케이션을 승인합니다.

기존 GitLab 사용자가 새 Azure AD 계정에 연결하는 방법에 대한 정보는 기존 사용자를위한 OmniAuth 활성화를 참조하세요.

문제 해결

사용자 로그인 배너 메시지: Extern UID가 이미 사용 중입니다

로그인할 때 Extern UID가 이미 사용 중입니다라는 오류 메시지를 받을 수 있습니다.

이를 해결하려면 Rails console을 사용하여 해당 계정에 연결된 기존 사용자가 있는지 확인하세요:

extern_uid를 찾습니다:

id = Identity.where(extern_uid: '<extern_uid>')

해당 extern_uid에 연결된 사용자 이름을 찾기 위해 내용을 출력합니다:
```
pp id
```

extern_uid가 계정에 연결되어 있다면 해당 사용자 이름을 사용하여 로그인할 수 있습니다.

extern_uid가 어떤 사용자 이름에도 연결되어 있지 않다면, 이는 유령 레코드로 인한 삭제 오류일 수 있습니다.

다음 명령을 실행하여 extern uid를 해제하기 위해 해당 Identity를 삭제합니다:

 Identity.find('<id>').delete

Microsoft Azure를 OAuth 2.0 인증 제공자로 사용하기

OpenID Connect 프로토콜로 마이그레이션

Azure 애플리케이션 등록

API 권한 (범위) 추가

GitLab에서 Microsoft OAuth 활성화

문제 해결

사용자 로그인 배너 메시지: Extern UID가 이미 사용 중입니다

도움말

기능 사용 가능성과 제품 평가판

도움받기