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 Identity 플랫폼(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로 마이그레이션하려면 구성을 변경해야 합니다.

리눅스 패키지 (Omnibus)

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

gitlab_rails['omniauth_providers'] = [
  {
    name: "azure_oauth2",
    # label: "Provider name", # optional label for login button, defaults to "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: 'Provider name', # optional label for login button, defaults to "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로 마이그레이션하려면 구성을 변경해야 합니다.

리눅스 패키지 (Omnibus)

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

gitlab_rails['omniauth_providers'] = [
  {
 -    name: "azure_activedirectory_v2",
    # label: "Provider name", # optional label for login button, defaults to "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: 'Provider name', # optional label for login button, defaults to "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와 클라이언트 시크릿을 저장합니다. 클라이언트 시크릿은 한 번만 표시됩니다.
필요한 경우, 새 애플리케이션 시크릿을 생성할 수 있습니다.

client ID 및 client secret은 OAuth 2.0과 연관된 용어입니다. Microsoft 문서에서는 이 용어를 Application ID와 Application Secret로 지칭하기도 합니다.

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를 단일 사이인(Single Sign-On) 제공자로 추가합니다. 이렇게 하면 기존 GitLab 계정이 없는 사용자를 위해 즉시 계정 프로비저닝이 가능해집니다.

제공자 구성을 추가합니다. 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" } }

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

구성 파일을 저장합니다.
Linux 패키지를 사용하여 설치한 경우 GitLab을 다시 구성하거나, 직접 컴파일한 설치한 경우 GitLab을 다시 시작합니다.
GitLab 로그인 페이지를 새로 고칩니다. Microsoft 아이콘이 로그인 양식 아래에 표시되어야 합니다.
아이콘을 선택합니다. Microsoft에 로그인하고 Gitlab 애플리케이션을 허용합니다.

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

문제 해결

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

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

이 문제를 해결하려면 Rails 콘솔을 사용하여 해당 계정에 연결된 기존 사용자가 있는지 확인하십시오:

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가 이미 사용 중입니다

도움말

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

도움받기