IBM Developer

Tutorial

Automate a secure user onboarding journey using IBM Security Verify

Collect and validate user details in a single secure flow

By Sushmita Das, Rahul K.P., Suraj Kanth

On this page

When an organization focuses on digital transformation, it’s vital that they ensure a quality customer experience while maintaining security. Brands that deal with consumers need to ensure their B2C applications continue to represent a trusted, valuable experience and the best possible image in the digital world. A small mistake can deter customers, impacting revenue and the larger brand image.

This tutorial shows you how IBM Security Verify SaaS can help both your users’ experience and security. Using Verify SaaS, you can build complex user journeys for a consumer’s interaction with your brand. You will collect and update user details, fetch information from a third-party repository, and validate the user in a single enhanced flow. You’ll also see how app developers can focus on their core development tasks without worrying about the user journey.

The image that follows depicts the flow that you will learn in this tutorial. We’ll present a sample that gets you started with identity orchestration, but you can build and customize workflows based on your specific requirements.

alt

Consider a scenario where you are migrating your consumers’ identity and access management from Microsoft Active Directory to Okta at runtime, after they are successfully authenticated by Verify SaaS.

In this flow, a valid user available on Verify SaaS tries to log in. The backend logic checks the value of the user attribute migratedtookta. If the value is null or "false", the user is redirected to Active Directory for authentication. If the authentication is successful, the user is created in Okta using the Okta REST API. Details like firstname, lastname, userlogin and email would be sent in the API invocation request. Post that the attribute value would be updated to "true" in Verify SaaS.

alt

If the value of the attribute is "true" during the validation, the user is redirected to Okta for authentication using Verify SaaS.

IBM Security Verify SaaS

IBM Security Verify SaaS is a cloud Identity Access Management (IAM) solution. It provides secure, frictionless access to applications supporting all modern and legacy protocols.

Designed for B2E, B2B and B2C, Verify caters to a wide range of use cases in an enterprise. Orchestration enables low-code or no-code configuration, which allows administrators to configure experiences by using a drag-and-drop editor. Orchestration capabilities minimizes writing code and removes the need to have technical domain knowledge to deliver business outcomes enabled by IAM.

Verify SaaS’s orchestration capabilities are delivered through its Flow Designer using a low-code/no-code approach. The following scenarios can be orchestrated:

  1. User journey: The user’s experiences and how an organization interacts with their customers during, for example, account registration, login, and password/username recovery.
  2. Fraud and risk: How risky or fraudulent users are mitigated by orchestration.
  3. Identity agnostic modernization: Helps organizations manage, migrate, and enforce security on identities from one IAM solution to another. For example, migrating users from a legacy directory to a new IAM system.

Next, you’ll learn how to build a flow using IBM Verify SaaS and Okta REST APIs to migrate users.

Prerequisites

  • An IBM Security Verify SaaS tenant. Register for a free trial.
  • Enable the Flow Designer, if it is not yet enabled:
    alt
  • On-premises Microsoft Active Directory
  • Free Okta/Entra trial instance

Note: This tutorial shows you the integration with Okta but you can use any provider that supports the SAML/OIDC protocol.

Steps

Step 1: Clone the repository

Download the required files from this GitHub repository. You will need to make some changes later in the tutorial.

Step 2: Register Microsoft Active Directory as an identity agent

  1. Log in to your Verify SaaS tenant and go to Integrations > Identity agents.
  2. Click Create agent configuration. alt
  3. Select Authentication as the purpose and select the LDAP tile. Click Next. alt
  4. In the Connection settings, provide the LDAP connection details.
  5. For the attribute mapping, map the identity provider attributes from the identity provider to the Verify Cloud Directory attributes.
  6. In Next steps, complete the following actions:
    1. Select View API credentials and use the Copy to clipboard icon to copy and store the Client ID and Client secret.
    2. Download the bridge agent from the IBM Container Repository (ICR). Refer to Installing and configuring the Verify Bridge on Docker for further details.
  7. The configuration is added to Identity agents and the identity provider is listed in the Authentication > Identity providers tab.
  8. In the Identity Linking section, select Enable Identity linking for this identity provider. Select a Unique user identifier from the drop-down list.
  9. Enable the Just-in-time provisioning option.
  10. Under Just-in-time provisioning, select the Provision password migration checkbox to enable user password migration to the Cloud Directory. alt

Step 3: Create a custom attribute

A custom attribute is used to store the value that determines whether the user is migrated to Okta or not. The flag can be called “Migrated to Okta”.

  1. To create a custom profile attribute, in the left menu, click Directory > Attributes > Custom attribute. alt
  2. Review the values for different fields after saving the custom attribute, as in the following image: alt
  3. To attach a rule, in the left menu, click Authentication > Identity provider > Global settings > Attribute mapping.
  4. A custom rule is used to create the user with the login flow and then map it to a custom attribute (in this case, “Migrated to Okta”). In this way, the user is created at runtime; when the user logs in next time, the attribute value determines the login experience that needs to be offered. Copy the following script and use it with the custom attribute “Migrated to Okta”.
statements:
- context: >
    oktaTenant := "https://<trial-tenant>.okta.com"
- if:
    match: idsuser.getValue("JIT_realmName") != "ibmgsilabs.com"
    block:
        - return: "false"
- context: >
    oktaToken := "yourOktatoken"
- context: >
    r := hc.Post(context.oktaTenant + "/api/v1/users", {
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "SSWS " + context.oktaToken
    }, jsonToString({
        "profile": {
            "firstName": idsuser.getValue("givenName"),
            "lastName": idsuser.getValue("sn"),
            "email": idsuser.getValue("mail"),
            "login": idsuser.getValue("mail")
        },
        "credentials": {
            "password" : { "value": idsuser.getValue("password") }
        }
    }))
- context: rstatus := string(context.r.responseBody.status)
- if:
    match: context.rstatus == "ACTIVE"
    block:
        - return: "true"
- return: "false"

Note: Replace trial-tenant and yourOktatoken with the actual values in your environment.

The attribute mapping should look like the following image: alt

Step 4: Create a custom branding

The UI is customized to collect a user name initially and present an error page in case of an event failure. You can create a custom theme for the following two pages.

  • custom_page1.html: Username requested in this page
  • custom_page2.html: Error page for event failure

To create your custom branding, complete the following steps:

  1. In Verify SaaS, click User experience > Branding.
  2. Create a new branding theme called "LDAP Migration". See Downloading and uploading a master theme.zip with user interface for detailed steps.
    alt
  3. Click on the theme tile to view the file tree.
  4. Expand workflow > pages and click the three vertical dots next to custom_page1.html.
  5. From the list, select Upload. (Note: This file is available in the GitHub repo that you downloaded earlier in Step 1, flows > ldap_to_okta_migration > pages > templates > workflow > default.) alt
  6. In workflow > pages, click on the three vertical dots next to custom_page2.html and select Upload. The file is present at the same location as earlier. See Step 1: Clone the repository for the file.

Step 5: Configure Okta to work with IBM Security Verify

We need to redirect the user to Okta for authentication based on the custom attribute "Migrated to Okta" value. You therefore need to integrate it with IBM Verify before you can use it.

  1. Generate a token so that API can be executed on your tenant. Type the name LDAPtoOkta. alt
  2. Configure a web application to establish a federation between Okta and IBM Security Verify.
  3. In the left menu, click Applications > Applications > Create App integration > OIDC. alt
  4. Choose the grant type that you want to configure. By default, the Authorization Code Grant type is configured.
  5. Provide your sign-in redirect URIs. The values come from IBM Security Verify. For example, https://<your_verify_tenant>/auth/redirect.
  6. Make a note of the client ID and secret. You will require these when you configure IBM Security Verify.

Step 6: Configure the identity provider

You now need to ensure the primary identity source is set to “Cloud Directory” and create identity sources for Active Directory and Okta.

In this tutorial, Active Directory is used as the primary source of authentication if the user details aren’t available in Okta yet. Note: You registered Active Directory as an identity agent on Verify SaaS in Step 2, above.

Okta is a third party IDP that is OIDC compliant. Okta must be integrated because the user will be redirected to it for authentication.

  1. In the left menu, click Authentication > Identity Providers.
  2. Click Add Identity Provider and click the OIDC Enterprise tile. alt
  3. Provide Okta details such as clientid, clientsecret, and well-known URL. Note: For more details, see Configuring an OIDC Enterprise identity provider in the IBM Security Verify documentation. alt

Step 7: Import the workflow

  1. From the left menu, click User experience > Flow designer.
  2. Click the Import icon (adjacent to the Create flow button). alt
  3. Enter the details and upload the .bpmn file located at flows > ldap_to_okta_migration . ldap_to_okta_migration.bpmn
  4. Click Import flow. alt
  5. Import the .bpmn file. alt
  6. Confirm that the designer screen has opened and is displaying the flow. alt
  7. Select the SetVars function and modify the okta_tenant and onprem_realm values. Note that onprem_realm is the realm name of your LDAP or Active Directory identity source. alt
  8. Select the Ask for username task and set the theme to LDAP Migration. alt
  9. Select the Resolve IdP task and replace the code with the following:
     statements:
 - context: "theme := has(ctx.themeId) ? ctx.themeId : ''"
 - context: "identitySourceIds := has(ctx.identity_source_ids) ? ctx.identity_source_ids : ''"
 - context: "postUrl := has(ctx.Target) && ctx.Target != '' ? ctx.Target : 'https://' + ctx.__tenantid + '/usc'"
 - context: "realm := user != null && user.getCustomValue('migratedToOkta') == 'true' ? ctx.okta_tenant : ctx.onprem_realm"
 - if:
       match: user != null
       block:
         - if:
             match: user.getCustomValue("migratedtookta") == "true"
             block:
               - context: "realm := ctx.okta_tenant"
               - return: >-
                   {
                     'loginUrl': 'https://' + ctx.__tenantid + '/idaas/mtfim/sps/idaas/login?runtime=true&login_hint=' + ctx.username + '&realm_hint=' + context.realm + '&themeId=' + context.theme + '&identity_source_ids=' + context.identitySourceIds,
                     "post_url": context.postUrl,
                     'realm': context.realm
                   }
         - if:
             match: user.getCustomValue("migratedtookta") == "false" || string(user.getCustomValue("migratedtookta")) == ''
             block:
               - context: "realm := ctx.onprem_realm"
               - return: >-
                   {
                     'loginUrl': 'https://' + ctx.__tenantid + '/idaas/mtfim/sps/idaas/login?runtime=true&login_hint=' + ctx.username + '&realm_hint=' + context.realm + '&themeId=' + context.theme + '&identity_source_ids=' + context.identitySourceIds,
                     "post_url": context.postUrl,
                     'realm': context.realm
                   }
    Note: You can add debug statements in the YAML to get the values of the variables: - debug: '"realm is : " + string(context.realm)' alt
  10. Click Save and Publish.

Step 8: Running the flow

  1. In the flow Settings tab, copy the Execution URL value. alt
  2. Open a private browser window or a completely different browser and paste the URL.
  3. Enter the username and click Continue. The user is redirected to the on-prem LDAP identity source login.
  4. Log out and paste the URL in the browser again. This time the user is redirected to log in using Okta.
  5. If you have debug statements in the YAML, you can see the values by enabling the Trace view in the menu bar of the flow window. alt
  6. Generate the Trace URL and use it for testing.
    alt
  7. To check the traces, click Reporting & diagnostics > Trace viewer. alt

Summary

In this tutorial, you’ve learned how to build your user journey with IBM Security Verify SaaS Flow Designer, and you've used Okta and Microsoft Active Directory for authentication. The value of the flag "Migrated to Okta" is an indicator of the login page that the user will see. If the user hasn’t been migrated to Okta yet, they would get a Microsoft Active Directory login page rather than an Okta login page. Based on your client requirements, you can use any other SAML/OIDC-compliant identity provider.

You can design flows for employees and contractors (B2E), consumers (B2C), or business partners (B2B). You can invoke REST APIs from a third-party system or complete validation checks, both of which will be handled in the flows.

Next steps

Now that you understand how to orchestrate identity using IBM Security Verify, Okta, and Active Directory, keep going with your orchestration journey. Interested to know more about our offering?