Connect-IPPSSession

Модуль:

Exchange PowerShell

Этот командлет доступен только в модуле PowerShell Exchange Online. Дополнительные сведения см. в разделе Сведения о модуле PowerShell Exchange Online.

Используйте командлет Connect-IPPSSession в модуле PowerShell Exchange Online, чтобы подключиться к PowerShell для обеспечения соответствия требованиям безопасности & с помощью современной проверки подлинности. Командлет работает для учетных записей с поддержкой MFA или без MFA.

Примечание. Версия модуля 3.2.0 или более поздняя поддерживает режим REST API практически для всех командлетов PowerShell для обеспечения соответствия безопасности & (обычная проверка подлинности в WinRM на локальном компьютере не требуется для режима REST API). Дополнительные сведения см. в разделе Предварительные требования для модуля PowerShell Exchange Online.

Сведения о наборах параметров в разделе Синтаксис ниже см. В разделе Синтаксис командлета Exchange.

Синтаксис

Default (По умолчанию)

Connect-IPPSSession

    [[-ConnectionUri] <String>]
    [[-AzureADAuthorizationEndpointUri] <String>]
    [[-DelegatedOrganization] <String>]
    [[-PSSessionOption] <PSSessionOption>]
    [[-Prefix] <String>]
    [[-CommandName] <String[]>]
    [[-FormatTypeName] <String[]>]
    [-AccessToken <String>]
    [-AppId <String>]
    [-BypassMailboxAnchoring]
    [-Certificate <X509Certificate2>]
    [-CertificateFilePath <String>]
    [-CertificatePassword <SecureString>]
    [-CertificateThumbprint <String>]
    [-Credential <PSCredential>]
    [-DisableWAM]
    [-EnableErrorReporting]
    [-EnableSearchOnlySession]
    [-LogDirectoryPath <String>]
    [-LogLevel <LogLevel>]
    [-Organization <String>]
    [-ShowBanner]
    [-UserPrincipalName <String>]
    [-UseRPSSession]
    [<CommonParameters>]

Описание

Подробные инструкции по подключению, включая предварительные требования, см. в разделе Подключение к безопасности & соответствия требованиям PowerShell.

Примеры

Пример 1

Connect-IPPSSession -UserPrincipalName michelle@contoso.onmicrosoft.com

В этом примере выполняется подключение к PowerShell для обеспечения безопасности & соответствия требованиям, используя указанную учетную запись и современную проверку подлинности с MFA или без нее. В версии 3.2.0 или более поздней версии модуля мы подключаемся в режиме REST API, поэтому обычная проверка подлинности в WinRM не требуется на локальном компьютере.

Пример 2

Connect-IPPSSession -UserPrincipalName michelle@contoso.onmicrosoft.com -UseRPSSession

В этом примере выполняется подключение к PowerShell для обеспечения безопасности & соответствия требованиям, используя указанную учетную запись и современную проверку подлинности с MFA или без нее. В версии 3.2.0 или более поздней версии модуля мы подключаемся в удаленном режиме PowerShell, поэтому на локальном компьютере требуется обычная проверка подлинности в WinRM.

Пример 3

Connect-IPPSSession -AppId <%App_id%> -CertificateThumbprint <%Thumbprint string of certificate%> -Organization "contoso.onmicrosoft.com"

В этом примере выполняется подключение к PowerShell для обеспечения безопасности & соответствия требованиям в сценарии автоматического скрипта с помощью отпечатка сертификата.

Пример 4

Connect-IPPSSession -AppId <%App_id%> -Certificate <%X509Certificate2 object%> -Organization "contoso.onmicrosoft.com"

В этом примере выполняется подключение к PowerShell соответствия требованиям безопасности & в сценарии автоматического скрипта с помощью файла сертификата. Этот метод лучше всего подходит для сценариев, когда сертификат хранится на удаленных компьютерах и извлекается во время выполнения. Например, сертификат хранится в Azure Key Vault.

Параметры

-AccessToken

Применимо: Exchange Online

Примечание. Этот параметр доступен в модуле версии 3.8.0-Preview1 или более поздней.

Параметр AccessToken указывает веб-токен OAuth JSON (JWT), который используется для подключения к PowerShell для обеспечения безопасности и соответствия требованиям.

В зависимости от типа маркера доступа этот параметр необходимо использовать с параметрами Organization, DelegatedOrganization или UserPrincipalName.

Свойства параметров

Тип:	String
Default value:	None
Поддерживаются подстановочные знаки:	False
DontShow:	False

Наборы параметров

(All)

Position:	Named
Обязательно:	False
Значение из конвейера:	False
Значение из конвейера по имени свойства:	False
Значение из оставшихся аргументов:	False

-AppId

Применимо: Exchange Online

Параметр AppId указывает идентификатор приложения субъекта-службы, который используется для проверки подлинности на основе сертификатов (CBA). Допустимым значением является GUID идентификатора приложения (субъекта-службы). Например, 36ee4c6c-0812-40a2-b820-b22ebd02bce3.

Дополнительные сведения см. в статье Проверка подлинности только для приложений для автоматических сценариев в модуле Exchange Online PowerShell.

Свойства параметров

Тип:	String
Default value:	None
Поддерживаются подстановочные знаки:	False
DontShow:	False

Наборы параметров

(All)

Position:	Named
Обязательно:	False
Значение из конвейера:	False
Значение из конвейера по имени свойства:	False
Значение из оставшихся аргументов:	False

-AzureADAuthorizationEndpointUri

Применимо: Exchange Online

Параметр AzureADAuthorizationEndpointUri указывает конечную точку авторизации Microsoft Entra, которая может выдавать маркеры доступа OAuth2. Поддерживаются следующие среды PowerShell и связанные значения:

• Безопасность & соответствия Требованиям PowerShell в Microsoft 365 или Microsoft 365 GCC: не используйте этот параметр. Обязательное значение — https://login.microsoftonline.com/organizations, но это также значение по умолчанию, поэтому использовать этот параметр не нужно.
• Безопасность & соответствия требованиям PowerShell в Office 365 управляется 21Vianet:https://login.chinacloudapi.cn/organizations
• Безопасность & соответствия PowerShell в Microsoft GCC High или Microsoft DoD: https://login.microsoftonline.us/organizations

Значение URI, заканчивающееся на /organizations , разрешает использовать только рабочие или учебные учетные записи. Старое значение URI, заканчивающееся на/common, по-прежнему работает, но может предложить выбрать между личная учетная запись и рабочей или учебной учетной записью. Мы рекомендуем использовать /organizations значение URI в корпоративных сценариях, в которых следует исключить учетные записи потребителей.

Если вы используете параметр UserPrincipalName, вам не нужно использовать параметр AzureADAuthorizationEndpointUri для MFA или федеративных пользователей в средах, которым он обычно требуется (UserPrincipalName или AzureADAuthorizationEndpointUri является обязательным; ОК для использования обоих вариантов).

Свойства параметров

Тип:	String
Default value:	None
Поддерживаются подстановочные знаки:	False
DontShow:	False

Наборы параметров

(All)

Position:	1
Обязательно:	False
Значение из конвейера:	False
Значение из конвейера по имени свойства:	False
Значение из оставшихся аргументов:	False

-BypassMailboxAnchoring

Применимо: Exchange Online

Параметр BypassMailboxAnchoring обходит использование указания привязки почтового ящика. С этим параметром не нужно указывать значение.

Свойства параметров

Тип:	SwitchParameter
Default value:	None
Поддерживаются подстановочные знаки:	False
DontShow:	False

Наборы параметров

(All)

Position:	Named
Обязательно:	False
Значение из конвейера:	False
Значение из конвейера по имени свойства:	False
Значение из оставшихся аргументов:	False

-Certificate

Применимо: Exchange Online

Параметр Certificate указывает сертификат, используемый для проверки подлинности на основе сертификата (CBA). Допустимым значением является значение объекта X509Certificate2 сертификата.

Не используйте этот параметр с параметрами CertificateFilePath или CertificateThumbprint.

Дополнительные сведения о CBA см. в статье Проверка подлинности только для приложений для автоматических сценариев в модуле Exchange Online PowerShell.

Свойства параметров

Тип:	X509Certificate2
Default value:	None
Поддерживаются подстановочные знаки:	False
DontShow:	False

Наборы параметров

(All)

Position:	Named
Обязательно:	False
Значение из конвейера:	False
Значение из конвейера по имени свойства:	False
Значение из оставшихся аргументов:	False

-CertificateFilePath

Применимо: Exchange Online

Параметр CertificateFilePath указывает сертификат, используемый для CBA. Допустимым значением является полный открытый путь к файлу сертификата. Используйте параметр CertificatePassword с этим параметром.

Не используйте этот параметр с параметрами Certificate или CertificateThumbprint.

Дополнительные сведения о CBA см. в статье Проверка подлинности только для приложений для автоматических сценариев в модуле Exchange Online PowerShell.

Свойства параметров

Тип:	String
Default value:	None
Поддерживаются подстановочные знаки:	False
DontShow:	False

Наборы параметров

(All)

Position:	Named
Обязательно:	False
Значение из конвейера:	False
Значение из конвейера по имени свойства:	False
Значение из оставшихся аргументов:	False

-CertificatePassword

Применимо: Exchange Online

Параметр CertificatePassword указывает пароль, необходимый для открытия файла сертификата при использовании параметра CertificateFilePath для идентификации сертификата, используемого для CBA.

В качестве значения для этого параметра можно использовать следующие методы:

• (ConvertTo-SecureString -String '<password>' -AsPlainText -Force).
• Перед выполнением этой команды сохраните пароль как переменную (например, $password = Read-Host "Enter password" -AsSecureString), а затем используйте переменную ($password) в качестве значения.
• (Get-Credential).password запрос на безопасный ввод пароля при выполнении этой команды.

Дополнительные сведения о CBA см. в статье Проверка подлинности только для приложений для автоматических сценариев в модуле Exchange Online PowerShell.

Примечание. Использование команды ConvertTo-SecureString для локального хранения пароля сертификата не позволяет использовать метод безопасного подключения для сценариев автоматизации. Использование команды Get-Credential для безопасного запроса пароля сертификата не подходит для сценариев автоматизации. Другими словами, на самом деле нет автоматизированного и безопасного способа подключения с помощью локального сертификата.

Свойства параметров

Тип:	SecureString
Default value:	None
Поддерживаются подстановочные знаки:	False
DontShow:	False

Наборы параметров

(All)

Position:	Named
Обязательно:	False
Значение из конвейера:	False
Значение из конвейера по имени свойства:	False
Значение из оставшихся аргументов:	False

-CertificateThumbprint

Применимо: Exchange Online

Параметр CertificateThumbprint указывает сертификат, используемый для CBA. Допустимое значение — это значение отпечатка сертификата. Например, 83213AEAC56D61C97AEE5C1528F4AC5EBA7321C1.

Не используйте этот параметр с параметрами Certificate или CertificateFilePath.

Примечание. Параметр CertificateThumbprint поддерживается только в Microsoft Windows.

Дополнительные сведения о CBA см. в статье Проверка подлинности только для приложений для автоматических сценариев в модуле Exchange Online PowerShell.

Свойства параметров

Тип:	String
Default value:	None
Поддерживаются подстановочные знаки:	False
DontShow:	False

Наборы параметров

(All)

Position:	Named
Обязательно:	False
Значение из конвейера:	False
Значение из конвейера по имени свойства:	False
Значение из оставшихся аргументов:	False

-CommandName

Применимо: Exchange Online

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

Свойства параметров

Тип:	String[]
Default value:	None
Поддерживаются подстановочные знаки:	False
DontShow:	False

Наборы параметров

(All)

Position:	5
Обязательно:	False
Значение из конвейера:	False
Значение из конвейера по имени свойства:	False
Значение из оставшихся аргументов:	False

-ConnectionUri

Применимо: Exchange Online

Параметр ConnectionUri указывает конечную точку подключения для сеанса PowerShell. Поддерживаются следующие среды PowerShell и связанные значения:

• Безопасность & соответствия Требованиям PowerShell в Microsoft 365 или Microsoft 365 GCC: не используйте этот параметр. Обязательное значение — https://ps.compliance.protection.outlook.com/powershell-liveid/, но это также значение по умолчанию, поэтому использовать этот параметр не нужно.
• Безопасность & соответствия требованиям PowerShell в Office 365 управляется 21Vianet:https://ps.compliance.protection.partner.outlook.cn/powershell-liveid
• Безопасность & соответствия Требованиям PowerShell в Microsoft GCC High: https://ps.compliance.protection.office365.us/powershell-liveid/
• Безопасность & соответствия Требованиям PowerShell в Microsoft DoD: https://l5.ps.compliance.protection.office365.us/powershell-liveid/

Свойства параметров

Тип:	String
Default value:	None
Поддерживаются подстановочные знаки:	False
DontShow:	False

Наборы параметров

(All)

Position:	0
Обязательно:	False
Значение из конвейера:	False
Значение из конвейера по имени свойства:	False
Значение из оставшихся аргументов:	False

-Credential

Применимо: Exchange Online

Параметр Credential указывает имя пользователя и пароль, используемые для подключения к Exchange Online PowerShell. Как правило, этот параметр используется в сценариях, или если требуется указывать различные учетные данные, которые предоставляют необходимые разрешения. Не используйте этот параметр для учетных записей, использующих многофакторную проверку подлинности (MFA).

Перед выполнением команды Connect-IPPSSession сохраните имя пользователя и пароль в переменной (например, $UserCredential = Get-Credential). Затем используйте имя переменной ($UserCredential) для этого параметра.

После выполнения команды Connect-IPPSSession ключ пароля в переменной очищается.

Свойства параметров

Тип:	PSCredential
Default value:	None
Поддерживаются подстановочные знаки:	False
DontShow:	False

Наборы параметров

(All)

Position:	Named
Обязательно:	False
Значение из конвейера:	False
Значение из конвейера по имени свойства:	False
Значение из оставшихся аргументов:	False

-DelegatedOrganization

Применимо: Exchange Online

Параметр DelegatedOrganization указывает организацию клиента, которой вы хотите управлять (например, contosoelectronics.onmicrosoft.com). Этот параметр работает, только если организация-клиент согласилась на делегированное управление с помощью программы CSP.

После успешной проверки подлинности командлеты в этом сеансе сопоставляются с клиентской организацией, а все операции в этом сеансе выполняются в организации клиента.

Примечания.

• Используйте основной домен .onmicrosoft.com делегированной организации для значения этого параметра.
• С этим параметром необходимо использовать параметр AzureADAuthorizationEndpointUri.

Свойства параметров

Тип:	String
Default value:	None
Поддерживаются подстановочные знаки:	False
DontShow:	False

Наборы параметров

(All)

Position:	2
Обязательно:	False
Значение из конвейера:	False
Значение из конвейера по имени свойства:	False
Значение из оставшихся аргументов:	False

-DisableWAM

Применимо: Exchange Online

Примечание. Этот параметр доступен в модуле версии 3.7.2-Preview1 или более поздней.

Параметр DisableWAM отключает диспетчер веб-учетных записей (WAM). С этим параметром не нужно указывать значение.

Если во время входа возникают проблемы, связанные с WAM, этот параметр можно использовать для отключения WAM.

Свойства параметров

Тип:	SwitchParameter
Default value:	None
Поддерживаются подстановочные знаки:	False
DontShow:	False

Наборы параметров

(All)

Position:	Named
Обязательно:	False
Значение из конвейера:	False
Значение из конвейера по имени свойства:	False
Значение из оставшихся аргументов:	False

-EnableErrorReporting

Применимо: Exchange Online

Примечание. Этот параметр доступен в модуле версии 3.8.1-Preview1 или более поздней.

Параметр EnableErrorReporting указывает, следует ли включать отчеты об ошибках. С этим параметром не нужно указывать значение.

Свойства параметров

Тип:	SwitchParameter
Default value:	None
Поддерживаются подстановочные знаки:	False
DontShow:	False

Наборы параметров

(All)

Position:	Named
Обязательно:	False
Значение из конвейера:	False
Значение из конвейера по имени свойства:	False
Значение из оставшихся аргументов:	False

-EnableSearchOnlySession

Применимо: Exchange Online

Примечание. Этот параметр доступен в модуле версии 3.9.0-Preview1 или более поздней.

Параметр EnableSearchOnlySession указывает, следует ли включать определенные командлеты обнаружения электронных данных и связанные командлеты, которые подключаются к другим службам Microsoft 365. С этим параметром не нужно указывать значение.

Свойства параметров

Тип:	SwitchParameter
Default value:	None
Поддерживаются подстановочные знаки:	False
DontShow:	False

Наборы параметров

(All)

Position:	Named
Обязательно:	False
Значение из конвейера:	False
Значение из конвейера по имени свойства:	False
Значение из оставшихся аргументов:	False

-FormatTypeName

Применимо: Exchange Online

Параметр FormatTypeName указывает формат выходных данных командлета.

Свойства параметров

Тип:	String[]
Default value:	None
Поддерживаются подстановочные знаки:	False
DontShow:	False

Наборы параметров

(All)

Position:	6
Обязательно:	False
Значение из конвейера:	False
Значение из конвейера по имени свойства:	False
Значение из оставшихся аргументов:	False

-LogDirectoryPath

Применимо: Exchange Online

Примечание. Этот параметр доступен в модуле версии 3.8.1-Preview1 или более поздней.

Параметр LogDirectoryPath указывает расположение файлов журнала. Расположение по умолчанию — %TMP%\EXOCmdletTelemetry\EXOCmdletTelemetry-yyyymmdd-hhmmss.csv.

Если указать пользовательское расположение и имя файла, содержащие пробелы, заключите значение в кавычки (").

Свойства параметров

Тип:	String
Default value:	None
Поддерживаются подстановочные знаки:	False
DontShow:	False

Наборы параметров

(All)

Position:	Named
Обязательно:	False
Значение из конвейера:	False
Значение из конвейера по имени свойства:	False
Значение из оставшихся аргументов:	False

-LogLevel

Применимо: Exchange Online

Примечание. Этот параметр доступен в модуле версии 3.8.1-Preview1 или более поздней.

Параметр LogLevel указывает уровень ведения журнала. Допустимые значения: Default и All.

Свойства параметров

Тип:	LogLevel
Default value:	None
Поддерживаются подстановочные знаки:	False
DontShow:	False

Наборы параметров

(All)

Position:	Named
Обязательно:	False
Значение из конвейера:	False
Значение из конвейера по имени свойства:	False
Значение из оставшихся аргументов:	False

-Organization

Применимо: Exchange Online

Параметр Organization указывает организацию при подключении с помощью CBA. Для значения этого параметра необходимо использовать основной домен .onmicrosoft.com организации.

Дополнительные сведения о CBA см. в статье Проверка подлинности только для приложений для автоматических сценариев в модуле Exchange Online PowerShell.

Свойства параметров

Тип:	String
Default value:	None
Поддерживаются подстановочные знаки:	False
DontShow:	False

Наборы параметров

(All)

Position:	Named
Обязательно:	False
Значение из конвейера:	False
Значение из конвейера по имени свойства:	False
Значение из оставшихся аргументов:	False

-Prefix

Применимо: Exchange Online

Параметр Prefix задает текстовое значение, добавляемое к именам командлетов PowerShell для обеспечения безопасности & соответствия требованиям при подключении. Например, Get-ComplianceCase становится Get-ContosoComplianceCase при использовании значения Contoso для этого параметра.

• Значение префикса не может содержать пробелы или специальные символы, такие как символы подчеркивания или звездочки.
• Нельзя использовать значение префикса EXO. Это значение зарезервировано для девяти эксклюзивных командлетов Get-EXO* , встроенных в модуль.
• Параметр Prefix влияет только на импортированные имена командлетов Security & Compliance. Он не влияет на имена командлетов, встроенных в модуль (например, Disconnect-ExchangeOnline).

Свойства параметров

Тип:	String
Default value:	None
Поддерживаются подстановочные знаки:	False
DontShow:	False

Наборы параметров

(All)

Position:	4
Обязательно:	False
Значение из конвейера:	False
Значение из конвейера по имени свойства:	False
Значение из оставшихся аргументов:	False

-PSSessionOption

Применимо: Exchange Online

Примечание. Этот параметр не работает в подключениях REST API.

Параметр PSSessionOption указывает параметры удаленного сеанса PowerShell для использования в подключении к PowerShell для обеспечения безопасности & соответствия требованиям. Этот параметр работает только в том случае, если вы также используете параметр UseRPSSession в той же команде.

Сохраните выходные данные команды New-PSSessionOption в переменной (например, $PSOptions = New-PSSessionOption <Settings>) и используйте имя переменной в качестве значения для этого параметра (например, $PSOptions).

Свойства параметров

Тип:	PSSessionOption
Default value:	None
Поддерживаются подстановочные знаки:	False
DontShow:	False

Наборы параметров

(All)

Position:	3
Обязательно:	False
Значение из конвейера:	False
Значение из конвейера по имени свойства:	False
Значение из оставшихся аргументов:	False

-ShowBanner

Применимо: Exchange Online

Примечание. Этот параметр доступен в модуле версии 3.2.0 или более поздней.

Параметр ShowBanner отображает или скрывает сообщение баннера, которое отображается при запуске Connect-IPPSSession. С этим параметром не нужно указывать значение.

• Чтобы отобразить баннер, вам не нужно использовать этот параметр (баннер отображается по умолчанию).
• Чтобы скрыть баннер, используйте следующий синтаксис: -ShowBanner:$false.

Свойства параметров

Тип:	SwitchParameter
Default value:	None
Поддерживаются подстановочные знаки:	False
DontShow:	False

Наборы параметров

(All)

Position:	Named
Обязательно:	False
Значение из конвейера:	False
Значение из конвейера по имени свойства:	False
Значение из оставшихся аргументов:	False

-UserPrincipalName

Применимо: Exchange Online

Параметр UserPrincipalName указывает учетную запись, которую вы хотите использовать для подключения (например, navin@contoso.onmicrosoft.com). Использование этого параметра позволяет пропустить ввод имени пользователя в запросе на современные учетные данные проверки подлинности (вам будет предложено ввести пароль).

Если вы используете параметр UserPrincipalName, вам не нужно использовать параметр AzureADAuthorizationEndpointUri для MFA или федеративных пользователей в средах, которым он обычно требуется (UserPrincipalName или AzureADAuthorizationEndpointUri является обязательным; ОК для использования обоих вариантов).

Свойства параметров

Тип:	String
Default value:	None
Поддерживаются подстановочные знаки:	False
DontShow:	False

Наборы параметров

(All)

Position:	Named
Обязательно:	False
Значение из конвейера:	False
Значение из конвейера по имени свойства:	False
Значение из оставшихся аргументов:	False

-UseRPSSession

Применимо: Exchange Online

Примечание. Этот параметр доступен в модуле версии 3.2.0-Preview3 или более поздней.

Примечание. Удаленные подключения PowerShell к PowerShell для обеспечения безопасности & соответствия требованиям устарели. Дополнительные сведения см. в разделе Прекращение поддержки удаленной оболочки PowerShell в разделе Безопасность и соответствие требованиям PowerShell.

Параметр UseRPSSession позволяет подключаться к PowerShell для обеспечения безопасности & соответствия требованиям, используя традиционный удаленный доступ PowerShell ко всем командлетам. С этим параметром не нужно указывать значение.

Если этот параметр не используется, для подключения используется режим REST API, поэтому обычная проверка подлинности в WinRM не требуется.

Свойства параметров

Тип:	SwitchParameter
Default value:	False
Поддерживаются подстановочные знаки:	False
DontShow:	False

Наборы параметров

(All)

Position:	Named
Обязательно:	False
Значение из конвейера:	False
Значение из конвейера по имени свойства:	False
Значение из оставшихся аргументов:	False

CommonParameters

Этот командлет поддерживает общие параметры: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction и -WarningVariable. Дополнительные сведения см. в статье about_CommonParameters.