Okta-PSModule Documentation
======================
This is not to be confused with or in competition with the official Okta Powershell/CSharp module. This is something I have been building and adding to for a few years. I still need the functionality it provides on a near daily basis so I figured it was time to share.
Getting Started
PreReq
- This Module requires Powershell version 4 or greater (see output from
$PSVersionTable)
PS > $PSVersionTable Name Value ---- ----- PSVersion 6.0.0-rc PSEdition Core GitCommitId v6.0.0-rc OS Darwin 17.4.0 Darwin Kernel Version 17.4.0: Sun Dec 17 09:19:54 PST 2017; root:xnu-4570.41.2~1/RELEASE_X86_64 Platform Unix PSCompatibleVersions {1.0, 2.0, 3.0, 4.0...} PSRemotingProtocolVersion 2.3 SerializationVersion 1.1.0.1 WSManStackVersion 3.0
- This Module will run on both Windows and Mac/*nix version of powershell
Installation
- Download the module (git clone or download the zip)
- Place the module in your PSModulePath hint Read more about PSModulePath Here
Write-Host $env:PSModulePath
- Get an API Token for your Okta Org Getting an API Token
- Create a file called Okta_org.ps1 (example content below) and save it in the directory with the Okta.psd1 and Okta.psm1 files.
<# Okta_org.ps1 #> # Verbose will print various informative messages [Boolean]$oktaVerbose = $true # define the default Okta Org you want to use, useful if you have more than one. [String]$oktaDefOrg = "prod" [Hashtable]$oktaOrgs = @{ prod1 = [Hashtable]@{ baseUrl = [String]"https://yourdomain.okta.com" secToken = [String]"yourApiToken" enablePagination = [boolean]$true pageSize = [int]500 } prod2 = [Hashtable]@{ baseUrl = [String]"https://yourOtherdomain.okta.com" secToken = [String]"yourOtherApiToken" enablePagination = [boolean]$true pageSize = [int]500 } prev = [HashTable]@{ baseUrl = [String]"https://yourDomain.oktapreview.com" secToken = [String]"yourPreviewApiToken" enablePagination = [boolean]$true pageSize = [int]500 } }
Example Installation:
- Open a command prompt
cd %userprofile%\Documents\WindowsPowerShell\Modules
git clone https://github.com/mbegan/Okta-PSModule.git Okta
cd Okta
notepad Okta_org.ps1
- Paste the basic format for the Okta_org.ps1 file listed Above.
- Modify file as required (Update yourdomain, API Token you generated for that org etc)
- Save the file
Basic Usage:
- Launch powershell (or even better, the powershell ise)
- Import the Okta Module
- Use
PS C:\> Import-Module Okta PS C:\> oktaGetUserbyID -oOrg prod -uid mbegan@gmail.com [ GET https://varian.okta.com/api/v1/users/mbegan@gmail.com ] id : 00u103j904jPJACDTXXV status : ACTIVE created : 2014-12-23T22:50:41.000Z activated : 2014-12-23T22:50:41.000Z statusChanged : 2014-12-23T22:50:41.000Z lastLogin : 2015-01-30T23:48:05.000Z lastUpdated : 2015-01-30T23:41:41.000Z passwordChanged : 2015-01-30T23:41:41.000Z profile : @{email=mbegan@gmail.com; firstName=Matt; lastName=Egan; login=mbegan@gmail.com; mobilePhone=; secondEmail=} credentials : @{password=; recovery_question=; provider=} _links : @{resetPassword=; resetFactors=; expirePassword=; forgotPassword=; changeRecoveryQuestion=; deactivate=; changePassword=}
When elements are returned in the API they are powershell objects, you can treat them as such.
An example of something I do often.
PS C:\Users\megan> $oktauser = oktaGetUserbyID -oOrg prev -uid mbegan@gmail.com [ GET https://varian.oktapreview.com/api/v1/users/mbegan@gmail.com ] PS C:\Users\megan> $groups = oktaGetGroupsbyUserId -oOrg prev -uid $oktauser.id [ GET https://varian.oktapreview.com/api/v1/users/00u3j3jj2cLstvJL70h7/groups ] PS C:\Users\megan> foreach ($group in $groups) {write-host $group.profile.name $group.id} Everyone 00g326179lGHZOYPWXCD okta.throwaway 00g3hyrge0QfpnvM80h7 PS C:\Users\megan> oktaDeleteUserfromGroup -oOrg prev -uid $oktauser.id -gid $groups[1].id [ DELETE https://varian.oktapreview.com/api/v1/groups/00g3hyrge0QfpnvM80h7/users/00u3j3jj2cLstvJL70h7 ]
Some very basic examples, it can do much more.
It supports pagination, so grabbing ALL of your users or groups is not a problem.
I'll add more details on usage later, if you have a specific use case ask away i'll post an example.
Also browse on over to Okta community for more discussion
Available Commands
- oktaActivateUserbyId
- oktaAddUseridtoGroupid
- oktaAddUsertoRoles
- oktaAdminExpirePasswordbyID
- oktaAdminUpdatePasswordbyID
- oktaAdminUpdateQandAbyID
- oktaAuthnQuestionWithState
- oktaChangePasswordbyID
- oktaChangeProfilebyID
- oktaCheckCreds
- oktaCheckCredsOld
- oktaConvertGroupbyId
- oktaConverttoSecureString
- oktaConvertUsertoFederation
- oktaDeactivateUserbyID
- oktaDeleteGroupbyId
- oktaDeleteUserfromGroup
- oktaDelUserFromAllGroups
- oktaDelUseridfromAppid
- oktaDelUseridfromGroupid
- oktaExternalIdtoGUID
- oktaForgotPasswordbyId
- oktaGetActiveApps
- oktaGetAppbyId
- oktaGetAppGroups
- oktaGetAppLinksbyUserId
- oktaGetAppProfilebyUserId
- oktaGetAppsbyUserId
- oktaGetFactorbyUser
- oktaGetFactorsbyUser
- oktaGetGroupbyId
- oktaGetGroupMembersbyId
- oktaGetGroupsAll
- oktaGetGroupsbyquery
- oktaGetGroupsbyUserId
- oktaGetMasterProfile
- oktaGetprofilebyId
- oktaGetProfileMappingBySchema
- oktaGetRolesByUserId
- oktaGetSchemabyID
- oktaGetTypebyID
- oktaGetTypes
- oktaGetUserbyID
- oktaGetUsersbyAppID
- oktaGetUserSchemabyType
- oktaListActiveUsers
- oktaListDeprovisionedUsers
- oktaListUsers
- oktaListUsersbyAttribute
- oktaListUsersbyDate
- oktaListUsersbyStatus
- oktaNewPassword
- oktaNewUser
- oktaProcessHeaderLink
- oktaPutProfileupdate
- oktaResetFactorbyUser
- oktaResetFactorsbyUser
- oktaResetPasswordbyID
- oktaSetAppidCredentialUsername
- oktaUnlockUserbyId
- oktaUpdateApp
- oktaUpdateAppExternalIdbyUserId
- oktaUpdateAppProfilebyUserId
- oktaUpdateUserbyID
- oktaUpdateUserProfilebyID
- oktaVerifyMFAnswerbyUser
- oktaVerifyOTPbyUser