Okta provides a number of Out of the Box reports for Okta’s Workforce Identity Cloud (WIC) and Customer Identity Solution (CIS). These reports are based on the System Log and are therefore derived by user activity. A list of these reports can be found here: Report types | Okta
But what if you want a report based on the status of each user, including the total number of users in your tenant?
Okta has a new report which produces a list of accounts by status. Its currently an Early Access (EA) feature and can be enabled via the Settings > Features menu in the Okta Administration console.
See an example below:
For further information on this new report, see the documentation here: User Accounts Report
This report is certainly useful, but for a fully customized report, the Okta API will need to be utilized. The Okta REST based API provides endpoints to configure and query objects within your tenant. The Okta Users API provides operations to manage users in your organization. This includes operations to search and list users. See the Users API doco here: Users | Okta Developer
Writing scripts to call the API, calculate totals and formatting and sending a report is time consuming and resource intensive. The good news is that Okta Workflows can do this for you.
Here is a sample of the type of report that can be produced with Okta Workflows:
The above report can be generated and emailed to a configured list of recipients on a set schedule. It also maintains a history of the previous report and uses the saved data to provide a comparison. The flows used to generate this report can be downloaded from here: Advanced User Reporting Sample Flows
Sample Flow Overview
The workflow has been constructed to process the data in a number of steps. By doing it this way, we can componentize the the logic into separate helper flows which helps with both reuse and in isolating issues.
The workflow starts by extracting all the users with their respective status and dumping the data in a working table (User Export table). This is done by the flow titled [helper] Extract All Users.
This flow uses the List Users with Search card to retrieve all users, regardless of status. The returned data is then streamed to another helper flow [helper] Write User to Table which creates a record on the workflow User Export table for every user returned.
Next, the helper flow titled [helper] Calculate Status Totals searches the User Export table for users with a particular status. The total users for the respective status is then derived using the List Length card. The total count is then written to the User Summary table.
An extract from the [helper] Calculate Status Totals flow is displayed below:
Finally, the helper flow titled [helper] Send Summary Email is called to format and send the report. An extract of this flow is displayed below:
Sample Flow Setup
The rest of this article details how to get the sample flows up and running.
Note: This workflow sample is not suitable for Okta tenants with over 100k of users.
Step 1 – Import Workflow Sample
Within the Okta Workflow console, create a folder for the sample flows. The click on the three dots at the end of the folder name and select Import. Then import the previously downloaded sample workflow folder.
Once imported, the folder should contain the following flows:
- [helper] Calculate Status Totals – Calculates the totals for each user status
- [helper] Extract All Users – Get all users from underlying Okta org
- [helper] Initialize Summary Table – Moves current totals to previous totals
- [helper] Send Summary Email – Sends a user status summary report via email
- [helper] Write User to Table – Creates individual user record in the export table
- [main] Run User Status Report – This is the main flow that is used to run the report
The folder will also contain the following tables:
- Config – Configuration table that holds static name/value pairs
- Execution Dates – Dynamic table that stores the report execution dates
- User Summary – Dynamic table that holds the calculated user status totals
- User Export – Dynamic table that holds all the users extracted from the respective tenant
Step 2 – Configure Workflow Sample
The flows use two connectors:
- Okta Connector
- Office 365 Mail Connector (Can be replaced with GMail Connector)
If either of these connectors don’t exist in your workflow instance, then add them from the connector catalogue now. The Office 365 Mail Connector will require a user account that will be used to send the report.
Next, open flow [helper] Extract All Users and update the Okta List Users with Search card to use your local Okta connector.
Next, open flow [helper] Send Summary Email and update the Send Email card at the end of the flow to use your local Office 365 Mail connector. This card can be replaced with the GMail Send Email card if using Google.
Next, open table Config and import the sample-config-data.csv file downloaded with the sample flows. Once imported, update the value column to your desired values as per the table below:
| Name | Description |
|---|---|
| timezone | Timezone for Date/Time display. See the correct format here: List of tz database time zones |
| recipients | A comma delimited list of email recipients |
| logo | A link to the logo on the resulting email |
| org | The name of your Okta Tenant. This can be in any format and is just used as a display in the resulting report. |
Next, open flow [main] Run User Status Report and click on the clock icon at the bottom of the Schedule Flow card:
This will bring up the schedule popup.
Set the schedule to your desired interval.
Finally, turn each flow on by using the toggle ON/OFF switch. Once all the flows are on, we can now run a test.
Step 3 – Test Report Execution
Even though the main execution flow has been scheduled to run at a particular time, the workflow can be tested at any time.
Open flow [main] Run User Status Report and click the test button at the top of the flow.
The flow will then start execution and the console view will switch to debug. Depending on the number of users in your tenant, the flow may take a few minutes to complete. Additionally, the first time the flow runs, the execution data history will be empty, so the resulting report will just have zeros for the previous set of figures.
The flow history should indicate that execution was successful. Successful flow execution will result in a report being sent to each configured email recipient. If the flow history indicates an error, then flow that caused the error will be indicated with a red exclamation mark. Open the respective flow and go to the flow history. The flow history will indicate why the flow terminated with an error.
What you learned
In this tutorial, you learned how to build a workflow that leverages Okta’s REST based API to create a custom report on user status. You learned:
- The benefits of using Okta Workflows to call Okta’s API and generate a report rather than using custom scripts.
- How the List Users with Search card can be used to retrieve users from an Okta tenant and stream the returned data to a helper flow.
- How the List utility can be used to calculate totals.
- How a HTML report can be formatted and sent via an Email Connector.
More resources
- 🍫 Get help from Workflows specialists during weekly community office hours.
- 📺 Learn from Workflows videos.
- 🛟 Get help from support: discuss a Workflows topic or ask a question.
- 🙋🏻♀️ Join the #okta-workflows channel on MacAdmins Slack to learn and get help from the community.
