Getting started with IO

This section helps you get started with the Identity Orchestrator (IO) by walking through the process of creating your first flow. By the end of this section, you'll understand how to access IO, create a basic authentication flow, and test it.

Prerequisites

Before you begin, ensure you have:

• Access to the OneWelcome Identity Platform
• Administrative privileges for your tenant
• Basic understanding of user authentication workflows
• Familiarity with identity management concepts

Accessing IO

1. Log in to the OneWelcome Identity Platform console.

2. In the left pane, navigate to Identity Orchestrator.

You'll see a list of flow categories

The IO interface consists of:

• Flow categories: Organize flows by purpose (Authentication, Self-Service, Admin, and so on).
• Flow list: View and manage existing flows.
• Flow designer: Create and edit flows with the visual editor.

Create your first flow

Let's create a simple login flow as an example. This process demonstrates the core concepts of IO.

Step 1: Create a new flow

1. In the left pane, select Identity Orchestrator.

2. Select the Authentication category.

3. In the top-right corner, select Add.

4. In the configuration dialog box, enter the flow information:

5. Flow Type: Select Login.

6. Name: Enter My First Login Flow.

7. Description: Enter Simple username/password login.

8. Initialize: Select Creates an empty flow.

9. Select Add to create the flow.

The flow designer opens with an empty canvas.

Step 2: Add the start node

The Start node is the entry point for your flow. For authentication flows, it provides different output connectors based on the user's authentication state.

Every flow begins with a Start node:

1. In the top-left corner, select Add Node.

2. Search for Start or find it in the node list.

3. Drag the Start node onto the canvas.

Step 3: Add user input collection

Now add a form to collect the username and password:

1. Open the node palette again.

2. Find and drag the Frontend - Form node onto the canvas.

3. Connect the Not authenticated output of the Start node to the input of the Form node.

4. Select the Form node to open its configuration.

The form already includes Username and Password fields by default.

1. Create a Success output connector:

   • In the Variable Output Table tab, add an element with these settings:

   • Submit Element ID: login

   • Output: Success

2. Store the form data in a variable called user:

   • In the Save in the flow store tab, use these settings:

   • Click Select all to save both username and password.

   • Variable name: Enter user

3. Click Done to save the node configuration.

Step 4: Add authentication logic

Now add a node to authenticate the user:

1. Add an Authenticate User node to the canvas.

   The Authenticate User node validates the credentials against your identity store and provide Success or Failure outputs.

2. Connect the Success output of the Form node to the input of the Authenticate User node.

3. Open the Authenticate User node configuration.

4. Configure the authentication:

   • Username field: Enter {{user.username}}.

   • Password field: Enter {{user.password}}.

   These {{variable}} expressions retrieve values from the session.

5. Keep other settings as default.

6. Click Done.

Step 5: Add end nodes

Every flow must end with either a success or failure end node:

1. Add a Flow - End Success node to the canvas.

2. Connect the Success output of the Authenticate User node to the End Success node.

3. Add a Flow - End Failure node to the canvas.

4. Connect all Failure outputs (from Form and Authenticate User) to the End Failure node.

Your complete flow should look like this:

    #!
    [Start] → [Form] → [Authenticate] → [End Success]
                ↓            ↓
         [End Failure] ← (Failure paths)

Step 6: Save the flow

1. At the bottom-right, select the Settings gear icon.

2. Select Save Flow.

   Your flow is now saved

Understanding the flow

Let's review what happens when a user executes this flow:

1. User arrives: The Start node checks if the user is already authenticated.

2. Not authenticated: Flow proceeds to the Form node.

3. Form displays: The user sees the username and password fields.

4. User submits: Form data is stored in the user variable.

5. Authentication: The Authenticate User node validates the credentials.

6. Success: The user proceeds to End Success and is logged in.

7. Failure: The user proceeds to End Failure and sees an error.

Test your flow

Before you activate the flow for production, test the flow:

1. Click Settings.

2. Select Copy Flow URL.

3. Open the URL in a browser (or use your API client).

4. Test the login process:

   • Enter valid credentials: Should succeed

   • Enter invalid credentials: Should fail

   • Test edge cases (empty fields, special characters, and so on)

Activate the flow

After you finish testing, activate the flow:

1. In the flow list, next to your flow, select the Edit pencil icon.

2. Select the Active check box.

3. If this is the primary login flow, select Default flow.

4. Click Save.

Your flow is now active and ready for users.

Common IO patterns

Add multiple authentication methods

To support multiple authentication options (such as password and OTP):

1. Add additional authentication nodes in parallel.

2. Use groups to organize options.

3. Connect each method's Success output to the End Success node.

4. Connect Failure outputs to End Failure.

Implement conditional logic

To add branching, use Condition Wizard nodes:

1. Between steps, add a Condition Wizard node.

2. Configure conditions based on user attributes or flow variables.

3. Route different user types to different authentication methods.

Collect additional information

Add more Form nodes to collect data progressively:

1. Add multiple Form nodes in sequence.

   Each form stores data in different variables.

2. Combine data before final submission.

Next steps

Now that you've created your first flow, explore more advanced topics:

• Design flows: Learn advanced flow design patterns.
• Flow categories: Explore different flow types.
• Node types: Discover all available nodes.
• Flow versioning: Manage flow versions.
• Import and export: Share flows between environments.

Troubleshooting IO flows

Flow doesn't appear in the list

• Ensure that you saved the flow.

• Check that you're in the correct flow category.

• Refresh the page.

Authentication always fails

• Verify the variable names match: {{user.username}} and {{user.password}}.

• Check that the form is saving values correctly.

• Ensure that the identity store is configured properly.

Form doesn't display

• Verify that the Start node output is connected to the Form node input.

• Check that the flow is active.

• Review the browser console for errors.

Best practices for IO flows

1. Name flows clearly: Use descriptive names that indicate purpose.

2. Add descriptions: Document what each flow does.

3. Test thoroughly: Test all paths through the flow before activating.

4. Use variables wisely: Name variables descriptively.

5. Handle all outputs: Ensure every node output is connected.

6. Version control: Create new versions before making major changes.

7. Keep flows simple: Break complex workflows into smaller, reusable library flows.

Getting help

If you need assistance:

• Review the detailed documentation for each component.

• Check the flow execution logs for errors.

• Contact your OneWelcome Identity Platform administrator.

• Refer to the OneWelcome Identity Platform support resources.