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

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:

3. 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 to upon authentication and where the user is redirected to upon logout. http://localhost:3000/api/auth/callback/wso2is http://localhost:3000

4. 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 to upon authentication and where the user is redirected to 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 to 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, configure the following values.

   Note

   If you have selected Traditional Web Application template for application creation, the following values should have already 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 to upon authentication and where the user is redirected to 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 to upon authentication and where the user is redirected to 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 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 tag line 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 tag line 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 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 explain 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/

   

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.

   

5. Enter the username and password of a user who 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.

   

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

   

   Note

   Make sure that the configured IdP will share 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/.

   

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