Connect-HaloAPI
This page has been generated from the HaloAPI PowerShell module source. To make changes please edit the appropriate PowerShell source file.
SYNOPSIS
Creates a new connection to a Halo instance.
SYNTAX
Client Credentials (Default)
Connect-HaloAPI [-URL <Uri>] [-ClientID <String>] [-ClientSecret <String>] [-Scopes <String[]>]
[-Tenant <String>] [-AdditionalHeaders <Hashtable>] [-UseKeyVault <Boolean>] [-SecretName <String>]
[-VaultName <String>] [-SaveToKeyVault <Boolean>] [-UseManagedIdentity] [-MaxRetries <Int32>] [-NoConfirm]
[-ProgressAction <ActionPreference>] [<CommonParameters>]
Authorisation Code
Connect-HaloAPI -URL <Uri> -ClientID <String> [-Scopes <String[]>] [-Tenant <String>] [-Interactive]
[-RedirectURI <Uri>] [-LoginTimeout <Int32>] [-AdditionalHeaders <Hashtable>] [-MaxRetries <Int32>]
[-NoConfirm] [-ProgressAction <ActionPreference>] [<CommonParameters>]
DESCRIPTION
Creates a new connection to a Halo instance and stores this in a PowerShell Session.
EXAMPLES
EXAMPLE 1
Connect-HaloAPI -URL "https://example.halopsa.com" -ClientId "c9534241-dde9-4d04-9d45-32b1fbff22ed" -ClientSecret "14c0c9af-2db1-48ab-b29c-51975df4afa2-739e4ef2-9aad-4fe9-b486-794feca48ea8" -Scopes "all" -Tenant "demo" -VaultName "MyVault" -SaveToKeyVault $true
This logs into Halo using the Client Credentials authorisation flow and saves the secrets to the specified Azure Key Vault for future use.
EXAMPLE 2
Connect-HaloAPI -URL "https://example.halopsa.com" -ClientId "c9534241-dde9-4d04-9d45-32b1fbff22ed" -Tenant "demo" -Interactive
This opens a browser to sign in to Halo with your own agent account using the Authorisation Code flow with PKCE. No client secret is needed: create the API application in Halo with the "Authorisation Code (Native Application)" authentication method and add "http://localhost:8400/" as a redirect URI. Requests then run with the signed-in agent's permissions and the token is refreshed automatically.
PARAMETERS
-URL
The URL of the Halo instance to connect to. Not required if UseKeyVault is set to $true.
Type: Uri
Parameter Sets: Client Credentials
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
Type: Uri
Parameter Sets: Authorisation Code
Aliases:
Required: True
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-ClientID
The Client ID for the application configured in Halo. Not required if UseKeyVault is set to $true.
Type: String
Parameter Sets: Client Credentials
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
Type: String
Parameter Sets: Authorisation Code
Aliases:
Required: True
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-ClientSecret
The Client Secret for the application configured in Halo. Not required if UseKeyVault is set to $true.
Type: String
Parameter Sets: Client Credentials
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Scopes
The API scopes to request, if this isn't passed the scope is assumed to be "all". Pass a string or array of strings. Limited by the scopes granted to the application in Halo.
Type: String[]
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: All
Accept pipeline input: False
Accept wildcard characters: False
-Tenant
The tenant name required for hosted Halo instances.
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Interactive
Sign in through the browser with your own Halo agent account (Authorisation Code flow with PKCE) instead of using a client secret.
Type: SwitchParameter
Parameter Sets: Authorisation Code
Aliases:
Required: True
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
-RedirectURI
The redirect URI configured on the Halo API application. A temporary local listener is started on this address to receive the sign-in response.
Type: Uri
Parameter Sets: Authorisation Code
Aliases:
Required: False
Position: Named
Default value: Http://localhost:8400/
Accept pipeline input: False
Accept wildcard characters: False
-LoginTimeout
How long to wait, in seconds, for the browser sign-in to complete.
Type: Int32
Parameter Sets: Authorisation Code
Aliases:
Required: False
Position: Named
Default value: 300
Accept pipeline input: False
Accept wildcard characters: False
-AdditionalHeaders
Hashtable containing additional parameters to be sent with each request.
Type: Hashtable
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-UseKeyVault
If $true, retrieve parameters from Azure Key Vault. If $false, use parameters passed to function.
Type: Boolean
Parameter Sets: Client Credentials
Aliases:
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
-SecretName
The name of the secret in the Azure Key Vault.
Type: String
Parameter Sets: Client Credentials
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-VaultName
The name of the Azure Key Vault.
Type: String
Parameter Sets: Client Credentials
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-SaveToKeyVault
If $true, save parameters to Azure Key Vault. If $false or not specified, do not save parameters.
Type: Boolean
Parameter Sets: Client Credentials
Aliases:
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
-UseManagedIdentity
When set to $true, uses a Managed Identity to connect to Azure Key Vault instead of interactive login.
Type: SwitchParameter
Parameter Sets: Client Credentials
Aliases:
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
-MaxRetries
The maximum number of times to retry requests before giving up.
Type: Int32
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: 10
Accept pipeline input: False
Accept wildcard characters: False
-NoConfirm
Don't return a boolean to confirm the connection status.
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
CommonParameters
This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.