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 administrative app

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 administrative app

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

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

    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 application 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.

    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

  1. Go to the API Authorization tab and click on + Authorize an API Resource.
  2. From the API Resources drop-down select the following APIs listed under the Organization APIs category and add the corresponding Authorized Scopes provided below.

    API Resource Authorized Scopes
    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 and click + New Role.

    Create Application Roles - Initial view

  3. Enter the following details:

    Field Description Value
    Role Name Enter a unique name to identify the role. GuardioAdministrator
    Select API Resource All the API resources added in step 2 will be listed. Add each API resource and check the box to include all permissions (scopes).
    • SCIM2 Users API
    • SCIM2 Roles API
    • SCIM2 Groups API
    • Application Management API
    • Identity Provider Management API

    Create Application Roles

  4. Click Create.

Upon successful creation the new application role will displayed under Assigned Roles.

Created Application Role

Set up the business application

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 business app

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

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

    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

Step 2: Share the application with organizations

Share the Guardio-Business-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 application 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.

    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

    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.

Set up the client applications

Before you begin

Download the sample b2b applications.

To set up the client applications:

  1. Navigate to b2b-samples/config.json 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 sections explain how an organization user who has admin privileges of the Guardio Insurance Administrative App logs in and uses 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.