Automating Realm Creation in Okta with Workflows

The new Realms feature in the Okta Workforce platform and the Secure Partner Access (SPA) product built on top of it are designed to make management of discrete user populations simpler. Realms can be managed via the Okta Admin Console. But what about when you want to automate the process, such as onboarding a large number of partners. Okta provides various APIs for this, and some of them are baked into the Okta Realms Workflows connector.

This article looks at how the APIs can be used in Workflows to automate the process of realm creation as well as all the objects related to realms, such as realm assignments, admin groups and admin resource sets.

Introduction

When working with realms there are some constructs you need to be familiar with:

• Realms – the definition of the containers for storing user populations.
• Realm assignments – rules to define which users are assigned to which realm, normally through some user profile attribute condition.
• Administration roles – users need to be assigned to administration roles to be able to manage users in a realm. Roles define the scope of permissions (what object types and attributes can be managed by admins). There is a default role generated with the Secure Partner Access product called “Partner Admin” covering the standard set of permissions.
• Administration resource sets – what objects and administrator can manage. Whereas roles define the “what a user can do”, resource sets define “what they can do it on”.
• Administration groups and assignment – whilst you can assign users to a role+resource set combination, it’s cleaner to assign a group, then manage the group membership (perhaps with Okta Identity Governance)

If you were to create a separate realm and set of related objects for Secure Partner Access, the flow would be similar to this:

1. Create the Realm
2. Create one or more Realm Assignments to define which users are assigned. You would enable it, and could rerun the assignment rules to move users into the realm.
3. Create an administrators group and assign users to it.
4. Create an administration role if the supplied one doesn’t cover what you want.
5. Create an administration resource set for the new realm and it’s users, and optionally any groups or applications you wish to allow the realm admins to manage membership/assignment for.
6. Assign the admin group to the role + resource set.
7. Assign the admin group to the Secure Partner Access portal.

Most of these steps are covered in the flow described below. Note the administration configuration for realms is explored in Assigning Administrators to Realms in Okta.

Overview of the Flow

The set of workflows built to implement this automation have a main flow and associated sub-flow and some utilities. The main flow in this case is a delegated flow, so it could be exposed to an administrator to enter the required attributes. Or you could have a main flow that reads a CSV file into a table then processes each record in turn.

The overall flow is:

1. Create a new realm
2. Create a new realm assignment, including an assignment condition to put users into that realm (it does not activate or run the new rule – this can be done by an admin later)
3. Create an admin group (it does not assign users – this can be done later)
4. Build an administrator resource set for the realm and assign the admin group to the standard SPA role and new resource set
5. Assign the admin group to the Partner Admin Portal so an admin can access the portal (from their Okta Dashboard) to manage users

We will walk through the details later on, but most of the flows are leveraging Okta APIs, to manage Realms, Realm Assignments and get Org details. The Okta workflows connector is used to create the group and assign the group to the portal application. There is also an Okta Realms workflows connector, but it uses the earlier realms API that does not support SPA, so direct API calls (Custom API Actions) on the standard Okta connector were used as needed.

Running the Flow

Lets walk through the execution of the main flow.

An administrator goes to the Delegated flows menu item and runs the flow.

It prompts for the attributes (inputs) used in the flow.

Most of these inputs are the labels for each of the objects that will be created.

Of note is the Assignment Condition input. This is the condition that will assign users to the new realm. In this case it will select all users where the primary email field contains “deadwoods.com”. Note the escaping of quotes.

When the flow runs, it will execute a number of sub flows.

These follow the steps listed above. As a result of this, there is a new realm created.

A new realm assignment is created.

This has the condition entered earlier and will assign matching users to the new realm. Note that the status is INACTIVE. We could activate it in the relevant workflow, but you would probably want to review the new assignment rule in the context of the others and their priorities before activating.

A new Okta group has been created and assigned to the Partner Admin Portal.

The new admin group has been assigned to the combination of Partner Admin role (the default one with SPA) and the new resource set.

If we look at that new resource set, we can see it is assigned two resources – the new realm itself and the users in that realm (none yet). It does not have any applications or groups assigned to the resource set.

The realm, and realm-related objects, are ready to use. You could assign one or more users to the new group and they would automatically get the admin rights to manage the users in the realm. You could manually assign users to the realm, or activate the new realm assignment rule and have the users automatically assigned.

As mentioned earlier, this flow has been built as a delegated flow to allow an administrator to run it from the Admin Console. But you could apply the same approach with reading a CSV with all the input fields into a table and processing each row.

Details of the Flows

The components in this include: a connection, a table, a main flow and some calling flows, and some utility flows.

Connection

You need to allow the relevant Okta API scopes in the Okta Workflows OAuth application.

• okta.applications.manage
• okta.groups.manage
• okta.orgs.read
• okta.realmAssignments.manage
• okta.realmAssignments.read
• okta.realms.manage
• okta.realms.read

Whilst the normal Okta connector can perform some of the operations needed, you need to set some customized scopes. So you either modify your existing connector or create a new one. You need customized scopes on the connector. You can leave the default scopes selected under Customzie scopes (advanced) or trim them down. You will need to manage groups, and application memberships. You will also need to add the following custom scopes:

• okta.orgs.read
• okta.realmAssignments.manage
• okta.realmAssignments.read
• okta.realms.manage
• okta.realms.read

With the connection authorised, all the operations in the flows can run.

Table

There is a single table called Env Vars. It has two columns, varname and varvalue.

It needs to have a single row, with varname of “APIToken” and varvalue of the API token you setup in your org. This is used as authorization for each API call.

Main Flow

There is a single main flow that is called as a delegated flow.

It prompts for the input fields shown earlier, then calls subflows to:

1. Get’s the API token from the table as an authorization object for the API calls
2. Get’s the org id from a simple API call as this is used in later flows
3. Create a realm (M10 flow)
4. Create a realm assignment (M20)
5. Create an admin group (M30)
6. Create an administration resource set, then assign the group to the SPA default role and this resource set (M40)
7. Assign the admin group to the Partner Admin Portal (M50).

We will explore these flows in the following sections.

M10 Flow

The first subflow will create the realm using the name passed into it and the realm API.

The first two cards build the Body object for the API call. The body includes the name and the realmType fields. For the realm to be accessible in the Partner Admin Portal, the type must be “PARTNER”.

{
   "profile": {
      "name": "Deadwoods Realm",
      "realmType": "PARTNER"
   }
}

The new Realm ID is returned to the calling flow.

M20 Flow

The second subflow creates the assignment for the realm.

It uses a simple compose card to build up the Body object then calls the API to create the assignment. The Body object could be built up out of a series of Object Construct cards, but that would have taken many cards and the body structure does not change.

The Body object is shown below. It’s basically saying, for users where the condition is matched (in our example it’s where primary email profile attribute (user.profile.email) contains “a set string”deadwoods.com) then assign the user to the realm specified by realmId. Notice that there is a profileSourceId field set to the Okta org. Realm assignments allow specifying different identity sources (Okta profile or a directory integration).

{
   "actions": {
      "assignUserToRealm": {
      "realmId": "Realm ID"
      }
   },
   "conditions": {
      "expression": {
         "value": "Assignment Condition"
         },
      "profileSourceId": "Org ID"
   },
   "name": "Assignment Name",
   "priority": 0
}

You could set the priority here, but we’ve chosen to leave it for when an admin would review this assignment rule in the context of the others before activating.

M30 Flow

The third subflow creates an Okta group which will represent the administrators of this realm.

It builds a description, creates the group using the standard connector card and returns the new group ID to the calling flow.

M40 Flow

There are multiple stages in the flow to assign the new admin group to the role + resource set.

First, it searches for the SPA-generated “Partner Admin” role and gets the ID of it.

Next it creates a new resource set for the new realm.

It constructs strings to represent the description of the new resource set, and the two resources to go into the resource set. They use the ORN nomenclature to refer to the new realm and the users in the realm (including reference to the Realm ID and the Org ID).

The two resource strings are put into a list and assigned to the body object. The API will then create the resource set.

A sample body object is:

{
  "description": "Resource set for users and realm Deadwoods Realm",
  "label": "Deadwoods Realm Resources",
  "resources": [
    "orn:oktapreview:directory:<orgid>:realms:<realmid>",
    "orn:oktapreview:directory:<orgid>:realms:<realmid>:users"
  ]
}

Finally it assigns the group to the role + resource set combination.

Note that the assignment is of type CUSTOM.

Thus it has found the id of the role, created a new resource set and got the id of that, then assigned both (by ids) to the admin group.

M50 Flow

The final subflow assigns the new admin group to the portal app. It searches for the app, named “Partner Admin Portal”, then assigns the group to it.

These are standard Okta connector card actions.

Utility Flows

The last two flows used are utility flows. One will pull the API Token from the Env Vars table, format an Authorization object from it and return that to the calling flow.

The other will lookup the Org to get the org ID. This requires a Custom API Action as there are no standard actions for this on the Okta connector.

The Org ID is returned to the calling flow.

This concludes the exploration of the workflows in the solution.

Conclusion

The new Realms feature in Okta, and the Secure Partner Access product leveraging it, can be managed in the Okta Admin Console. But a partner scenario where partners may be onboarded in bulk or there is a steady flow of new partners, calls for some form of automation. Okta provides APIs to manage realms and their related objects for this purpose.

This article has shown an example of how a set of workflows could be built to automate the creation of a realm, and related realm assignment rule, admin group, admin resource set and assignment to the role+resource set and portal app. This is a standard flow that is called as a delegated flow, but could be the basis of a more advanced mechanism (like reading from a CSV). The article explored each of the flows and who they use the relevant APIs. This should provide enough detail if you wanted to build your own.