Skip to content
Call Okta API from PowerShell -- unofficial code.
PowerShell
Branch: master
Clone or download
Latest commit 393be59 Aug 22, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
Modules Update OktaAPI.psm1 Aug 22, 2019
CallOktaAPI.ps1
OktaAPISettings.ps1 Update OktaAPISettings.ps1 Apr 25, 2018
README.md Update README.md Jul 6, 2019
okta.json Update okta.json Apr 30, 2019

README.md

OktaAPI.psm1

Call the Okta API from PowerShell -- unofficial code.

This module provides a very thin wrapper around the Okta API. It converts to/from JSON. It supports pagination of objects and allows you to check rate limits.

It assumes you are familiar with the Okta API and using REST.

Contents

Usage

Connect-Okta "YOUR_API_TOKEN" "https://YOUR_ORG.oktapreview.com"

# Add a user to a group.
$user = Get-OktaUser "me"
$group = Get-OktaGroups "PowerShell" 'type eq "OKTA_GROUP"'
Add-OktaGroupMember $group.id $user.id

# Create a user.
$profile = @{login = $login; email = $email; firstName = $firstName; lastName = $lastName}
$user = New-OktaUser @{profile = $profile}

# Create a group.
$profile = @{name = $name; description = $description}
$group = New-OktaGroup @{profile = $profile}

See CallOktaAPI.ps1 for more examples.

There are functions for Apps, Events, Factors, Groups, IdPs, Logs, Roles, Users and Zones. And you can add your own.

Installation

To determine which version of PowerShell you're running, see PSVersion under $PSVersionTable.

To Install on PowerShell 5 or newer

Install-Module OktaAPI # [1]

Install-Script CallOktaAPI # [2]

CallOktaAPI.ps1 has sample code. Replace YOUR_API_TOKEN and YOUR_ORG with your values or use OktaAPISettings.ps1.

[1] https://www.powershellgallery.com/packages/OktaAPI
[2] https://www.powershellgallery.com/packages/CallOktaAPI

To Install on PowerShell 4 or older

  1. $env:PSModulePath contains a list of folders where modules live (e.g., C:\Users\Administrator\Documents\WindowsPowerShell\Modules). Create a new folder in a folder in your module path called OktaAPI (e.g., C:\Users\Administrator\Documents\WindowsPowerShell\Modules\OktaAPI).
  2. Copy OktaAPI.psm1 to the new folder: Modules\OktaAPI
  3. Copy CallOktaAPI.ps1. It has sample code. Replace YOUR_API_TOKEN and YOUR_ORG with your values or use OktaAPISettings.ps1.

Might I also suggest a GUI/IDE and debugging tools

  • PowerShell ISE (Windows-only). It comes pre-installed with most Windows versions (including Server). It's basic, but better than the command-line. It's in maintenance mode and no new features are likely to be added, so you might consider Visual Studio Code.
  • Visual Studio Code and the PowerShell Extension (on Windows, macOS, or Linux). See also Using VS Code for PowerShell. It's very powerful, but maybe not as well integrated with PowerShell as the ISE.
  • Fiddler - web debugging proxy.

Converting JSON to PowerShell

Most Okta API calls come with sample curl commands with blocks of JSON. To convert from JSON to PowerShell:

  • Change { to @{
  • Change : to =
  • Change , to ; or use a line break instead
  • Change [ to @(, and ] to )
  • Change true, false and null to $true, $false and $null

Here is an example from Assign User to App:

JSON

{
  "id": "00ud4tVDDXYVKPXKVLCO",
  "scope": "USER",
  "credentials": {
    "userName": "user@example.com",
    "password": {
      "value": "correcthorsebatterystaple"
    }
  }
}

PowerShell

@{
  id = "00ud4tVDDXYVKPXKVLCO"
  scope = "USER"
  credentials = @{
    userName = "user@example.com"
    password = @{
      value = "correcthorsebatterystaple"
    }
  }
}

Adding new endpoints

To add a new endpoint, check the documentation for the HTTP verb (e.g. GET, POST, PUT, DELETE) and URL, and convert it into a corresponding PowerShell call.

For example, the documentation for Get User says:

GET /api/v1/users/${id}

The PowerShell code is:

function Get-OktaUser($id) {
    Invoke-Method GET "/api/v1/users/$id"
}

See Modules/OktaAPI.psm1 for more examples.

You can’t perform that action at this time.