From 223388dbfd4db365e864f941d29efbd7bc5a799e Mon Sep 17 00:00:00 2001 From: John Duprey Date: Thu, 8 Dec 2022 21:13:46 -0500 Subject: [PATCH 1/2] Auth API + Docs --- Docs/Get-DuoAuthEnrollmentStatus.md | 73 +++++ Docs/Get-DuoAuthLogo.md | 58 ++++ Docs/Get-DuoAuthStatus.md | 59 ++++ Docs/New-DuoAuthEnrollment.md | 75 +++++ Docs/Send-DuoAuth.md | 265 ++++++++++++++++++ Docs/Send-DuoAuthPing.md | 45 +++ Docs/Send-DuoPreAuth.md | 131 +++++++++ Docs/Test-DuoAuthApi.md | 44 +++ .../Private/Invoke/Invoke-DuoRequest.ps1 | 31 +- .../Auth API/Get-DuoAuthEnrollmentStatus.ps1 | 55 ++++ .../Public/Auth API/Get-DuoAuthLogo.ps1 | 44 +++ .../Public/Auth API/Get-DuoAuthStatus.ps1 | 46 +++ .../Public/Auth API/New-DuoAuthEnrollment.ps1 | 49 ++++ DuoSecurity/Public/Auth API/Send-DuoAuth.ps1 | 134 +++++++++ .../Public/Auth API/Send-DuoAuthPing.ps1 | 36 +++ .../Public/Auth API/Send-DuoPreAuth.ps1 | 74 +++++ .../Public/Auth API/Test-DuoAuthApi.ps1 | 35 +++ README.md | 21 +- 18 files changed, 1267 insertions(+), 8 deletions(-) create mode 100644 Docs/Get-DuoAuthEnrollmentStatus.md create mode 100644 Docs/Get-DuoAuthLogo.md create mode 100644 Docs/Get-DuoAuthStatus.md create mode 100644 Docs/New-DuoAuthEnrollment.md create mode 100644 Docs/Send-DuoAuth.md create mode 100644 Docs/Send-DuoAuthPing.md create mode 100644 Docs/Send-DuoPreAuth.md create mode 100644 Docs/Test-DuoAuthApi.md create mode 100644 DuoSecurity/Public/Auth API/Get-DuoAuthEnrollmentStatus.ps1 create mode 100644 DuoSecurity/Public/Auth API/Get-DuoAuthLogo.ps1 create mode 100644 DuoSecurity/Public/Auth API/Get-DuoAuthStatus.ps1 create mode 100644 DuoSecurity/Public/Auth API/New-DuoAuthEnrollment.ps1 create mode 100644 DuoSecurity/Public/Auth API/Send-DuoAuth.ps1 create mode 100644 DuoSecurity/Public/Auth API/Send-DuoAuthPing.ps1 create mode 100644 DuoSecurity/Public/Auth API/Send-DuoPreAuth.ps1 create mode 100644 DuoSecurity/Public/Auth API/Test-DuoAuthApi.ps1 diff --git a/Docs/Get-DuoAuthEnrollmentStatus.md b/Docs/Get-DuoAuthEnrollmentStatus.md new file mode 100644 index 0000000..dfdab4a --- /dev/null +++ b/Docs/Get-DuoAuthEnrollmentStatus.md @@ -0,0 +1,73 @@ +--- +external help file: DuoSecurity-help.xml +Module Name: DuoSecurity +online version: https://duo.com/docs/authapi#/enroll_status +schema: 2.0.0 +--- + +# Get-DuoAuthEnrollmentStatus + +## SYNOPSIS +Duo Auth Enrollment Status + +## SYNTAX + +``` +Get-DuoAuthEnrollmentStatus [-UserId] [-ActivationCode] [] +``` + +## DESCRIPTION +Check whether a user has completed enrollment. + +## EXAMPLES + +### EXAMPLE 1 +``` +Get-DuoAuthEnrollmentStatus -UserId SOMEUSERID -ActivationCode SOMEACTIVATIONCODE +``` + +## PARAMETERS + +### -UserId +ID of the user. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: user_id + +Required: True +Position: 1 +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### -ActivationCode +Activation code, as returned from /enroll. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: activation_code + +Required: True +Position: 2 +Default value: None +Accept pipeline input: True (ByPropertyName) +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](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +## OUTPUTS + +## NOTES + +## RELATED LINKS + +[https://duo.com/docs/authapi#/enroll_status](https://duo.com/docs/authapi#/enroll_status) + diff --git a/Docs/Get-DuoAuthLogo.md b/Docs/Get-DuoAuthLogo.md new file mode 100644 index 0000000..0e63b64 --- /dev/null +++ b/Docs/Get-DuoAuthLogo.md @@ -0,0 +1,58 @@ +--- +external help file: DuoSecurity-help.xml +Module Name: DuoSecurity +online version: https://duo.com/docs/authapi#/logo +schema: 2.0.0 +--- + +# Get-DuoAuthLogo + +## SYNOPSIS +Duo Auth Logo + +## SYNTAX + +``` +Get-DuoAuthLogo [-FilePath] [] +``` + +## DESCRIPTION +The /logo endpoint provides a programmatic way to retrieve your stored logo. + +## EXAMPLES + +### EXAMPLE 1 +``` +Get-DuoAuthLogo -FilePath ./logo.png +``` + +## PARAMETERS + +### -FilePath +Where to save the logo + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: True +Position: 1 +Default value: None +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](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +## OUTPUTS + +## NOTES + +## RELATED LINKS + +[https://duo.com/docs/authapi#/logo](https://duo.com/docs/authapi#/logo) + diff --git a/Docs/Get-DuoAuthStatus.md b/Docs/Get-DuoAuthStatus.md new file mode 100644 index 0000000..31962c4 --- /dev/null +++ b/Docs/Get-DuoAuthStatus.md @@ -0,0 +1,59 @@ +--- +external help file: DuoSecurity-help.xml +Module Name: DuoSecurity +online version: https://duo.com/docs/authapi#/auth_status +schema: 2.0.0 +--- + +# Get-DuoAuthStatus + +## SYNOPSIS +Duo API Auth Status + +## SYNTAX + +``` +Get-DuoAuthStatus [-TxId] [] +``` + +## DESCRIPTION +The /auth_status endpoint "long-polls" for the next status update from the authentication process for a given transaction. +That is to say, if no status update is available at the time the request is sent, it will wait until there is an update before returning a response. + +## EXAMPLES + +### EXAMPLE 1 +``` +Get-DuoAuthStatus -TxId 66cc8d20-fdfa-41bc-8b74-1a3b095d55f7 +``` + +## PARAMETERS + +### -TxId +The transaction ID of the authentication attempt, as returned by the /auth endpoint. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: True +Position: 1 +Default value: None +Accept pipeline input: True (ByPropertyName) +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](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +## OUTPUTS + +## NOTES + +## RELATED LINKS + +[https://duo.com/docs/authapi#/auth_status](https://duo.com/docs/authapi#/auth_status) + diff --git a/Docs/New-DuoAuthEnrollment.md b/Docs/New-DuoAuthEnrollment.md new file mode 100644 index 0000000..12f6155 --- /dev/null +++ b/Docs/New-DuoAuthEnrollment.md @@ -0,0 +1,75 @@ +--- +external help file: DuoSecurity-help.xml +Module Name: DuoSecurity +online version: https://duo.com/docs/adminapi#add-administrative-unit +schema: 2.0.0 +--- + +# New-DuoAuthEnrollment + +## SYNOPSIS +Duo Auth Enrollment + +## SYNTAX + +``` +New-DuoAuthEnrollment [[-Username] ] [[-ValidSecs] ] [] +``` + +## DESCRIPTION +The /enroll endpoint provides a programmatic way to enroll new users with Duo two-factor authentication. +It creates the user in Duo and returns a code (as a QR code) that Duo Mobile can scan with its built-in camera. +Scanning the QR code adds the user's account to the app so that they receive and respond to Duo Push login requests. + +## EXAMPLES + +### EXAMPLE 1 +``` +New-DuoAuthEnrollment +``` + +## PARAMETERS + +### -Username +Username for the created user. +If not given, a random username will be assigned and returned. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: 1 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ValidSecs +Seconds for which the activation code will remain valid. +Default: 86400 (one day). + +```yaml +Type: Int32 +Parameter Sets: (All) +Aliases: + +Required: False +Position: 2 +Default value: 0 +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](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +## OUTPUTS + +## NOTES +General notes + +## RELATED LINKS diff --git a/Docs/Send-DuoAuth.md b/Docs/Send-DuoAuth.md new file mode 100644 index 0000000..c91c7ba --- /dev/null +++ b/Docs/Send-DuoAuth.md @@ -0,0 +1,265 @@ +--- +external help file: DuoSecurity-help.xml +Module Name: DuoSecurity +online version: https://duo.com/docs/authapi#/auth +schema: 2.0.0 +--- + +# Send-DuoAuth + +## SYNOPSIS +Duo Auth + +## SYNTAX + +### Username (Default) +``` +Send-DuoAuth -Username [-Factor ] [-IpAddr ] [-Hostname ] [-Async] + [] +``` + +### UserId +``` +Send-DuoAuth -UserId [-Factor ] [-IpAddr ] [-Hostname ] [-Async] + [] +``` + +### PhoneSms +``` +Send-DuoAuth [-Factor ] [-IpAddr ] [-Hostname ] [-Async] [-Device ] + [] +``` + +### Push +``` +Send-DuoAuth [-Factor ] [-IpAddr ] [-Hostname ] [-Async] [-Device ] [-Type] + [-PushInfo ] [-DisplayUsername ] [] +``` + +### Passcode +``` +Send-DuoAuth [-Factor ] [-IpAddr ] [-Hostname ] [-Async] [-Passcode] + [] +``` + +## DESCRIPTION +The /auth endpoint performs second-factor authentication for a user by sending a push notification to the user's smartphone app, verifying a passcode, or placing a phone call. +It is also used to send the user a new batch of passcodes via SMS. + +## EXAMPLES + +### EXAMPLE 1 +``` +New-DuoAuth -Username blumbergh -Factor Auto -Async +``` + +## PARAMETERS + +### -UserId +Permanent, unique identifier for the user as generated by Duo upon user creation (e.g. +DUYHV6TJBC3O4RITS1WC). + +```yaml +Type: String +Parameter Sets: UserId +Aliases: user_id + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Username +Unique identifier for the user that is commonly specified by your application during user creation (e.g. +user@domain.com). +This value may also represent a username alias assigned to a user. + +```yaml +Type: String +Parameter Sets: Username +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Factor +Factor to use for authentication. +Currently, the following choices are supported: + +| Value | Meaning | +|-------|---------| +| auto | Use the out-of-band factor (push or phone) recommended by Duo as the best for the user's devices. +| push | Authenticate the user with Duo Push. +| passcode | Authenticate the user with a passcode (from Duo Mobile, SMS, hardware token, or bypass code). +| sms | Send a new batch of SMS passcodes to the user. +Note that this will not actually authenticate the user (it will automatically return "deny"). +Thus, if the user elects to do this then you should re-prompt to authenticate after the call has completed. +| phone | Authenticate the user with phone callback. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: Auto +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -IpAddr +The IP address of the user to be authenticated, in dotted quad format. +This will cause an "allow" response to be sent if appropriate for requests from a trusted network. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Hostname +The host name of the device accessing the application. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Async +If this parameter is not provided, then the /auth endpoint will only return a response when the authentication process has completed. +If, however, your application provides this parameter with a value of "1", then /auth will immediately return a transaction ID, and your application will need to subsequently query the /auth_status endpoint to get the status (and, eventually, result) of the authentication process. + +If you enable async, then your application will be able to retrieve real-time status updates from the authentication process, rather than receiving no information until the process is complete. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Device +ID of the device. +This device must have the "push","phone" or "sms" capability. + +Default: auto + +```yaml +Type: String +Parameter Sets: PhoneSms, Push +Aliases: + +Required: False +Position: Named +Default value: Auto +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Type +This string is displayed in the Duo Mobile app push notification and UI. +You may wish to specify some alternate phrase for this parameter. + +The default English string in Duo Mobile v4 is "Verify your identity" and "Are you logging in to" followed by the application's name in the push request notification text, and "Are you logging in to" followed by the application's name in the request details screen as shown in Duo Mobile. +With type specified, the notification text changes to "Verify request" and shows your customized string followed by a colon and the application's name, and the request details screen also shows your customized string and the application's name. +Duo Mobile shows the equivalent localization in the languagues supported by the app, but does not attempt to localize your custom string or support multiple string values (for different languages). + +```yaml +Type: SwitchParameter +Parameter Sets: Push +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -PushInfo +A set of key/value pairs with additional contextual information associated with this authentication attempt. +The Duo Mobile app will display this information to the user. + +```yaml +Type: Hashtable +Parameter Sets: Push +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -DisplayUsername +String to display in Duo Mobile in place of the user's Duo username. + +```yaml +Type: String +Parameter Sets: Push +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Passcode +Passcode entered by the user. + +```yaml +Type: SwitchParameter +Parameter Sets: Passcode +Aliases: + +Required: True +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](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +## OUTPUTS + +## NOTES +Exactly one of user_id or username must be specified. + +The push_info URL-encoded string's total length must be less than 20,000 bytes. + +## RELATED LINKS + +[https://duo.com/docs/authapi#/auth](https://duo.com/docs/authapi#/auth) + diff --git a/Docs/Send-DuoAuthPing.md b/Docs/Send-DuoAuthPing.md new file mode 100644 index 0000000..19039ae --- /dev/null +++ b/Docs/Send-DuoAuthPing.md @@ -0,0 +1,45 @@ +--- +external help file: DuoSecurity-help.xml +Module Name: DuoSecurity +online version: https://duo.com/docs/authapi#/ping +schema: 2.0.0 +--- + +# Send-DuoAuthPing + +## SYNOPSIS +Duo API Ping + +## SYNTAX + +``` +Send-DuoAuthPing [] +``` + +## DESCRIPTION +The /ping endpoint acts as a "liveness check" that can be called to verify that Duo is up before trying to call other Auth API endpoints. +Unlike the other endpoints, this one does not have to be signed with the Authorization header. + +## EXAMPLES + +### EXAMPLE 1 +``` +Send-DuoAuthPing +``` + +## PARAMETERS + +### 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](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +## OUTPUTS + +## NOTES +This endpoint is also suitable for use with Duo's v2 Web SDK to verify that Duo's service is responding before initializing frame authentication. + +## RELATED LINKS + +[https://duo.com/docs/authapi#/ping](https://duo.com/docs/authapi#/ping) + diff --git a/Docs/Send-DuoPreAuth.md b/Docs/Send-DuoPreAuth.md new file mode 100644 index 0000000..26c1420 --- /dev/null +++ b/Docs/Send-DuoPreAuth.md @@ -0,0 +1,131 @@ +--- +external help file: DuoSecurity-help.xml +Module Name: DuoSecurity +online version: https://duo.com/docs/authapi#/preauth +schema: 2.0.0 +--- + +# Send-DuoPreAuth + +## SYNOPSIS +Duo Pre-Auth + +## SYNTAX + +### Username (Default) +``` +Send-DuoPreAuth -Username [-IpAddr ] [-Hostname ] [-TrustedDeviceToken ] + [] +``` + +### UserId +``` +Send-DuoPreAuth -UserId [-IpAddr ] [-Hostname ] [-TrustedDeviceToken ] + [] +``` + +## DESCRIPTION +The /preauth endpoint determines whether a user is authorized to log in, and (if so) returns the user's available authentication factors. + +## EXAMPLES + +### EXAMPLE 1 +``` +Send-DuoPreAuth -Username pgibbons +``` + +## PARAMETERS + +### -UserId +Permanent, unique identifier for the user as generated by Duo upon user creation (e.g. +DUYHV6TJBC3O4RITS1WC). + +```yaml +Type: String +Parameter Sets: UserId +Aliases: user_id + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Username +Unique identifier for the user that is commonly specified by your application during user creation (e.g. +user@domain.com). +This value may also represent a username alias assigned to a user + +```yaml +Type: String +Parameter Sets: Username +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -IpAddr +The IP address of the user to be authenticated, in dotted quad format. +This will cause an "allow" response to be sent if appropriate for requests from a trusted network. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Hostname +The host name of the device accessing the application. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -TrustedDeviceToken +If the trusted_device_token is present and the Auth API application has an effective policy that enables Remembered Devices for each browser-based application, return an "allow" response for the lifetime of the token as set by the Duo administrator in the policy. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +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](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +## OUTPUTS + +## NOTES +Exactly one of user_id or username must be specified. + +## RELATED LINKS + +[https://duo.com/docs/authapi#/preauth](https://duo.com/docs/authapi#/preauth) + diff --git a/Docs/Test-DuoAuthApi.md b/Docs/Test-DuoAuthApi.md new file mode 100644 index 0000000..0613b1d --- /dev/null +++ b/Docs/Test-DuoAuthApi.md @@ -0,0 +1,44 @@ +--- +external help file: DuoSecurity-help.xml +Module Name: DuoSecurity +online version: https://duo.com/docs/authapi#/check +schema: 2.0.0 +--- + +# Test-DuoAuthApi + +## SYNOPSIS +Check Duo API + +## SYNTAX + +``` +Test-DuoAuthApi [] +``` + +## DESCRIPTION +The /check endpoint can be called to verify that the Auth API integration and secret keys are valid, and that the signature is being generated properly. + +## EXAMPLES + +### EXAMPLE 1 +``` +Test-DuoAuthApi +``` + +## PARAMETERS + +### 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](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +## OUTPUTS + +## NOTES +This endpoint is also suitable for use with Duo's v2 Web SDK to verify integration information before initializing frame authentication. + +## RELATED LINKS + +[https://duo.com/docs/authapi#/check](https://duo.com/docs/authapi#/check) + diff --git a/DuoSecurity/Private/Invoke/Invoke-DuoRequest.ps1 b/DuoSecurity/Private/Invoke/Invoke-DuoRequest.ps1 index c731052..ba13451 100644 --- a/DuoSecurity/Private/Invoke/Invoke-DuoRequest.ps1 +++ b/DuoSecurity/Private/Invoke/Invoke-DuoRequest.ps1 @@ -14,6 +14,12 @@ function Invoke-DuoRequest { .PARAMETER Params Hashtable of parameters + + .PARAMETER NoAuth + Do not send authorization header + + .PARAMETER FilePath + Path to save output file to .EXAMPLE Invoke-DuoRequest -Path '/admin/v1/users' -Method GET @@ -28,7 +34,13 @@ function Invoke-DuoRequest { [string]$Path, [Parameter()] - [hashtable]$Params = @{} + [hashtable]$Params = @{}, + + [Parameter()] + [switch]$NoAuth, + + [Parameter()] + [string]$FilePath ) # Get API credentials @@ -113,13 +125,28 @@ function Invoke-DuoRequest { 'Authorization' = $AuthString } + if ($NoAuth) { + $Headers = @{} + } + # Make API call URI $UriBuilder = [System.UriBuilder]('https://{0}{1}' -f $ApiHost, $Path) $UriBuilder.Query = $Request Write-Verbose ( '[{0}]' -f $UriBuilder.Uri ) - $Results = Invoke-RestMethod -Method $Method -Uri $UriBuilder.Uri -Headers $Headers -SkipHttpErrorCheck + $RestMethod = @{ + Method = $Method + Uri = $UriBuilder.Uri + Headers = $Headers + SkipHttpErrorCheck = $true + } + + if ($FilePath) { + $RestMethod.OutFile = $FilePath + } + + $Results = Invoke-RestMethod @RestMethod $Results } diff --git a/DuoSecurity/Public/Auth API/Get-DuoAuthEnrollmentStatus.ps1 b/DuoSecurity/Public/Auth API/Get-DuoAuthEnrollmentStatus.ps1 new file mode 100644 index 0000000..9c3f7e7 --- /dev/null +++ b/DuoSecurity/Public/Auth API/Get-DuoAuthEnrollmentStatus.ps1 @@ -0,0 +1,55 @@ +function Get-DuoAuthEnrollmentStatus { + <# + .SYNOPSIS + Duo Auth Enrollment Status + + .DESCRIPTION + Check whether a user has completed enrollment. + + .PARAMETER UserId + ID of the user. + + .PARAMETER ActivationCode + Activation code, as returned from /enroll. + + .EXAMPLE + Get-DuoAuthEnrollmentStatus -UserId SOMEUSERID -ActivationCode SOMEACTIVATIONCODE + + .LINK + https://duo.com/docs/authapi#/enroll_status + + .NOTES + + #> + [CmdletBinding()] + Param( + [Parameter(ValueFromPipelineByPropertyName = $true, Mandatory = $true)] + [Alias('user_id')] + [string]$UserId, + + [Parameter(ValueFromPipelineByPropertyName = $true, Mandatory = $true)] + [Alias('activation_code')] + [string]$ActivationCode + ) + + process { + $Params = @{ + user_id = $UserId + activation_code = $ActivationCode + } + + $DuoRequest = @{ + Method = 'POST' + Path = '/auth/v2/enroll_status' + Params = $Params + } + + $Response = Invoke-DuoRequest @DuoRequest + if ($Response.stat -eq 'OK') { + $Response.response + } + else { + $Response + } + } +} diff --git a/DuoSecurity/Public/Auth API/Get-DuoAuthLogo.ps1 b/DuoSecurity/Public/Auth API/Get-DuoAuthLogo.ps1 new file mode 100644 index 0000000..70cd535 --- /dev/null +++ b/DuoSecurity/Public/Auth API/Get-DuoAuthLogo.ps1 @@ -0,0 +1,44 @@ +function Get-DuoAuthLogo { + <# + .SYNOPSIS + Duo Auth Logo + + .DESCRIPTION + The /logo endpoint provides a programmatic way to retrieve your stored logo. + + .PARAMETER FilePath + Where to save the logo + + .EXAMPLE + Get-DuoAuthLogo -FilePath ./logo.png + + .LINK + https://duo.com/docs/authapi#/logo + + .NOTES + + #> + [CmdletBinding()] + Param( + [Parameter(Mandatory = $true)] + [string]$FilePath + ) + + process { + $DuoRequest = @{ + Method = 'GET' + Path = '/auth/v2/logo' + Params = @{ + FilePath = $FilePath + } + } + + $Response = Invoke-DuoRequest @DuoRequest + if ($Response.stat -eq 'OK') { + $Response.response + } + else { + $Response + } + } +} diff --git a/DuoSecurity/Public/Auth API/Get-DuoAuthStatus.ps1 b/DuoSecurity/Public/Auth API/Get-DuoAuthStatus.ps1 new file mode 100644 index 0000000..341ab32 --- /dev/null +++ b/DuoSecurity/Public/Auth API/Get-DuoAuthStatus.ps1 @@ -0,0 +1,46 @@ +function Get-DuoAuthStatus { + <# + .SYNOPSIS + Duo API Auth Status + + .DESCRIPTION + The /auth_status endpoint "long-polls" for the next status update from the authentication process for a given transaction. That is to say, if no status update is available at the time the request is sent, it will wait until there is an update before returning a response. + + .PARAMETER TxId + The transaction ID of the authentication attempt, as returned by the /auth endpoint. + + .EXAMPLE + Get-DuoAuthStatus -TxId 66cc8d20-fdfa-41bc-8b74-1a3b095d55f7 + + .LINK + https://duo.com/docs/authapi#/auth_status + + .NOTES + + #> + [CmdletBinding()] + Param( + [Parameter(ValueFromPipelineByPropertyName = $true, Mandatory = $true)] + [string]$TxId + ) + + process { + $Params = @{ + txid = $TxId + } + + $DuoRequest = @{ + Method = 'GET' + Path = '/auth/v2/auth_status' + Params = $Params + } + + $Response = Invoke-DuoRequest @DuoRequest + if ($Response.stat -eq 'OK') { + $Response.response + } + else { + $Response + } + } +} diff --git a/DuoSecurity/Public/Auth API/New-DuoAuthEnrollment.ps1 b/DuoSecurity/Public/Auth API/New-DuoAuthEnrollment.ps1 new file mode 100644 index 0000000..f9e6b29 --- /dev/null +++ b/DuoSecurity/Public/Auth API/New-DuoAuthEnrollment.ps1 @@ -0,0 +1,49 @@ +function New-DuoAuthEnrollment { + <# + .SYNOPSIS + Duo Auth Enrollment + + .DESCRIPTION + The /enroll endpoint provides a programmatic way to enroll new users with Duo two-factor authentication. It creates the user in Duo and returns a code (as a QR code) that Duo Mobile can scan with its built-in camera. Scanning the QR code adds the user's account to the app so that they receive and respond to Duo Push login requests. + + .PARAMETER Username + Username for the created user. If not given, a random username will be assigned and returned. + + .PARAMETER ValidSecs + Seconds for which the activation code will remain valid. Default: 86400 (one day). + + .EXAMPLE + New-DuoAuthEnrollment + + .NOTES + General notes + #> + [CmdletBinding()] + Param( + [Parameter()] + [string]$Username, + + [Parameter()] + [int]$ValidSecs + ) + + process { + $Params = @{} + if ($Username) { $Params.username = $Username } + if ($ValidSecs) { $Params.valid_secs = $ValidSecs } + + $DuoRequest = @{ + Method = 'POST' + Path = '/auth/v2/enroll' + Params = $Params + } + + $Response = Invoke-DuoRequest @DuoRequest + if ($Response.stat -eq 'OK') { + $Response.response + } + else { + $Response + } + } +} diff --git a/DuoSecurity/Public/Auth API/Send-DuoAuth.ps1 b/DuoSecurity/Public/Auth API/Send-DuoAuth.ps1 new file mode 100644 index 0000000..515672b --- /dev/null +++ b/DuoSecurity/Public/Auth API/Send-DuoAuth.ps1 @@ -0,0 +1,134 @@ +function Send-DuoAuth { + <# + .SYNOPSIS + Duo Auth + + .DESCRIPTION + The /auth endpoint performs second-factor authentication for a user by sending a push notification to the user's smartphone app, verifying a passcode, or placing a phone call. It is also used to send the user a new batch of passcodes via SMS. + + .PARAMETER UserId + Permanent, unique identifier for the user as generated by Duo upon user creation (e.g. DUYHV6TJBC3O4RITS1WC). + + .PARAMETER Username + Unique identifier for the user that is commonly specified by your application during user creation (e.g. user@domain.com). This value may also represent a username alias assigned to a user. + + .PARAMETER Factor + Factor to use for authentication. Currently, the following choices are supported: + + | Value | Meaning | + |-------|---------| + | auto | Use the out-of-band factor (push or phone) recommended by Duo as the best for the user's devices. + | push | Authenticate the user with Duo Push. + | passcode | Authenticate the user with a passcode (from Duo Mobile, SMS, hardware token, or bypass code). + | sms | Send a new batch of SMS passcodes to the user. Note that this will not actually authenticate the user (it will automatically return "deny"). Thus, if the user elects to do this then you should re-prompt to authenticate after the call has completed. + | phone | Authenticate the user with phone callback. + + .PARAMETER IpAddr + The IP address of the user to be authenticated, in dotted quad format. This will cause an "allow" response to be sent if appropriate for requests from a trusted network. + + .PARAMETER Hostname + The host name of the device accessing the application. + + .PARAMETER Async + If this parameter is not provided, then the /auth endpoint will only return a response when the authentication process has completed. If, however, your application provides this parameter with a value of "1", then /auth will immediately return a transaction ID, and your application will need to subsequently query the /auth_status endpoint to get the status (and, eventually, result) of the authentication process. + + If you enable async, then your application will be able to retrieve real-time status updates from the authentication process, rather than receiving no information until the process is complete. + + .PARAMETER Device + ID of the device. This device must have the "push","phone" or "sms" capability. + + Default: auto + + .PARAMETER Type + This string is displayed in the Duo Mobile app push notification and UI. You may wish to specify some alternate phrase for this parameter. + + The default English string in Duo Mobile v4 is "Verify your identity" and "Are you logging in to" followed by the application's name in the push request notification text, and "Are you logging in to" followed by the application's name in the request details screen as shown in Duo Mobile. With type specified, the notification text changes to "Verify request" and shows your customized string followed by a colon and the application's name, and the request details screen also shows your customized string and the application's name. Duo Mobile shows the equivalent localization in the languagues supported by the app, but does not attempt to localize your custom string or support multiple string values (for different languages). + + .PARAMETER DisplayUsername + String to display in Duo Mobile in place of the user's Duo username. + + .PARAMETER PushInfo + A set of key/value pairs with additional contextual information associated with this authentication attempt. The Duo Mobile app will display this information to the user. + + .PARAMETER Passcode + Passcode entered by the user. + + .EXAMPLE + New-DuoAuth -Username blumbergh -Factor Auto -Async + + .LINK + https://duo.com/docs/authapi#/auth + + .NOTES + Exactly one of user_id or username must be specified. + + The push_info URL-encoded string's total length must be less than 20,000 bytes. + #> + [CmdletBinding(DefaultParameterSetName = 'Username')] + Param( + [Parameter(Mandatory = $true, ParameterSetName = 'UserId')] + [Alias('user_id')] + [string]$UserId, + + [Parameter(Mandatory = $true, ParameterSetName = 'Username')] + [string]$Username, + + [Parameter()] + [ValidateSet('Auto', 'Push', 'Passcode', 'Sms', 'Phone')] + [string]$Factor = 'Auto', + + [Parameter()] + [string]$IpAddr, + + [Parameter()] + [string]$Hostname, + + [Parameter()] + [switch]$Async, + + [Parameter(ParameterSetName = 'Push')] + [Parameter(ParameterSetName = 'PhoneSms')] + [string]$Device = 'auto', + + [Parameter(ParameterSetName = 'Push')] + [switch]$Type, + + [Parameter(ParameterSetName = 'Push')] + [hashtable]$PushInfo, + + [Parameter(ParameterSetName = 'Push')] + [string]$DisplayUsername, + + [Parameter(Mandatory = $true, ParameterSetName = 'Passcode')] + [switch]$Passcode + ) + + process { + $Params = @{ + factor = $Factor.ToLower() + } + if ($UserId) { $Params.user_id = $UserId } + if ($Username) { $Params.username = $Username } + if ($IpAddr) { $Params.ipaddr = $IpAddr } + if ($Hostname) { $Params.hostname = $Hostname } + if ($Async.IsPresent) { $Params.async = 1 } + if ($Device) { $Params.device = $Device } + if ($Type) { $Params.type = $Type } + if ($PushInfo) { $Params.pushinfo = $PushInfo } + if ($Passcode) { $Params.passcode = $Passcode } + + $DuoRequest = @{ + Method = 'POST' + Path = '/auth/v2/auth' + Params = $Params + } + + $Response = Invoke-DuoRequest @DuoRequest + if ($Response.stat -eq 'OK') { + $Response.response + } + else { + $Response + } + } +} diff --git a/DuoSecurity/Public/Auth API/Send-DuoAuthPing.ps1 b/DuoSecurity/Public/Auth API/Send-DuoAuthPing.ps1 new file mode 100644 index 0000000..97d2700 --- /dev/null +++ b/DuoSecurity/Public/Auth API/Send-DuoAuthPing.ps1 @@ -0,0 +1,36 @@ +function Send-DuoAuthPing { + <# + .SYNOPSIS + Duo API Ping + + .DESCRIPTION + The /ping endpoint acts as a "liveness check" that can be called to verify that Duo is up before trying to call other Auth API endpoints. Unlike the other endpoints, this one does not have to be signed with the Authorization header. + + .EXAMPLE + Send-DuoAuthPing + + .LINK + https://duo.com/docs/authapi#/ping + + .NOTES + This endpoint is also suitable for use with Duo's v2 Web SDK to verify that Duo's service is responding before initializing frame authentication. + #> + [CmdletBinding()] + Param() + + process { + $DuoRequest = @{ + Method = 'GET' + Path = '/auth/v2/ping' + NoAuth = $true + } + + $Response = Invoke-DuoRequest @DuoRequest + if ($Response.stat -eq 'OK') { + $Response.response + } + else { + $Response + } + } +} diff --git a/DuoSecurity/Public/Auth API/Send-DuoPreAuth.ps1 b/DuoSecurity/Public/Auth API/Send-DuoPreAuth.ps1 new file mode 100644 index 0000000..7fe756a --- /dev/null +++ b/DuoSecurity/Public/Auth API/Send-DuoPreAuth.ps1 @@ -0,0 +1,74 @@ +function Send-DuoPreAuth { + <# + .SYNOPSIS + Duo Pre-Auth + + .DESCRIPTION + The /preauth endpoint determines whether a user is authorized to log in, and (if so) returns the user's available authentication factors. + + .PARAMETER UserId + Permanent, unique identifier for the user as generated by Duo upon user creation (e.g. DUYHV6TJBC3O4RITS1WC). + + .PARAMETER Username + Unique identifier for the user that is commonly specified by your application during user creation (e.g. user@domain.com). This value may also represent a username alias assigned to a user + + .PARAMETER IpAddr + The IP address of the user to be authenticated, in dotted quad format. This will cause an "allow" response to be sent if appropriate for requests from a trusted network. + + .PARAMETER Hostname + The host name of the device accessing the application. + + .PARAMETER TrustedDeviceToken + If the trusted_device_token is present and the Auth API application has an effective policy that enables Remembered Devices for each browser-based application, return an "allow" response for the lifetime of the token as set by the Duo administrator in the policy. + + .EXAMPLE + Send-DuoPreAuth -Username pgibbons + + .LINK + https://duo.com/docs/authapi#/preauth + + .NOTES + Exactly one of user_id or username must be specified. + #> + [CmdletBinding(DefaultParameterSetName = 'Username')] + Param( + [Parameter(Mandatory = $true, ParameterSetName = 'UserId')] + [Alias('user_id')] + [string]$UserId, + + [Parameter(Mandatory = $true, ParameterSetName = 'Username')] + [string]$Username, + + [Parameter()] + [string]$IpAddr, + + [Parameter()] + [string]$Hostname, + + [Parameter()] + [string]$TrustedDeviceToken + ) + + process { + $Params = @{} + if ($UserId) { $Params.user_id = $UserId } + if ($Username) { $Params.username = $Username } + if ($IpAddr) { $Params.ipaddr = $IpAddr } + if ($Hostname) { $Params.hostname = $Hostname } + if ($TrustedDeviceToken) { $Params.trusted_device_token = $TrustedDeviceToken } + + $DuoRequest = @{ + Method = 'POST' + Path = '/auth/v2/preauth' + Params = $Params + } + + $Response = Invoke-DuoRequest @DuoRequest + if ($Response.stat -eq 'OK') { + $Response.response + } + else { + $Response + } + } +} diff --git a/DuoSecurity/Public/Auth API/Test-DuoAuthApi.ps1 b/DuoSecurity/Public/Auth API/Test-DuoAuthApi.ps1 new file mode 100644 index 0000000..957333f --- /dev/null +++ b/DuoSecurity/Public/Auth API/Test-DuoAuthApi.ps1 @@ -0,0 +1,35 @@ +function Test-DuoAuthApi { + <# + .SYNOPSIS + Check Duo API + + .DESCRIPTION + The /check endpoint can be called to verify that the Auth API integration and secret keys are valid, and that the signature is being generated properly. + + .EXAMPLE + Test-DuoAuthApi + + .LINK + https://duo.com/docs/authapi#/check + + .NOTES + This endpoint is also suitable for use with Duo's v2 Web SDK to verify integration information before initializing frame authentication. + #> + [CmdletBinding()] + Param() + + process { + $DuoRequest = @{ + Method = 'GET' + Path = '/auth/v2/check' + } + + $Response = Invoke-DuoRequest @DuoRequest + if ($Response.stat -eq 'OK') { + $Response.response + } + else { + $Response + } + } +} diff --git a/README.md b/README.md index 5f35703..f7f8e23 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,12 @@ # DuoSecurity Module [![DuoSecurityDownloads]][DuoSecurityGallery] ![DuoSecurityBuild] ![DuoSecurityPublish] + +[DuoSecurityDownloads]: https://img.shields.io/powershellgallery/dt/DuoSecurity +[DuoSecurityGallery]: https://www.powershellgallery.com/packages/DuoSecurity/ +[DuoSecurityBuild]: https://img.shields.io/github/workflow/status/johnduprey/DuoSecurity/Run%20PSScriptAnalyzer?label=PSScriptAnalyzer +[DuoSecurityPublish]: https://img.shields.io/github/workflow/status/johnduprey/DuoSecurity/Publish%20New%20Version?label=PSGallery + This module interacts with the Duo APIs. # Instructions @@ -64,6 +70,7 @@ Set-DuoApiAuth @Auth Get-DuoUsers ``` + # Cmdlet Help ## Accounts API - [Get-DuoAccountEdition](./Docs/Get-DuoAccountEdition.md) @@ -177,13 +184,15 @@ Get-DuoUsers - [Get-DuoWebAuthnCredentials](./Docs/Get-DuoWebAuthnCredentials.md) - [Remove-DuoWebAuthnCredential](./Docs/Remove-DuoWebAuthnCredential.md) ## Auth API +- [Get-DuoAuthEnrollmentStatus](./Docs/Get-DuoAuthEnrollmentStatus.md) +- [Get-DuoAuthLogo](./Docs/Get-DuoAuthLogo.md) +- [Get-DuoAuthStatus](./Docs/Get-DuoAuthStatus.md) +- [New-DuoAuthEnrollment](./Docs/New-DuoAuthEnrollment.md) +- [Send-DuoAuth](./Docs/Send-DuoAuth.md) +- [Send-DuoAuthPing](./Docs/Send-DuoAuthPing.md) +- [Send-DuoPreAuth](./Docs/Send-DuoPreAuth.md) +- [Test-DuoAuthApi](./Docs/Test-DuoAuthApi.md) ## Authentication - [Set-DuoApiAuth](./Docs/Set-DuoApiAuth.md) ## Misc - [New-DuoTokenTotpSecret](./Docs/New-DuoTokenTotpSecret.md) - - -[DuoSecurityDownloads]: https://img.shields.io/powershellgallery/dt/DuoSecurity -[DuoSecurityGallery]: https://www.powershellgallery.com/packages/DuoSecurity/ -[DuoSecurityBuild]: https://img.shields.io/github/workflow/status/johnduprey/DuoSecurity/Run%20PSScriptAnalyzer?label=PSScriptAnalyzer -[DuoSecurityPublish]: https://img.shields.io/github/workflow/status/johnduprey/DuoSecurity/Publish%20New%20Version?label=PSGallery \ No newline at end of file From b1132ba4f92b3c5fb864945d1ff5ff39b9c60bb6 Mon Sep 17 00:00:00 2001 From: John Duprey Date: Thu, 8 Dec 2022 21:14:16 -0500 Subject: [PATCH 2/2] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index f7f8e23..f172c1a 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,7 @@ Install-Module DuoSecurity - [X] [Accounts API](https://duo.com/docs/accountsapi) - [X] [Admin API](https://duo.com/docs/adminapi) -- [ ] [Auth API](https://duo.com/docs/authapi) +- [X] [Auth API](https://duo.com/docs/authapi) # Examples