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.
- Login into the organization(root).
-
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 to upon authentication and where the user is redirected to 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 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
-
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
andclient_secret
generated for your applications. -
-
Click Update to save your configurations.
User Attribute Configurations
-
Go to the User Attributes tab of the Guardio Insurance Business App.
-
Select
Email
,First Name
,Last Name
, andUsername
attributes. -
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
- Go to the Roles tab.
- Select Application as Role Audience.
-
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
-
-
Click Create.
Step 4: Set up the client applications¶
To set up the client applications:
-
Open the
config.json
file found in theb2b-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
-
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
-
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.
-
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. -
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.
-
Open the application by copying the following URL to your browser:
http://localhost:3001/
-
Click Sign In and see that you are diverted to the WSO2 Identity Server login screen.
-
Click Sign In with SSO to specify the organization to which you are signing in.
-
Enter Best Car Mart as the organization name and click Submit.
-
Enter the username and password of a user who you have onboarded to Best Car Mart.
-
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:
-
Log in to the application with the credentials of Alex.
-
On the application, go to Settings > Identity Providers and click Add Identity Provider.
-
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
, andUsername
attributes of the authenticating user with WSO2 Identity Server. -
Provide the details specific to your IdP and click Create.
-
Click Add to login flow to enable this IdP as the login option for Best Car Mart users in the application.
-
Open the Guardio Insurance Business App by copying the following URL to your browser:
http://localhost:3000/
. -
Log in to the business application through SSO option. Now, the users in the configured external IdP can be logged into the application.