Настройка BigQuery OAuth

Функция уровня Enterprise

В этом руководстве описана функция, доступная в тарифных планах Enterprise и Enterprise+ dbt platform. Если вы хотите узнать больше о наших тарифных планах уровня Enterprise, свяжитесь с нами по адресу sales@getdbt.com.

dbt platform поддерживает OAuth для BigQuery, обеспечивая дополнительный уровень безопасности для корпоративных пользователей dbt.

Настройка нативного OAuth BigQuery

Когда BigQuery OAuth включен для проекта dbt platform, все разработчики dbt platform должны аутентифицироваться в BigQuery для доступа к инструментам разработки, таким как Studio IDE.

Чтобы настроить BigQuery OAuth в dbt platform, администратор BigQuery должен:

1. Найти значение URI перенаправления в dbt platform.
2. Создать OAuth 2.0 client ID и secret для BigQuery в BigQuery.
3. Настроить подключение в dbt platform.

Чтобы использовать BigQuery в Studio IDE, всем разработчикам необходимо:

1. Пройти аутентификацию в BigQuery в разделе учетных данных своего профиля.

Найдите значение redirect URI

Для начала найдите redirect URI подключения, необходимый для настройки BigQuery OAuth. Для этого:

1. Перейдите к имени вашего аккаунта над иконкой профиля на левой боковой панели.
2. Выберите Account settings в меню.
3. В левой боковой панели выберите Connections.
4. Нажмите на подключение BigQuery.
5. Найдите поле Redirect URI в разделе Development OAuth. Скопируйте это значение в буфер обмена — оно понадобится позже.

Доступ к настройкам BigQuery OAuth в dbt

Создание client ID и secret для BigQuery OAuth 2.0

примечание

dbt platform автоматически запросит необходимые области доступа BigQuery в процессе OAuth. Настройка областей доступа на экране согласия OAuth для BigQuery необязательна и не требуется для подключения dbt platform к BigQuery. Необходимые области доступа запрашиваются и одобряются при аутентификации пользователей через OAuth.

Для начала необходимо создать идентификатор и секрет клиента для аутентификации в BigQuery. Эти идентификатор и секрет клиента будут храниться в dbt platform для управления OAuth-подключением между пользователями dbt platform и BigQuery.

1. В консоли BigQuery перейдите в API и сервисы и выберите Учетные данные:

Переход к учетным данным в BigQuery

На странице Credentials вы увидите существующие ключи, client ID и service accounts.

2. Настройте экран согласия OAuth, если вы еще этого не сделали.

3. Нажмите + Создать учетные данные в верхней части страницы и выберите Идентификатор клиента OAuth.

4. Заполните настройки идентификатора клиента. Разрешенные источники JavaScript не применяются.

5. Добавьте элемент в Разрешенные URI перенаправления и замените REDIRECT_URI значением, которое вы ранее скопировали в буфер обмена из раздела Настройки OAuth 2.0 подключения в dbt platform:

Параметр	Значение
Тип приложения	Веб-приложение
Name	dbt platform
Разрешенные URI перенаправления	REDIRECT_URI

6. Нажмите Создать, чтобы создать приложение BigQuery OAuth и просмотреть значения идентификатора и секрета клиента приложения. Эти значения доступны и после закрытия экрана приложения, поэтому вы сможете сохранить их и позже.

Создание приложения OAuth в BigQuery

Настройте подключение в dbt

Теперь, когда приложение OAuth настроено в BigQuery, необходимо добавить идентификатор и секрет клиента в dbt platform. Для этого:

1. Вернитесь на страницу деталей подключения, как описано в разделе Найдите значение redirect URI.
2. Добавьте client ID и secret из OAuth-приложения BigQuery в разделе OAuth 2.0 Settings.
3. Укажите token URI BigQuery. Значение по умолчанию — https://oauth2.googleapis.com/token.

Аутентификация в BigQuery

После настройки OAuth-приложения BigQuery для проекта dbt platform каждому пользователю dbt platform необходимо аутентифицироваться в BigQuery, чтобы использовать Studio IDE. Для этого:

1. Перейдите к имени своей учетной записи над значком профиля на левой боковой панели.
2. Выберите Настройки учетной записи в меню.
3. На левой боковой панели выберите Учетные данные.
4. Выберите проект из списка.
5. Убедитесь, что для параметра Метод аутентификации установлено значение Встроенный OAuth.
6. Выберите Подключиться к BigQuery.

Переход к настройкам учетной записи в платформе dbt.

Подключение учетной записи BigQuery.

После этого вы будете перенаправлены в BigQuery, где потребуется одобрить доступы к Google Drive, Cloud Platform и BigQuery, если только подключение не обладает меньшими привилегиями.

Запрос доступа к BigQuery

Выберите Разрешить. Вы будете перенаправлены обратно в dbt platform. Теперь вы прошли аутентификацию в BigQuery и можете начать пользоваться инструментами разработки dbt.

Настройка Workload Identity Federation для BigQuery Enterprise

Workload Identity Federation (WIF) позволяет рабочим нагрузкам приложений, выполняющимся за пределами dbt platform, действовать от имени сервисного аккаунта без необходимости управлять сервисными аккаунтами или другими ключами для сред развертывания. Следующие инструкции позволят вам настроить аутентификацию подключения BigQuery в dbt platform с помощью WIF. В настоящее время единственным поддерживаемым провайдером идентификации (IdP) является Microsoft Entra ID. Если вам требуется поддержка дополнительных IdP, свяжитесь с вашей аккаунт-командой.

1. Настройка Entra ID

Создайте приложение в Entra, через которое dbt будет запрашивать access tokens при аутентификации в BigQuery через workload identity pool:

1. На экране app registrations нажмите New registration.

2. Задайте приложению понятное имя.

3. Убедитесь, что Supported account types установлено в “Accounts in this organizational directory only (Org name - Single Tenant).”

4. Нажмите Register, чтобы открыть экран обзора приложения.

5. На странице обзора приложения выберите Expose an API в левом меню.

6. Нажмите Add рядом с Application ID URI. Поле заполнится автоматически.

7. Нажмите Save.

8. (Опционально) Чтобы включить claim sub в токены, выпускаемые этим приложением, настройте optional claims в Entra ID.
   Claim sub (subject) однозначно идентифицирует пользователя или service principal, для которого был выпущен токен.
   При настройке service account impersonation в GCP сопоставление Workload Identity Federation использует это значение sub для проверки идентичности вызывающего Entra-приложения.

9. (Опционально, но рекомендуется) Проверьте конфигурацию Entra ID, запросив токен:

   Выполните следующую команду, заменив <client-id>, <client-secret>, <application-ID-URI> и <tenant-id> на ваши реальные значения:

   curl -X POST -H "Content-Type: application/x-www-form-urlencoded" \
     -d 'client_id=<client-id> \
     &scope=<application-ID-URI>/.default \
     &client_secret=<client-secret> \
     &grant_type=client_credentials' \
     'https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token'

   Сообщить об ошибке в коде

   В ответе будет содержаться access_token. Вы можете декодировать этот токен с помощью сервиса jwt.io, чтобы посмотреть значение claim sub.

Workload Identity Federation использует машинный OAuth-поток (machine-to-machine), не требующий участия пользователя; поэтому redirect URI для приложения настраивать не нужно. Шаг 3 в этом разделе критически важен, так как он определяет audience для токенов, выпускаемых приложением, и сообщает workpool в GCP, имеет ли вызывающее приложение право доступа к ресурсам, защищенным этим workpool.

• Связанная документация: GCP — Prepare your external identity provider

2. Создайте Workpool и Workpool Provider в GCP

1. В главном меню GCP перейдите в IAM & Admin и выберите Workload Identity Federation (не путать с Work_force_ Identity Federation, расположенным рядом).
2. Если вы еще не создали workpool, нажмите Get started или создайте новый workpool (кнопка в верхней части страницы).
3. Задайте имя и описание workpool. Согласно документации GCP, для каждого окружения вне Google Cloud (development, staging, production и т.д.) следует создавать отдельный pool. Название workpool должно отражать это, чтобы его было легко идентифицировать в будущем.
4. При создании provider:
   • Установите тип provider в OpenID Connect (OIDC).
   • Задайте понятное имя provider, например Entra ID.
   • Укажите URL https://sts.windows.net/YOUR_TENANT_ID/. Его можно найти в самом токене, если декодировать его через jwt.io. Также сведения об ожидаемом URL издателя для Entra можно найти в документации GCP по WIF.
     • Замените YOUR_TENANT_ID идентификатором вашего арендатора.
     • Tenant (provider) ID можно найти в app registration, созданной в разделе 1; он называется Directory (tenant) ID и отображается на странице overview приложения.
   • В разделе Audiences выберите Allowed Audiences и укажите Application ID URI, заданный для вашего Entra ID приложения.
5. Нажмите Continue.
6. В разделе Configure provider attributes установите сопоставление google.subject → assertion.sub.
7. Нажмите Save.

3. Имперсонация сервисного аккаунта

Workpool либо использует service account, либо получает прямой доступ к ресурсам для определения того, к каким ресурсам может обращаться вызывающая сторона. Более подробную информацию см. в документации GCP. В нашей реализации мы выбрали подход с service account, так как он обеспечивает большую гибкость.

Если вы еще не сделали этого, создайте новый service account:

1. В главном меню выберите IAM & Admin.
2. Нажмите Service Accounts.
3. Нажмите Create service account. Google рекомендует создавать отдельный service account для каждой нагрузки.
4. Назначьте необходимые роли. По нашему опыту, роль BigQuery Admin является ролью по умолчанию с необходимым уровнем доступа.

После создания service account вернитесь к workpool, созданному на предыдущем шаге:

1. Нажмите Grant Access в верхней части страницы.

2. Выберите Grant access using Service Account Impersonation.

3. Выберите созданный service account.

4. В разделе Select Principals укажите subject в качестве Attribute Name, а в поле Attribute Value задайте значение claim sub из access token Entra ID.

    Получение значения sub

   Чтобы получить значение sub, запросите access token из Entra ID. Claim sub является постоянным для всех токенов, выпускаемых этим приложением:

   Выполните следующую команду, заменив <client-id>, <client-secret>, <application-ID-URI> и <tenant-id> на ваши реальные значения:

   curl -X POST -H "Content-Type: application/x-www-form-urlencoded" \
     -d 'client_id=<client-id> \
     &scope=<application-ID-URI>/.default \
     &client_secret=<client-secret> \
     &grant_type=client_credentials' \
     'https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token'

   Сообщить об ошибке в коде

   В ответе будет содержаться access_token. Вы можете декодировать этот токен с помощью сервиса jwt.io, чтобы посмотреть значение claim sub.

4. Настройка dbt

Чтобы настроить подключение BigQuery для использования аутентификации WIF в dbt platform, необходимо создать пользовательскую интеграцию OAuth с данными приложения Entra, используемого в качестве поставщика пула рабочих нагрузок в GCP. dbt platform:

1. Перейдите в Настройки учетной записи --> Интеграции.
2. Прокрутите вниз до раздела Пользовательские интеграции OAuth и создайте новую интеграцию.
3. Заполните все поля соответствующей информацией из вашего окружения IdP.
   • Application ID URI должен быть установлен в значение ожидаемого audience claim для токенов, выпускаемых Entra-приложением. Это будет тот же URI, который ожидает ваш workpool provider.
   • Добавлять URI перенаправления в приложение Entra не требуется.

5. Создайте подключения в dbt

Для начала создайте новое подключение в dbt platform:

1. Перейдите в Account settings --> Connections.
2. Нажмите New connection и выберите BigQuery в качестве типа подключения. Затем выберите BigQuery (не BigQuery (Legacy)).
3. В поле Deployment Environment Authentication Method выберите Workload Identity Federation.
4. Заполните Google Cloud Project ID и при необходимости другие параметры.
5. Выберите OAuth Configuration, созданную на предыдущем шаге, из выпадающего списка.
6. Настройте подключение для разработки:
   • BigQuery OAuth (рекомендуется).
     • Настраивается в том же подключении, что и WIF, в разделе OAuth2.0 settings
   • JSON сервисного аккаунта.
     • Необходимо создать отдельное подключение с конфигурацией Service JSON.

6. Настройте проект

Чтобы подключить новый проект к вашей WIF-конфигурации:

1. Перейдите в Account settings --> Projects.
2. Нажмите New project.
3. Укажите имя проекта и (опционально) путь к поддиректории, затем нажмите Continue.
4. Выберите Connection с WIF-конфигурацией.
5. Завершите настройку проекта, заполнив остальные необходимые поля.

7. Настройте deployment environment

Создайте новое или обновите существующее окружение для использования WIF-подключения.

После установки WIF-подключения для окружения в разделе Deployment credentials появятся два поля:

• Путь к поставщику пула рабочих нагрузок: Это поле обязательно для всех конфигураций WIF. Например:
• //iam.googleapis.com/projects/<numeric_project_id>/locations/global/workloadIdentityPools/<workpool_name>/providers/<workpool_providername>
• URL олицетворения сервисного аккаунта: Используется только в том случае, если вы настроили пул рабочих нагрузок на использование олицетворения сервисного аккаунта для доступа к ресурсам BigQuery (вместо предоставления пулу прямого доступа к ресурсам BigQuery). Например:
• https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/<serviceaccountemail>:generateAccessToken

Чтобы избежать ошибок из-за неверного регистра символов или опечаток, рекомендуем получать эти значения непосредственно из GCP, а не составлять их вручную:

1. В консоли GCP перейдите в IAM и администрирование > Workload Identity Federation.
2. Нажмите на свой пул удостоверений рабочих нагрузок, затем на поставщика, созданного для этой конфигурации.
3. Нажмите Скачать конфигурацию в верхней части страницы сведений о поставщике.
4. Откройте скачанный JSON-файл и скопируйте следующие значения:
   • Поле audience — вставьте в поле Путь к поставщику пула рабочих нагрузок в dbt.
   • Поле service_account_impersonation_url — вставьте в поле URL олицетворения сервисного аккаунта в dbt.

Если у вас еще нет задания на основе среды развертывания с подключением, настроенным для WIF, создайте его сейчас. Задав нужные настройки, запустите задание.

Часто задаваемые вопросы

Почему OAuth-приложение BigQuery требует доступ к Google Drive?

BigQuery поддерживает внешние таблицы как для личных файлов Google Drive, так и для общих файлов. Для получения дополнительной информации обратитесь к Создание внешних таблиц Google Drive.

Устранение неполадок

В следующем разделе приведены шаги по устранению распространенных проблем с подключениями BigQuery OAuth.

Сбой подключения после предоставления разрешений Google

При подключении учетной записи BigQuery вы можете успешно войти в Google и одобрить запрошенные разрешения, но затем увидеть страницу ошибки (например, 403 Account restricted) вместо возврата в dbt platform. Обычно отображается сообщение об ошибке сервера вместо страницы учетных данных, с которой вы начали.

Это может произойти, если ваша организация Google Workspace ограничивает доступ сторонних приложений к сервисам Google. Хотя Google позволил вам войти и просмотреть экран согласия, политика безопасности организации заблокировала заключительный этап выдачи учетных данных для dbt platform.

В этом разделе по устранению неполадок объясняется, почему это происходит, как решить проблему и что делать, если она возникает снова.

 1. Почему это влияет на BigQuery OAuth

Google делит области доступа OAuth на три уровня: неконфиденциальные, конфиденциальные и ограниченные. Приложения, которые запрашивают только неконфиденциальные области доступа (например, для обычного входа), как правило, работают без дополнительного одобрения администратора. Подключению BigQuery OAuth требуются области доступа, которые Google классифицирует как ограниченные, а они всегда требуют явного подтверждения доверия администратором независимо от политики вашей организации по умолчанию в отношении сторонних приложений.

Подключение BigQuery OAuth запрашивает следующие ограниченные области доступа:

• bigquery — Требуется для выполнения запросов и доступа к ресурсам BigQuery
• cloud-platform — Требуется для доступа к BigQuery между проектами и взаимодействия сервисов
• drive — Требуется для поддержки внешних таблиц BigQuery на основе Google Drive

Другие используемые вами приложения могут подключаться без этого этапа одобрения, поскольку они, вероятно, запрашивают только неконфиденциальные или конфиденциальные области доступа, на которые это ограничение не распространяется.

 2. Как решить проблему

Администратор Google Workspace должен пометить как доверенный идентификатор клиента OAuth, используемый вашим подключением BigQuery в dbt platform. Найдите этот идентификатор клиента в dbt platform в разделе Настройки учетной записи > Подключения > ваше подключение BigQuery > Настройки OAuth 2.0.

Получив идентификатор клиента, попросите администратора Google Workspace выполнить следующие действия:

1. Войти в Консоль администратора Google Workspace.
2. Перейти в Безопасность > Управление доступом и данными > Управление API > Управление доступом сторонних приложений.
3. Нажать Добавить приложение > Название приложения OAuth или идентификатор клиента.
4. Ввести идентификатор клиента из вашего подключения BigQuery в dbt platform.
5. Установить уровень доступа Доверенное.
6. Применить настройку к соответствующему организационному подразделению или ко всей организации.

После того как администратор выполнит эти действия, повторите попытку подключения к BigQuery со страницы учетных данных в dbt platform.

Подробнее см. в документации Google об управлении доступом сторонних приложений к данным Google Workspace.

 3. Если проблема сохраняется

Если подключение по-прежнему не удается после того, как администратор пометил клиент OAuth как доверенный в Google Workspace, попросите администратора проекта GCP проверить, не ограничивает ли политика организации Google Cloud использование внешних клиентов OAuth. Соответствующее ограничение — constraints/iam.allowedExternalOAuthClients.

Если ни один из этих шагов не помог решить проблему, обратитесь в службу поддержки dbt, указав приблизительное время неудачной попытки подключения и адрес электронной почты, который вы использовали для аутентификации в Google.

Нашли ошибку?

Создать GitHub Issue