Skip to content

Try a B2B use case (with organization)

The following guide is a complete end-to-end use case on how to manage B2B (Business-to-Business) applications in WSO2 Identity Server.

Scenario

You are an administrator of Guardio Insurance, which is a company that provides its services to other business organizations.

Best Car Mart has a partnership with Guardio Insurance to provide life insurance policies to its employees. Guardio Insurance exposes its services to Best Car Mart's employees through its Guardio Insurance Business App and Guardio Insurance Administrative App.

- **Guardio Insurance Administrative App** - Application that provides administrative capabilities to administrators of **Guardio** customer/partner organizations. The provided administrative capabilities are managing users, assigning roles, configuring an identity provider for the organization, and customizing the login flow of **Guardio Insurance Business App** business application for their organizations.

- **Guardio Insurance Business App** -  Application that provides insurance and claims settlement capabilities for other
 businesses, so that those businesses can use the software for internal requirements.

The employees of Best Car Mart should be able to log in to the Guardio Insurance applications to consume its services. The administrators of Best Car Mart will manage the users of its organization and also determine the login experience that their users should have.

Organization login scenario

Set up the applications

The following guides explain how you can share an application with organizations and allow organization users to log in to it using SSO.

Let's use the sample applications, Guardio Insurance Business application and Guardio Insurance Administrative application, to explore this use case.

Step 1: Register the applications on WSO2 Identity Server

Follow the steps given below to register the Guardio Insurance applications with WSO2 Identity Server.

  1. Login into the organization(root).
  2. Register Traditional Web Applications in your organization (root) with the following settings:

    • Register Guardio Insurance Business App

      Application Name Add a name for the application.
      Guardio-Business-App
      Protocol The authentication protocol to use.
      OpenID Connect
      Authorized redirect URLs The URLs to which the authorization code is sent upon authentication and where the user is redirected upon logout.
      http://localhost:3000/api/auth/callback/wso2is http://localhost:3000

    • Register Guardio Insurance Administrative App

      Application Name Add a name for the application.
      Guardio-Admin-App
      Protocol The authentication protocol to use.
      OpenID Connect
      Authorized redirect URLs The URLs to which the authorization code is sent upon authentication and where the user is redirected upon logout.
      http://localhost:3001/api/auth/callback/wso2isAdmin http://localhost:3001

Step 2: Share the applications with organizations

Share the Guardio-Business-App and Guardio-Admin-App with your organizations. See instructions on how to share applications with organizations.

When the application is shared with at least one organization, Sign In with SSO will be added as a login option in the application login screen, which organization users can use to log in.

Step 3: Configure the applications on WSO2 Identity Server

To configure the registered application on WSO2 Identity Server:

On the WSO2 Identity Server Console, go to Applications and select the application you registered.

Protocol Configurations

  1. Go to the Protocol tab of the application, and configure the following values.

    Note

    If you have selected the Traditional Web Application template for application creation, the following values should have already been set properly. Otherwise, verify and update the values.

    • For Guardio Insurance Business App

      Allowed Grant Types Select the following grant type:
      • Code
      Authorization Redirect URLs The URLs to which the authorization code is sent upon authentication and where the user is redirected upon logout.
      • http://localhost:3000/api/auth/callback/wso2is
      • http://localhost:3000
      Allowed Origins Enter the allowed origins.
      http://localhost:3000

    • For Guardio Insurance Administrative App

      Allowed Grant Types Select the following grant type:
      • Code
      Authorization Redirect URLs The URLs to which the authorization code is sent upon authentication and where the user is redirected upon logout.
      • http://localhost:3001/api/auth/callback/wso2isAdmin
      • http://localhost:3001
      Allowed Origins Enter the allowed origins.
      http://localhost:3001

    Take note of the client_id and client_secret generated for your applications.

  2. Click Update to save your configurations.

User Attribute Configurations

  1. Go to the User Attributes tab of the Guardio Insurance Business App.

  2. Select Email, First Name, Last Name, and Username attributes.

  3. Click Update.

API Authorization

Go to the API Authorization tab and authorize the APIs as follows.

  • For Guardio Insurance Business App

    • No API authorization is required.
  • For Guardio Insurance Administrative App

    • Select the following APIs under SYSTEM_ORG category (organization level APIs).

      SCIM2 Users API Scopes:
      • View User
      • List User
      • Create User
      • Update User
      • Delete User
      SCIM2 Roles API Scopes:
      • View Role
      • Update Role
      SCIM2 Groups API Scopes:
      • View Group
      • Update Group
      Application Management API Scopes:
      • View Application
      • Update Application
      Identity Provider Management API Scopes:
      • View Identity Provider
      • Create Identity Provider
      • Update Identity Provider
      • Delete Identity Provider

Role Configurations

  1. Go to the Roles tab.
  2. Select Application as Role Audience.
  3. Click + Create Role and create roles with following values

    • For Guardio Insurance Business App

      • No roles required.
    • For Guardio Insurance Administrative App

      Role Name Guardio Administrator
      Select API Resource Listed all permissions of authorized APIs of the application:
      • SCIM2 Users API
      • SCIM2 Roles API
      • SCIM2 Groups API
      • Application Management API
      • Identity Provider Management API

  4. Click Create.

Step 4: Set up the client applications

To set up the client applications:

  1. Open the config.json file found in the b2b-sample folder and update the following parameters:

    Parameter Description Value
    CommonConfig.AuthorizationConfig.BaseOrganizationUrl The base URL of the organization (root). https://localhost:9443/t/carbon.super
    BusinessAppConfig.AuthorizationConfig.ClientId The client ID of the Guardio-Business-App created on WSO2 Identity Server. Client ID copied from Guardio-Business-App in step 3 above.
    BusinessAppConfig.AuthorizationConfig.ClientSecret The client secret of the Guardio-Business-App created on WSO2 Identity Server. Client secret copied from Guardio-Business-App in step 3 above.
    BusinessAppConfig.ApplicationConfig.HostedUrl The URL of the Guardio-Business-App client application. http://localhost:3000
    BusinessAppConfig.ApplicationConfig.APIScopes The scopes required by the Guardio-Business-App application to access user resources. openid, email, profile, internal_login, etc.
    BusinessAppConfig.ApplicationConfig.Branding.name The branding name of your application. Guardio Insurance
    BusinessAppConfig.ApplicationConfig.Branding.tag A branding tagline for your application. Anytime . Anywhere
    BusinessAppConfig.ManagementAPIConfig.SharedApplicationName The application name you used to register the Guardio Business application in WSO2 Identity Server. Guardio-Business-App
    BusinessAppConfig.ManagementAPIConfig.Userstore The userstore name where the organization users are managed. PRIMARY
    BusinessAdminAppConfig.AuthorizationConfig.ClientId The client ID of the Guardio-Admin-App created on WSO2 Identity Server. Client ID copied from Guardio-Admin-App in step 3 above.
    BusinessAdminAppConfig.AuthorizationConfig.ClientSecret The client secret of the Guardio-Admin-App created on WSO2 Identity Server. Client secret copied from Guardio-Admin-App in step 3 above.
    BusinessAdminAppConfig.ApplicationConfig.HostedUrl The URL of the Guardio-Admin-App client application. http://localhost:3001
    BusinessAdminAppConfig.ApplicationConfig.APIScopes The scopes required by the Guardio-Admin-App to do administrative tasks. openid, email, profile, internal_login, internal_org_user_mgt_view, internal_org_user_mgt_list, internal_org_user_mgt_create, internal_org_user_mgt_update, etc.
    BusinessAdminAppConfig.ApplicationConfig.Branding.name The branding name of your application. Guardio Insurance - Administrator Application
    BusinessAdminAppConfig.ApplicationConfig.Branding.tag A branding tagline for your application. Administrator Application

  2. To start the Guardio Insurance Business App, open a terminal, navigate to the b2b-sample folder, and execute the following commands:

    Note

    Ensure that your system meets the specified minimum requirements: - Node version >= v16.16.0 - NPM version >= 8.11.0

    npm install
    
    npx nx serve business-app
    
  3. To start the Guardio Insurance Administrative App, open a terminal, navigate to the b2b-sample folder, and execute the following commands:

    npm install
    
    npx nx serve business-admin-app
    

Set up the organization

As the administrator of Guardio Insurance, next you need to set up an organization.

Step 1: Onboard the organization

Create an organization on the WSO2 Identity Server Console with Best Car Mart as the Organization Name.

Step 2: Onboard an organization administrator

Onboard an administrator to the Best Car Mart organization using the values given below.

  1. Create the user with the following values.

    Username Enter an unique identifier as the username.
    alex
    First Name Enter the first name of the user.
    Alex
    Last Name Enter the last name of the user.
    Doe
    Email Enter the email of the user.
    [email protected]
    Password Set a temporary password for the user or invite user to set the password.

  2. Assign the created user to the Guardio Administrator role of the shared Guardio-Admin-App application.

Try it out

The following guides explain how an organization user who has admin privileges of Guardio Insurance Administrative App login and use the administration portal. Also, this guide explains how other organization users consume the Guardio Insurance Business App.

Try out Sign In with SSO

Follow the steps below to see how organization login works for a user in the Best Car Mart organization when logging into Guardio Insurance Business App.

  1. Open the application by copying the following URL to your browser: http://localhost:3001/

    Guardio Admin Application Login

  2. Click Sign In and see that you are diverted to the WSO2 Identity Server login screen.

  3. Click Sign In with SSO to specify the organization to which you are signing in.

  4. Enter Best Car Mart as the organization name and click Submit.

    Sign in with SSO

  5. Enter the username and password of a user whom you have onboarded to Best Car Mart.

  6. Click Sign in and grant permission for the application to use.

    You have successfully logged into the Guardio Insurance Administrative App as a user of the Best Car Mart organization.

Try out the administration portal

Note

Learn how to build an administration portal for your B2B application in the implement an administration portal section.

Best Car Mart needs to manage its employees through an external IdP. As the administrator of Best Car Mart, Alex is tasked with enabling login from the external IdP for Best Car Mart employees.

To configure an identity provider for Guardio Insurance Business App:

  1. Log in to the application with the credentials of Alex.

  2. On the application, go to Settings > Identity Providers and click Add Identity Provider.

    Best car mart IdP config

  3. Select Google if you are onboarding a Google IdP or Enterprise if you are onboarding an enterprise IdP.

    Select Identity Provider method

    Note

    Make sure that the configured IdP will share the Email, First Name, Last Name, and Username attributes of the authenticating user with WSO2 Identity Server.

  4. Provide the details specific to your IdP and click Create.

  5. Click Add to login flow to enable this IdP as the login option for Best Car Mart users in the application.

  6. Open the Guardio Insurance Business App by copying the following URL to your browser: http://localhost:3000/.

    Guardio Business Application Login

  7. Log in to the business application through the SSO option. Now, the users in the configured external IdP can be logged into the application.