Merge pull request #81 from okta/lr-prepare-release-2.0

Prepare 2.0 release

Author: laura-rodriguez

CHANGELOG.md

@@ -2,6 +2,23 @@
 
 Running changelog of releases since `1.0.0`
 
+## 2.0.0
+
+Starting with the 2.x series, the Okta.PowerShell module supports PowerShell 7+.
+
+### New Features
+
+- Added support to revoke tokens (#67)
+- Exposed a new exception called `OktaApiException` for API errors (#78)
+- Updated readme with new samples such as "Create custom objects", "configure a web proxy", "List resources that match a filter criteria", "Get logs" and "Error handling".
+
+### Bug fixes
+
+- Fixed "Parameter existence checking in functions treats $false value as no parameter" (#56)
+- Fixed "Rate limit functionality doesn't work" (#61)(#70)
+- Fixed "Get-OktaLogs changes the required date format for "since" and "until" query params" (#55)
+- Improved testability (#74)  
+
 ## 1.0.0
 
 - We're excited to release the first generally available version of the Okta.PowerShell module. Please, check out the [README](./README.md) file to learn more about its capabilities.

MIGRATING.md

@@ -4,4 +4,36 @@ This module uses semantic versioning and follows Okta's [library version policy]
 
 ## Migrating from 1.x to 2.x
 
-* We removed the `Invoke-OktaRemoveAccessToken` and replaced it by `Invoke-OktaRevokeAccessToken` which will revoke your access token and remove it from your configuration object.
+* We removed the `Invoke-OktaRemoveAccessToken` command and replaced it by `Invoke-OktaRevokeAccessToken` which revokes your access token and remove it from your configuration object. You can execute the following command to [revoke your token](https://developer.okta.com/docs/guides/revoke-tokens):
+
+```powershell
+Invoke-OktaRevokeAccessToken
+```
+
+* We added a new exception called `OktaApiException` which is thrown when the Okta API returns 4xx/5xx responses. You can catch an `OktaApiException` and access the Okta API error details. For example, if the API returns a 429 response with the following content: `{"errorCode":"E0000047","errorSummary":"API call exceeded rate limit due to too many requests.","errorLink":"E0000047","errorId":"oae6dB62BdhRFCF_9ltxiklFQ","errorCauses":[]}`, you can access these details from the exception:
+
+```powershell
+    try{
+        $Result = Invoke-OktaListApplications
+    }
+    catch{
+        $_.Exception.StatusCode.Value__ | Should -Be 429;
+        $_.Exception.ErrorCode | Should -Be "E0000047"
+        $_.Exception.ErrorSummary | Should -Be "API call exceeded rate limit due to too many requests."
+        $_.Exception.ErrorLink | Should -Be "E0000047"
+        $_.Exception.ErrorId | Should -Be "oae6dB62BdhRFCF_9ltxiklFQ"
+        $_.Exception.ErrorCauses | Should -BeNullOrEmpty
+        $_.Exception.Headers | Should -Not -Be $null
+    }
+```
+
+* We updated the OpenAPI spec for the System Log API, and the query parameters `since` and `until` changed their type from `System.Nullable[System.DateTime]` to `String`. Since the System Log API requires `since` and `until` query parameters to be ISO 8601 compliant timestamp, make sure to format dates accordingly:
+
+```powershell
+$since = (Get-Date).AddMonths(-6).ToString("yyyy-MM-ddTHH:mm:ssZ")
+$until = (Get-Date).ToString("yyyy-MM-ddTHH:mm:ssZ")
+Get-OktaLogs -since $since -until $until
+
+```
+
+* We fixed the rate limit functionality which wasn't working as expected. Check out the [PR #78](https://github.com/okta/okta-powershell-cli/pull/78) for more details.

README.md

@@ -35,7 +35,8 @@ This library uses semantic versioning and follows Okta's [library version policy
 
 | Version | Status                    |
 | ------- | ------------------------- |
-| 1.x | :heavy_check_mark: Stable |
+| 2.x | :heavy_check_mark: Stable |
+| 1.x | :warning: Retiring on Aug 21st 2025 |
 
 The latest release can always be found on the [releases page][github-releases]. For more information about our SDKs' lifecycle, check out [our docs](https://developer.okta.com/code/library-versions/).
 
@@ -52,14 +53,13 @@ If you run into problems using the Okta PowerShell module, you can
 This PowerShell module is automatically generated by the [OpenAPI Generator](https://openapi-generator.tech) project:
 
 - API version: 3.0.0
-- SDK version: 1.0.0
 - Build package: org.openapitools.codegen.languages.PowerShellClientCodegen
     For more information, please visit [https://developer.okta.com/](https://developer.okta.com/)
 
 <a id="frameworks-supported"></a>
 The Okta PowerShell module is compatible with:
 
-- PowerShell 6.2 or later
+- PowerShell 7.0 or later
 - Mac/Windows
 - OIE and Classic Okta orgs
 
@@ -356,6 +356,55 @@ $NewApp = Initialize-OktaOpenIdConnectApplication -Label "New App" -SignOnMode "
 
 > Note: For more API samples checkout our [tests](https://github.com/okta/okta-powershell-cli/tree/main/tests/)
 
+### List resources that match a filter criteria
+
+Certain Okta APIs allow you to list a subset of resources that match a supported filter expression, query, or search criteria. For example, the Groups API enables you to provide filter criteria via query parameters to return a subset of groups. **These query parameters require URL encoding, which is handled internally by the Okta.PowerShell module**. This ensures that your queries are correctly formatted and processed by the Okta API without any additional effort on your part.
+
+#### List groups using the `search` parameter
+
+* Search groups that are of the type `OKTA_GROUP`:
+
+```powershell
+Invoke-OktaListGroups -Search 'type eq "OKTA_GROUP"'
+```
+
+Internally, the Okta.PowerShell module will encode the search criteria as `/api/v1/groups?search=type+eq+%22OKTA_GROUP%22`.
+
+* Search groups which name is equals to `IAM Team`:
+
+```powershell
+Invoke-OktaListGroups -Search 'profile.name eq "IAM Team"'
+```
+Internally, the Okta.PowerShell module will encode the search criteria as `/api/v1/groups?search=profile.name+eq+%22IAM+Team%22`.
+
+#### List groups using the `filter` parameter
+
+* Filter groups that are of the type `OKTA_GROUP` with profile updated after 11/11/2015
+
+```powershell
+Invoke-OktaListGroups -Filter 'type eq "OKTA_GROUP" and lastUpdated gt "2016-11-11T00:00:00.000Z"'
+```
+
+Internally, the Okta.PowerShell module will encode the filter criteria as `/api/v1/groups?filter=lastUpdated+gt+%222015-10-05T00%3a00%3a00.000Z%22`.
+
+* Filter groups by ID
+
+```powershell
+$GroupId = "00g6hmia52o0aTHx35d7"
+Invoke-OktaListGroups -Filter "id eq `"$GroupId`""
+```
+> Note: Notice `$GroupId` is enclosed in double quotes.
+
+Internally, the Okta.PowerShell module will encode the filter criteria as `/api/v1/groups?filter=id+eq+%2200g6hmia52o0aTHx35d7%22`.
+
+#### List groups using the `q` parameter
+
+Finds a group that matches the name property
+
+```powershell
+Invoke-OktaListGroups -Q "everyone"
+```
+
 ### Get logs
 
 Since the System Log API requires `since` and `until` query params to be ISO 8601 compliant timestamp, make sure to format dates accordingly: