Connect-IPPSSession
This cmdlet is available only in the Exchange Online PowerShell module. For more information, see About the Exchange Online PowerShell module.
Use the Connect-IPPSSession cmdlet in the Exchange Online PowerShell module to connect to Security & Compliance PowerShell using modern authentication. The cmdlet works for MFA or non-MFA enabled accounts.
Note: Version 3.2.0 or later of the module supports REST API mode for virtually all Security & Compliance PowerShell cmdlets (Basic authentication in WinRM on the local computer isn't required for REST API mode). For more information, see Prerequisites for the Exchange Online PowerShell module.
For information about the parameter sets in the Syntax section below, see Exchange cmdlet syntax.
Syntax
Connect-IPPSSession
[[-ConnectionUri] <String>]
[[-AzureADAuthorizationEndpointUri] <String>]
[[-DelegatedOrganization] <String>]
[[-PSSessionOption] <PSSessionOption>]
[[-Prefix] <String>]
[[-CommandName] <String[]>]
[[-FormatTypeName] <String[]>]
[-AppId <String>]
[-BypassMailboxAnchoring]
[-Certificate <X509Certificate2>]
[-CertificateFilePath <String>]
[-CertificatePassword <SecureString>]
[-CertificateThumbprint <String>]
[-Credential <PSCredential>]
[-Organization <String>]
[-UserPrincipalName <String>]
[-UseRPSSession]
[<CommonParameters>]Description
For detailed connection instructions, including prerequisites, see Connect to Security & Compliance PowerShell.
Examples
Example 1
Connect-IPPSSession -UserPrincipalName michelle@contoso.onmicrosoft.comThis example connects to Security & Compliance PowerShell using the specified account and modern authentication, with or without MFA. In v3.2.0 or later of the module, we're connecting in REST API mode, so Basic authentication in WinRM isn't required on the local computer.
Example 2
Connect-IPPSSession -UserPrincipalName michelle@contoso.onmicrosoft.com -UseRPSSessionThis example connects to Security & Compliance PowerShell using the specified account and modern authentication, with or without MFA. In v3.2.0 or later of the module, we're connecting in remote PowerShell mode, so Basic authentication in WinRM is required on the local computer.
Example 3
Connect-IPPSSession -AppId <%App_id%> -CertificateThumbprint <%Thumbprint string of certificate%> -Organization "contoso.onmicrosoft.com"This example connects to Security & Compliance PowerShell in an unattended scripting scenario using a certificate thumbprint.
Example 4
Connect-IPPSSession -AppId <%App_id%> -Certificate <%X509Certificate2 object%> -Organization "contoso.onmicrosoft.com"This example connects to Security & Compliance PowerShell in an unattended scripting scenario using a certificate file. This method is best suited for scenarios where the certificate is stored in remote machines and fetched at runtime. For example, the certificate is stored in the Azure Key Vault.
Parameters
-AppId
The AppId parameter specifies the application ID of the service principal that's used in certificate based authentication (CBA). A valid value is the GUID of the application ID (service principal). For example, 36ee4c6c-0812-40a2-b820-b22ebd02bce3.
For more information, see App-only authentication for unattended scripts in the Exchange Online PowerShell module.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
| Applies to: | Exchange Online |
-AzureADAuthorizationEndpointUri
The AzureADAuthorizationEndpointUri parameter specifies the Microsoft Entra Authorization endpoint that can issue OAuth2 access tokens. The following PowerShell environments and related values are supported:
- Security & Compliance PowerShell in Microsoft 365 or Microsoft 365 GCC: Don't use this parameter. The required value is
https://login.microsoftonline.com/common, but that's also the default value, so you don't need to use this parameter. - Security & Compliance PowerShell in Office 365 operated by 21Vianet:
https://login.chinacloudapi.cn/common - Security & Compliance PowerShell in Microsoft GCC High or Microsoft DoD:
https://login.microsoftonline.us/common
If you use the UserPrincipalName parameter, you don't need to use the AzureADAuthorizationEndpointUri parameter for MFA or federated users in environments that normally require it (UserPrincipalName or AzureADAuthorizationEndpointUri is required; OK to use both).
| Type: | String |
| Position: | 1 |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
| Applies to: | Exchange Online |
-BypassMailboxAnchoring
The BypassMailboxAnchoring switch bypasses the use of the mailbox anchoring hint. You don't need to specify a value with this switch.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
| Applies to: | Exchange Online |
-Certificate
The Certificate parameter specifies the certificate that's used for certificate-based authentication (CBA). A valid value is the X509Certificate2 object value of the certificate.
Don't use this parameter with the CertificateFilePath or CertificateThumbprint parameters.
For more information about CBA, see App-only authentication for unattended scripts in the Exchange Online PowerShell module.
| Type: | X509Certificate2 |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
| Applies to: | Exchange Online |
-CertificateFilePath
The CertificateFilePath parameter specifies the certificate that's used for CBA. A valid value is the complete public path to the certificate file. Use the CertificatePassword parameter with this parameter.
Don't use this parameter with the Certificate or CertificateThumbprint parameters.
For more information about CBA, see App-only authentication for unattended scripts in the Exchange Online PowerShell module.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
| Applies to: | Exchange Online |
-CertificatePassword
The CertificatePassword parameter specifies the password that's required to open the certificate file when you use the CertificateFilePath parameter to identify the certificate that's used for CBA.
You can use the following methods as a value for this parameter:
(ConvertTo-SecureString -String '<password>' -AsPlainText -Force).- Before you run this command, store the password as a variable (for example,
$password = Read-Host "Enter password" -AsSecureString), and then use the variable ($password) for the value. (Get-Credential).passwordto be prompted to enter the password securely when you run this command.
For more information about CBA, see App-only authentication for unattended scripts in the Exchange Online PowerShell module.
Note: Using a ConvertTo-SecureString command to store the password of the certificate locally defeats the purpose of a secure connection method for automation scenarios. Using a Get-Credential command to prompt you for the password of the certificate securely isn't ideal for automation scenarios. In other words, there's really no automated and secure way to connect using a local certificate.
| Type: | SecureString |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
| Applies to: | Exchange Online |
-CertificateThumbprint
The CertificateThumbprint parameter specifies the certificate that's used for CBA. A valid value is the thumbprint value of the certificate. For example, 83213AEAC56D61C97AEE5C1528F4AC5EBA7321C1.
Don't use this parameter with the Certificate or CertificateFilePath parameters.
Note: The CertificateThumbprint parameter is supported only in Microsoft Windows.
For more information about CBA, see App-only authentication for unattended scripts in the Exchange Online PowerShell module.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
| Applies to: | Exchange Online |
-CommandName
The CommandName parameter specifies the comma separated list of commands to import into the session. Use this parameter for applications or scripts that use a specific set of cmdlets. Reducing the number of cmdlets in the session helps improve performance and reduces the memory footprint of the application or script.
| Type: | String[] |
| Position: | 5 |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
| Applies to: | Exchange Online |
-ConnectionUri
The ConnectionUri parameter specifies the connection endpoint for the PowerShell session. The following PowerShell environments and related values are supported:
- Security & Compliance PowerShell in Microsoft 365 or Microsoft 365 GCC: Don't use this parameter. The required value is
https://ps.compliance.protection.outlook.com/powershell-liveid/, but that's also the default value, so you don't need to use this parameter. - Security & Compliance PowerShell in Office 365 operated by 21Vianet:
https://ps.compliance.protection.partner.outlook.cn/powershell-liveid - Security & Compliance PowerShell in Microsoft GCC High:
https://ps.compliance.protection.office365.us/powershell-liveid/ - Security & Compliance PowerShell in Microsoft DoD:
https://l5.ps.compliance.protection.office365.us/powershell-liveid/
| Type: | String |
| Position: | 0 |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
| Applies to: | Exchange Online |
-Credential
The Credential parameter specifies the username and password that's used to connect to Exchange Online PowerShell. Typically, you use this parameter in scripts or when you need to provide different credentials that have the required permissions. Don't use this parameter for accounts that use multi-factor authentication (MFA).
Before you run the Connect-IPPSSession command, store the username and password in a variable (for example, $UserCredential = Get-Credential). Then, use the variable name ($UserCredential) for this parameter.
After the Connect-IPPSSession command is complete, the password key in the variable is emptied.
| Type: | PSCredential |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
| Applies to: | Exchange Online |
-DelegatedOrganization
The DelegatedOrganization parameter specifies the customer organization that you want to manage (for example, contosoelectronics.onmicrosoft.com). This parameter works only if the customer organization has agreed to your delegated management via the CSP program.
After you successfully authenticate, the cmdlets in this session are mapped to the customer organization, and all operations in this session are done on the customer organization.
Notes:
- Use the primary .onmicrosoft.com domain of the delegated organization for the value of this parameter.
- You must use the AzureADAuthorizationEndpointUri parameter with this parameter.
| Type: | String |
| Position: | 2 |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
| Applies to: | Exchange Online |
-FormatTypeName
The FormatTypeName parameter specifies the output format of the cmdlet.
| Type: | String[] |
| Position: | 6 |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
| Applies to: | Exchange Online |
-Organization
The Organization parameter specifies the organization when you connect using CBA. You must use the primary .onmicrosoft.com domain of the organization for the value of this parameter.
For more information about CBA, see App-only authentication for unattended scripts in the Exchange Online PowerShell module.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
| Applies to: | Exchange Online |
-Prefix
The Prefix parameter specifies a text value to add to the names of Security & Compliance PowerShell cmdlets when you connect. For example, Get-ComplianceCase becomes Get-ContosoComplianceCase when you use the value Contoso for this parameter.
- The Prefix value can't contain spaces or special characters like underscores or asterisks.
- You can't use the Prefix value EXO. That value is reserved for the nine exclusive Get-EXO* cmdlets that are built into the module.
- The Prefix parameter affects only imported Security & Compliance cmdlet names. It doesn't affect the names of cmdlets that are built into the module (for example, Disconnect-ExchangeOnline).
| Type: | String |
| Position: | 4 |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
| Applies to: | Exchange Online |
-PSSessionOption
Note: This parameter doesn't work in REST API connections.
The PSSessionOption parameter specifies the remote PowerShell session options to use in your connection to Security & Compliance PowerShell. This parameter works only if you also use the UseRPSSession switch in the same command.
Store the output of the New-PSSessionOption command in a variable (for example, $PSOptions = New-PSSessionOption <Settings>), and use the variable name as the value for this parameter (for example, $PSOptions).
| Type: | PSSessionOption |
| Position: | 3 |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
| Applies to: | Exchange Online |
-UserPrincipalName
The UserPrincipalName parameter specifies the account that you want to use to connect (for example, navin@contoso.onmicrosoft.com). Using this parameter allows you to skip entering a username in the modern authentication credentials prompt (you're prompted to enter a password).
If you use the UserPrincipalName parameter, you don't need to use the AzureADAuthorizationEndpointUri parameter for MFA or federated users in environments that normally require it (UserPrincipalName or AzureADAuthorizationEndpointUri is required; OK to use both).
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
| Applies to: | Exchange Online |
-UseRPSSession
This parameter is available in version 3.2.0 or later of the module.
Note: Remote PowerShell connections to Security & Compliance are deprecated. For more information, see Deprecation of Remote PowerShell in Security and Compliance PowerShell.
The UseRPSSession switch allows you to connect to Security & Compliance PowerShell using traditional remote PowerShell access to all cmdlets. You don't need to specify a value with this switch.
This switch requires that Basic authentication is enabled in WinRM on the local computer. For more information, see Turn on Basic authentication in WinRM.
If you don't use this switch, Basic authentication in WinRM is not required.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | False |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
| Applies to: | Exchange Online |
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for