Краткое руководство: Вход пользователей в демонстрационное мобильное приложение

В этом кратком руководстве вы скачаете и запустите пример кода, демонстрирующий, как в приложении Android реализовать вход пользователей и получить токен доступа для вызова API Microsoft Graph.

Приложения должны быть представлены объектом приложения в Microsoft Entra ID, чтобы платформа удостоверений Майкрософт могла предоставлять токены вашему приложению.

В этом кратком руководстве вы скачаете и запустите пример кода, демонстрирующий, как нативное приложение для iOS или macOS может авторизовать пользователей и получить токен доступа для вызова API Microsoft Graph.

Краткое руководство относится как к приложениям iOS, так и к приложениям macOS. Некоторые шаги необходимы только для приложений iOS и будут указаны таким образом.

• Зарегистрируйте новое приложение в центре администрирования Microsoft Entra с помощью следующей конфигурации. Дополнительные сведения см. в разделе Регистрация приложения.
  • Имя: identity-client-web-app
  • Поддерживаемые типы учетных записей: учетные записи в любом каталоге организации (любой каталог Microsoft Entra — Multitenant) и личные учетные записи Microsoft (например, Skype, Xbox)
• Android Studio
• Android 16+

• Зарегистрируйте новое приложение в центре администрирования Microsoft Entra с помощью следующей конфигурации. Дополнительные сведения см. в разделе Регистрация приложения.
  • Имя: identity-client-web-app
  • Поддерживаемые типы учетных записей: учетные записи в этом каталоге организации (только один клиент)
• XCode 10+
• iOS 10+
• macOS 10.12+

1. В разделе Управление выберите Проверка подлинности>Добавить платформу>Android.

2. Введите имя пакета проекта в зависимости от загруженного выше типа.

   • Пример Java — com.azuresamples.msalandroidapp
   • Пример Kotlin — com.azuresamples.msalandroidkotlinapp

3. В разделе Хэш подписи области настройки приложения Android выберите Создание хэша подписи для разработки и скопируйте команду KeyTool в вашу командную строку.

   • KeyTool. exe устанавливается как часть пакета средств разработки Java (JDK). Необходимо также установить средство OpenSSL для выполнения команды KeyTool. Для получения дополнительных сведений см. документацию Android по созданию ключа.

4. Введите хэш подписи, созданный с помощью KeyTool.

5. Выберите "Настроить и сохранить конфигурацию MSAL", которая отображается в области конфигурации Android, чтобы можно было ввести ее при последующей настройке приложения.

6. Нажмите кнопку Готово.

1. В разделе Управлениевыберите Аутентификация>Добавить платформу>iOS.
2. Введите идентификатор пакета для вашего приложения. Идентификатор пакета — это уникальная строка, которая однозначно идентифицирует приложение, например com.<yourname>.identitysample.MSALMacOS. Запишите используемое значение. Обратите внимание, что конфигурация iOS также применима к приложениям macOS.
3. Выберите Настроить и сохраните сведения о конфигурации MSAL для использования позже в этом кратком руководстве.
4. Нажмите кнопку Готово.

• Java: скачайте код.
• Kotlin: скачайте код.

Скачивание примера проекта

• Скачайте пример кода для iOS
• Скачайте пример кода для macOS

Установка зависимостей

1. Извлеките ZIP-файл.
2. В окне терминала перейдите в папку с скачанным примером кода и запустите pod install, чтобы установить последнюю библиотеку MSAL.

1. На панели проекта Android Studio перейдите к app\src\main\res.

2. Щелкните правой кнопкой мыши res и выберите New (Создать) >Directory (Каталог). Введите raw имя нового каталога и нажмите кнопку "ОК".

3. В приложении>src>main>res>raw перейдите в JSON-файл с именем auth_config_single_account.json и вставьте сохраненную ранее конфигурацию MSAL.

   Под URI перенаправления вставьте:

     "account_mode" : "SINGLE",
   

   Теперь файл конфигурации должен выглядеть примерно так:

   {
     "client_id": "00001111-aaaa-bbbb-3333-cccc4444",
     "authorization_user_agent": "WEBVIEW",
     "redirect_uri": "msauth://com.azuresamples.msalandroidapp/00001111%cccc4444%3D",
     "broker_redirect_uri_registered": false,
     "account_mode": "SINGLE",
     "authorities": [
       {
         "type": "AAD",
         "audience": {
           "type": "AzureADandPersonalMicrosoftAccount",
           "tenant_id": "common"
         }
       }
     ]
   }
   

4. Откройте файл /app/src/main/AndroidManifest.xml.

5. Найдите плейсхолдер:

   • enter_the_signature_hash и замените его на хэш подписи, который вы создали ранее, когда добавляли URL-адрес перенаправления платформы.

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

Запуск примера приложения

Выберите эмулятор или физическое устройство из раскрывающегося списка доступных устройств Android Studio и запустите приложение.

Пример приложения запускается на экране Single Account Mode (Режим единой учетной записи). Область по умолчанию, user.read, предоставляется по умолчанию и используется при чтении данных собственного профиля во время вызова API Microsoft Graph. URL-адрес для вызова Microsoft Graph API предоставляется по умолчанию. При необходимости их можно изменить.

Используйте меню приложения для переключения между режимами одной и нескольких учетных записей.

В режиме одной учетной записи войдите с помощью рабочей или домашней учетной записи:

1. Выберите Get graph data interactively (Получить данные графов в интерактивном режиме ), чтобы запросить у пользователя учетные данные. Вы увидите выходные данные вызова API Microsoft Graph в нижней части экрана.
2. После входа в систему выберите Get graph data silently (Получить данные графов без уведомления), чтобы вызвать Microsoft Graph API, не запрашивая у пользователя учетные данные снова. Вы увидите выходные данные вызова API Microsoft Graph в нижней части экрана.

В режиме нескольких учетных записей можно повторить те же действия. Кроме того, можно удалить учетную запись для входа. При этом кэшированные токены для этой учетной записи также удаляются.

Если вы выбрали вариант 1 выше, можно пропустить эти действия.

1. Откройте проект в XCode.

2. Измените ViewController.swift и замените строку, начиная с "let kClientID" следующим фрагментом кода. Не забудьте обновить значение kClientID с помощью идентификатора клиента, сохраненного при регистрации приложения ранее в этом кратком руководстве:

   let kClientID = "Enter_the_Application_Id_Here"
   

3. Если вы создаете приложение для национальных облаков Microsoft Entra, замените строки, содержащие "let kGraphEndpoint" и "let kAuthority", на правильные конечные точки. Для глобального доступа используйте значения по умолчанию:

   let kGraphEndpoint = "https://graph.microsoft.com/"
   let kAuthority = "https://login.microsoftonline.com/common"
   

4. Другие конечные точки задокументированы здесь. Например, чтобы запустить быстрый запуск с Microsoft Entra Germany, используйте следующее:

   let kGraphEndpoint = "https://graph.microsoft.de/"
   let kAuthority = "https://login.microsoftonline.de/common"
   

5. Откройте параметры проекта. В разделе Identity введите идентификатор пакета .

6. Щелкните правой кнопкой мыши Info.plist и выберите Открыть как>исходный код.

7. В корневом узле dict замените Enter_the_bundle_Id_Here на идентификатор пакета , который вы использовали на портале. Обратите внимание на префикс msauth. в строке.

   <key>CFBundleURLTypes</key>
   <array>
      <dict>
         <key>CFBundleURLSchemes</key>
         <array>
            <string>msauth.Enter_the_Bundle_Id_Here</string>
         </array>
      </dict>
   </array>
   

8. Создайте и запустите приложение!

Код разделен на фрагменты, демонстрирующие, как записывать приложение MSAL для одной и нескольких учетных записей. Файлы кода организованы следующим образом:

Теперь мы рассмотрим эти файлы подробнее и вызовем код, относящийся к MSAL, в каждом из них

Перейдите к учебнику по Android, с помощью которого вы создадите приложение Android, получающее маркер доступа от платформы удостоверений Майкрософт и использующее его для вызова API Microsoft Graph.

Перейдите к пошаговому руководству, в котором вы создаете приложение iOS или macOS, которое получает маркер доступа из платформы удостоверений Майкрософт и использует его для вызова API Microsoft Graph.

• Android Studio.

• Поток пользователя. Дополнительные сведения см. в создании потоков пользователей самообслуживания для приложений в внешних арендаторах. Этот поток пользователя можно использовать для нескольких приложений.
• Добавление приложения в поток пользователя

• Пакет SDK для .NET 7.0
• Visual Studio 2022 с установленной рабочей нагрузкой MAUI:
  • инструкции для Windows
  • Инструкции для macOS

• Xcode.

Чтобы указать тип приложения для регистрации приложения, выполните следующие действия.

1. В разделе Управление выберите Проверка подлинности.
2. На странице конфигураций платформы выберите "Добавить платформу" и выберите вариант Android.
3. Введите имя пакета проекта. Если вы скачали пример кода, это значение равно com.azuresamples.msaldelegatedandroidkotlinsampleapp.
4. В разделе хэша подписи окна «Настройка приложения Android» выберите «Создать хэш подписи для разработки». Этот хэш будет меняться в зависимости от среды разработки. Скопируйте и выполните команду KeyTool для вашей операционной системы в терминале.
5. Введите хэш подписи, созданный с помощью KeyTool.
6. Выберите и настройте.
7. Скопируйте конфигурацию MSAL из области конфигурации Android и сохраните ее для последующей настройки приложения.
8. Нажмите кнопку Готово.

Включение публичного клиентского потока

Чтобы определить приложение как общедоступный клиент, выполните следующие действия.

1. В разделе Управление выберите Проверка подлинности.

2. В разделе "Дополнительные параметры" для параметра "Разрешить общедоступные потоки клиентов" нажмите кнопку "Да".

3. Выберите Сохранить, чтобы сохранить изменения.

Чтобы указать тип приложения для регистрации приложения, выполните следующие действия.

1. В разделе Управление выберите Проверка подлинности.
2. На странице конфигураций платформы выберите "Добавить платформу", а затем выберите пункт "Мобильные и классические приложения".
3. Для URI перенаправления введите msal{client_id}://auth. Убедитесь, что значение {client_id} соответствует значению, указанному в регистрации вашего приложения. Выберите и настройте.
4. Выберите Сохранить, чтобы сохранить изменения.

Чтобы указать тип приложения для регистрации приложения, выполните следующие действия.

1. В разделе Управление выберите Проверка подлинности.
2. На странице конфигураций платформы выберите "Добавить платформу" и выберите параметр iOS или macOS .
3. Введите идентификатор пакета проекта. Если вы скачали пример кода, это значение равно com.microsoft.identitysample.ciam.MSALiOS.
4. Выберите "Настроить и сохранить конфигурацию MSAL ", которая отображается в области конфигурации iOS или macOS , чтобы можно было ввести ее при настройке приложения позже.
5. Нажмите кнопку Готово.

Включение общедоступного потока клиента

Чтобы определить приложение как общедоступный клиент, выполните следующие действия.

1. В разделе Управление выберите Проверка подлинности.

2. В разделе "Дополнительные параметры" для параметра "Разрешить общедоступные потоки клиентов" нажмите кнопку "Да".

3. Выберите Сохранить, чтобы сохранить изменения.

После регистрации приложения ему предоставляется разрешение User.Read. Однако, поскольку клиент является внешним клиентом, сами пользователи клиента не могут согласиться с этим разрешением. Вы, как администратор клиента, должны предоставить это разрешение от имени всех пользователей в клиенте:

1. На странице Регистрация приложений выберите созданное приложение (например, ciam-client-app), чтобы открыть страницу обзора.

2. В разделе Управление выберите Разрешения API.

   1. Выберите "Предоставить согласие администратора" для <имени> клиента, а затем нажмите кнопку "Да".
   2. Выберите Обновить, а затем убедитесь, что предоставлено для <имя вашего арендатора> отображается в разделе Состояние для разрешения.

После регистрации приложения ему предоставляется разрешение User.Read. Однако, поскольку клиент является внешним клиентом, сами пользователи клиента не могут согласиться с этим разрешением. Вы, как администратор клиента, должны предоставить это разрешение от имени всех пользователей в клиенте:

1. На странице Регистрация приложений выберите созданное приложение (например, ciam-client-app), чтобы открыть страницу обзора.

2. В разделе Управление выберите Разрешения API.

   1. Выберите "Предоставить согласие администратора" для <имени> клиента, а затем нажмите кнопку "Да".
   2. Выберите Обновить, а затем убедитесь, что предоставлено для <имя вашего арендатора> отображается в разделе Состояние для разрешения.

После регистрации приложения ему предоставляется разрешение User.Read. Однако, поскольку клиент является внешним клиентом, сами пользователи клиента не могут согласиться с этим разрешением. Вы, как администратор клиента, должны предоставить это разрешение от имени всех пользователей в клиенте:

1. На странице Регистрация приложений выберите созданное приложение (например, ciam-client-app), чтобы открыть страницу обзора.

2. В разделе Управление выберите Разрешения API.

   1. Выберите "Предоставить согласие администратора" для <имени> клиента, а затем нажмите кнопку "Да".
   2. Выберите Обновить, а затем убедитесь, что предоставлено для <имя вашего арендатора> отображается в разделе Состояние для разрешения.

Чтобы получить пример приложения, можно клонировать его из GitHub или скачать его в виде файла .zip.

• Чтобы клонировать пример, откройте командную строку и перейдите к месту создания проекта и введите следующую команду:

  git clone https://github.com/Azure-Samples/ms-identity-ciam-browser-delegated-android-sample
  

Чтобы получить пример кода приложения .NET MAUI Android, скачайте файл .zip или клонируйте пример приложения .NET MAUI Android из GitHub, выполнив следующую команду:

git clone https://github.com/Azure-Samples/ms-identity-ciam-dotnet-tutorial.git

Чтобы получить пример приложения, можно клонировать его из GitHub или скачать его в виде файла .zip.

• Чтобы клонировать пример, откройте командную строку и перейдите к месту создания проекта и введите следующую команду:

  git clone https://github.com/Azure-Samples/ms-identity-ciam-browser-delegated-ios-sample.git
  

Чтобы включить проверку подлинности и доступ к ресурсам Microsoft Graph, настройте пример, выполнив следующие действия.

1. В Android Studio откройте клонируемый проект.

2. Откройте файл /app/src/main/res/raw/auth_config_ciam.json .

3. Найдите плейсхолдер:

   • Замените Enter_the_Application_Id_Here на идентификатор приложения (идентификатор клиента) того приложения, которое вы зарегистрировали ранее.
   • Enter_the_Redirect_Uri_Here и замените его на значение redirect_uri в файле конфигурации библиотеки проверки подлинности Майкрософт (MSAL), который вы скачали ранее, когда вы добавляли URL-адрес перенаправления платформы.
   • Enter_the_Tenant_Subdomain_Here и замените его на поддомен каталога (домен клиента). Например, если основной домен клиента — это contoso.onmicrosoft.com, используйте contoso. Если вы не знаете поддомен клиента, узнайте, как прочитать сведения о клиенте.

4. Откройте файл /app/src/main/AndroidManifest.xml.

5. Найдите плейсхолдер:

   • ENTER_YOUR_SIGNATURE_HASH_HERE и замените его хэшом подписи , созданным ранее при добавлении URL-адреса перенаправления платформы.

6. Откройте файл /app/src/main/java/com/azuresamples/msaldelegatedandroidkotlinsampleapp/MainActivity.kt .

7. Найдите свойство с именем scopes и задайте области, записанные в разделе "Предоставление согласия администратора". Если вы не записали сферы, вы можете оставить этот список сфер пустым.

   private const val scopes = "" // Developers should set the respective scopes of their Microsoft Graph resources here. For example, private const val scopes = "api://{clientId}/{ToDoList.Read} api://{clientId}/{ToDoList.ReadWrite}"
   

Вы настроили приложение, и оно готово к запуску.

1. В Visual Studio откройте файл ms-identity-ciam-dotnet-tutorial-main/1-Authentication/2-sign-in-maui/appsettings.json.
2. Найдите заполнитель:
   1. Enter_the_Tenant_Subdomain_Here и замените его на поддомен каталога (домен клиента). Например, если основной домен клиента — это contoso.onmicrosoft.com, используйте contoso. Если у вас нет названия арендатора, узнайте, как посмотреть сведения об арендаторе.
   2. Замените Enter_the_Application_Id_Here на идентификатор приложения (идентификатор клиента) того приложения, которое вы зарегистрировали ранее.
3. В Visual Studio откройте ms-identity-ciam-dotnet-tutorial-main/1-Authentication/2-sign-in-maui/Platforms/Android/AndroidManifest.xml.
4. Найдите заполнитель:
   1. Замените Enter_the_Application_Id_Here на идентификатор приложения (идентификатор клиента) того приложения, которое вы зарегистрировали ранее.

Чтобы включить проверку подлинности и доступ к ресурсам Microsoft Graph, настройте пример, выполнив следующие действия.

1. В Xcode откройте клонируемый проект.

2. Откройте файл /MSALiOS/Configuration.swift .

3. Найдите плейсхолдер:

   • Замените Enter_the_Application_Id_Here на идентификатор приложения (идентификатор клиента) того приложения, которое вы зарегистрировали ранее.
   • Enter_the_Redirect_URI_Here и замените его на значение kRedirectUri в скачанном ранее файле конфигурации библиотеки аутентификации Microsoft (MSAL) при добавлении URL-адреса перенаправления платформы.
   • Enter_the_Protected_API_Scopes_Here и замените его областями, записанными в разделе "Предоставление согласия администратора". Если вы не записали сферы, вы можете оставить этот список сфер пустым.
   • Enter_the_Tenant_Subdomain_Here и замените его на поддомен каталога (домен клиента). Например, если основной домен клиента — это contoso.onmicrosoft.com, используйте contoso. Если вы не знаете поддомен клиента, узнайте, как прочитать сведения о клиенте.

Вы настроили приложение, и оно готово к запуску.

Чтобы создать и запустить приложение, выполните следующие действия.

1. На панели инструментов выберите приложение в меню конфигураций запуска.

2. В меню целевого устройства выберите устройство, на которое вы хотите запустить приложение.

   Если у вас нет устройств, необходимо создать виртуальное устройство Android для использования эмулятора Android или подключить физическое устройство Android.

3. Нажмите кнопку Запустить.

4. Выберите "Получить маркер" в интерактивном режиме , чтобы запросить маркер доступа.

5. Если вы выберете API — выполните GET для вызова защищенного веб-API ASP.NET Core, появится сообщение об ошибке.

Дополнительные сведения о вызове защищенного веб-API см. в следующих шагах.

Приложения .NET MAUI предназначены для работы на нескольких операционных системах и устройствах. Вам потребуется выбрать целевой объект, с помощью которого вы хотите протестировать и отладить приложение.

Установите целевой объект отладки на панели инструментов Visual Studio на устройство, с которым требуется выполнить отладку и тестирование. Следующие шаги демонстрируют, как установить целевой объект отладки на Android.

1. Выберите целевой объект отладки раскрывающегося списка.
2. Выберите эмуляторы Android.
3. Выберите устройство эмулятора.

Запустите приложение, нажав клавишу F5 или нажав кнопку воспроизведения в верхней части Visual Studio.

1. Теперь можно протестировать пример приложения .NET MAUI Android. После запуска приложения окно приложения Android появится в эмуляторе:

   

2. На Android-устройстве, в появившемся окне, нажмите кнопку Войти. Откроется окно браузера, и вам будет предложено войти.

   

   Во время входа вам будет предложено предоставить различные разрешения (разрешить приложению доступ к данным). После успешного входа и согласия на экране приложения отображается главная страница.

   

Чтобы создать и запустить приложение, выполните следующие действия.

1. Чтобы создать и запустить код, выберите Запустить в меню Product в Xcode. После успешной сборки Xcode запустит пример приложения в симуляторе.
2. Выберите "Получить маркер" в интерактивном режиме , чтобы запросить маркер доступа.
3. Если вы выберете API — выполните GET для вызова защищенного веб-API ASP.NET Core, появится сообщение об ошибке.

Дополнительные сведения о вызове защищенного веб-API см. в следующих шагах.

• Авторизуйте пользователей и вызовите защищенный веб-интерфейс API в образце приложения Android (Kotlin).

• Настройте фирменную символику по умолчанию.
• Настроить вход с помощью Google.

• Авторизуйте пользователей и вызовите защищённый веб-интерфейс API в примере приложения iOS (Swift).