This repository contains the Okta management PowerShell module. This PowerShell module can be used to easily interact with the Okta management API and:
Note: For more details about the APIs and models the SDK support, check out the API docs
This library uses semantic versioning and follows Okta's library version policy.
| Version | Status |
|---|---|
| 1.x | :heavy_check_mark: Stable |
The latest release can always be found on the releases page. For more information about our SDKs' lifecycle, check out our docs.
If you run into problems using the Okta PowerShell module, you can
This PowerShell module is automatically generated by the OpenAPI Generator project:
The Okta PowerShell module is compatible with:
To install the Okta.PowerShell module from PS Gallery run the following command:
Install-Module -Name Okta.PowerShell -RequiredVersion <MODULE_VERSION>To verify the module was successfully installed, run Get-InstalledModule -Name 'okta.powershell' and verify that the module information is shown.
To uninstall the module, simply run:
Uninstall-Module -Name Okta.PowerShellTo install the Okta.PowerShell module from Chocolatey run the following command:
choco install okta.powershell --version=<MODULE_VERSION>To verify the module was successfully installed, run choco list "okta.powershell" and verify that the module information is shown.
To uninstall the module, simply run:
choco uninstall okta.powershellNote: Signed binary releases are posted to the okta-powershell-cli releases section in Github.
To install from the source, run the following command to build and install the PowerShell module locally:
./Build.ps1
Import-Module -Name '.\src\Okta.PowerShell' -VerboseTo avoid function name collision, one can use -Prefix, e.g. Import-Module -Name '.\src\Okta.PowerShell' -Prefix prefix
To uninstall the module, simply run:
Remove-Module -FullyQualifiedName @{ModuleName = "Okta.PowerShell"; ModuleVersion = "<MODULE_VERSION>"}To install and run Pester, please execute the following commands in the terminal:
Install-module -name Pester -force
Invoke-PesterFor troubleshooting, please run $DebugPreference = 'Continue' to turn on debugging and disable it with $DebugPreference = 'SilentlyContinue' when done with the troubleshooting.
We recommend limiting the access permissions of your Okta.PowerShell scripts to only authorized users.
Add the appropriate users or groups and assign the necessary permissions to the OktaConfiguration.ps1 file (Full Control, Read & Execute, etc.), and remove any unnecessary users or groups from the list.
:Warning: The OktaConfiguration.ps1 file contains secrets, so we recommend using least privilege access to the configuration file.
Note: For more information about PowerShell script security, check out the official PowerShell security guide.
The PowerShell module uses the device authorization flow to obtain an access token, so it requires, at least, three configuration values. These are the
values for the Okta Org domain, the client ID of the OIDC Native Application
and the scope for the API grants you are going to need. For example, if you are going to get groups then you will need the grant okta.groups.read configured in your scope. Make sure to assign the application to anyone that needs access to it.
Non-admin users will require to be granted specific permissions to perform certain tasks and access resources.
Check out the following resources to learn more:
$Configuration = Get-OktaConfiguration
$Configuration.BaseUrl = 'https://myorg.okta.com'
$Configuration.ClientId = 'MY_CLIENT_ID'
$Configuration.Scope = "okta.groups.read" # or "okta.groups.read okta.apps.read"Invoke-OktaEstablishAccessTokenNote: You have to open the browser and navigate to the provided URL to complete the flow. Once the device is authorized, go back to the PowerShell terminal.
Invoke-OktaListGroups
id : 00g9erf7s3ydK79IX5d7
created : 5/5/23 1:45:05 PM
lastUpdated : 5/5/23 1:45:05 PM
lastMembershipUpdated : 5/5/23 1:45:05 PM
objectClass : {okta:user_group}
type : OKTA_GROUP
profile : @{name=Sales; description=}
_links : @{logo=System.Object[]; users=; apps=}Note: For more details about commands, check out the documentation for API endpoints
Note: If you want to remove the access token from configuration you can execute
Invoke-OktaRemoveAccessToken
$User = Get-OktaUser -UserId "foo"$UserProfile = [PSCustomObject]@{
firstName = 'John'
lastName = 'Doe'
login = 'john.doe@mail.com'
email = 'john.doe@mail.com'
}
$CreateUserRequest = Initialize-OktaCreateUserRequest -VarProfile $UserProfile -GroupIds 'foo'
$TestResult = New-OktaUser -Body $CreateUserRequestNote: If you initialize objects using
PSCustomObject, ensure the casing is correct.
$Users = Invoke-OktaListUsers -Limit 10 Utilize the -withHttpInfo flag to retrieve additional response properties, including NextPageUri for accessing the subsequent page of results. Additionally, you can seamlessly access all response headers through the Headers property.
To paginate results, use Uri param, which allows passing absolute URIs:
$UsersResponse = Invoke-OktaListUsers -Limit 10 -withHttpInfo
While ($UsersResponse.NextPageUri)
{
$UsersResponse = Invoke-OktaListUsers -Uri $UsersResponse.NextPageUri -withHttpInfo #This time you can pass the absolute Uri with already contains query params such as "limit" or/and "after"
$UsersList = $UsersResponse.Response
}$OAuthClient = [PSCustomObject]@{
client_uri = "https://example.com/client"
logo_uri = "https://example.com/assets/images/logo-new.png"
response_types = @("token", "id_token", "code")
redirect_uris = @("https://example.com/oauth2/callback", "myapp://callback")
post_logout_redirect_uris = @("https://example.com/postlogout", "myapp://postlogoutcallback")
grant_types = @("implicit", "authorization_code")
application_type = "native"
tos_uri = "https://example.com/client/tos"
policy_uri = "https://example.com/client/policy"
}
# a simple test to create an object
$Settings = Initialize-OktaOpenIdConnectApplicationSettings -OauthClient $OAuthClient
$NewApp = Initialize-OktaOpenIdConnectApplication -Label "New App" -SignOnMode "OPENID_CONNECT" -Settings $Settings
Note: If you initialize objects using
PSCustomObject, ensure the casing is correct.Note: Null values are removed from the payload by default. If you want to include null values you have to include the
-IncludeNullValuesflag.Note: For more API samples checkout our tests
The Okta API will return 429 responses if too many requests are made within a given time. Please see Rate Limiting at Okta for a complete list of which endpoints are rate limited. When a 429 error is received, the X-Rate-Limit-Reset header will tell you the time at which you can retry. This section discusses methods for handling rate limiting with this SDK.
The Okta.PowerShell module uses a built-in retry strategy to automatically retry on 429 errors.
You can configure the following options when using the built-in retry strategy:
| Configuration Option | Description |
|---|---|
| RequestTimeout | The waiting time in milliseconds for a request to be resolved by the client. Less than or equal to 0 means "no timeout". The default value is $null (None). |
| MaxRetries | The number of times to retry. |
$Config = Get-OktaConfiguration
$Config.MaxRetries = 2
$Config.RequestTimeout = 6000
# Invoke your commands as usual
$Result = Invoke-OktaListApplications Note: We're happy to accept contributions and PRs! Please see the contribution guide to understand how to structure a contribution.