Introduction

From BioStar 2 v2.9.10, BioStar 2 supports the integration of Microsoft Entra ID (Azure Active Directory), so users can log in to BioStar 2 by using the account registered in the Microsoft Entra ID server.

To use this new feature, refer to the instructions below.


Warning

To use this new feature, the BioStar 2 Advance license needs to be ativated.



How To Set Up

There are two big steps for setting up the Microsoft Entra ID and integrating with BioStar 2. And, you can refer to each step as follows.


Step 1. Microsoft Entra ID Configuration


1-1. Go the "Microsoft Entra ID Entra admin center" and log in with a "Global Admin" account.

Microsoft Entra - Microsoft Entra admin center


1-2. Create a new Tenant by referring to the following Microsoft documentation. 

Quickstart - Access and create new tenant - Microsoft Entra | Microsoft Learn


Example) A newly created Tenant


1-3. Register the Application in Microsoft Enrta ID by referring to the following Microsoft documentation. 

How to register an app in Microsoft Entra ID - Microsoft identity platform | Microsoft Learn


Example) A created application


1-4. Create the Certificate or Client secret for the created application by referring to the following Microsoft documentation. https://learn.microsoft.com/en-us/entra/identity-platform/how-to-add-credentials?tabs=client-secret

In this article, the case of using Client secret will be introduced.


Warning

When entering the "Client Secret" into BioStar 2, be sure to copy the Value, not the Secret ID. 


Example) A created Client secret


1-5. Add a redirect URI to your application by referring to the following Microsoft documentation. https://learn.microsoft.com/en-us/entra/identity-platform/how-to-add-redirect-uri


Warning

In this stage, you need to add the URL that can be copied in the "Directory Integration" of BioStar 2's Settings to the Redirect URIs for the created application. You can check how to know the needed URL in the #2-5 of Step 2.


Example) A added redirect URI



1-6. Add some needed API perrmission for the application by referring to the following Microsoft documentation. Web API app registration and API permissions - Microsoft identity platform | Microsoft Learn 


Example) Procedures to add the API permissions

1) Go to API Permissions

2) Click the Add a permission 

3) Select Microsoft Graph 

4) Select "Application permissions"

5)  Add the permissions for the following items:

  • Directory.AccessAsUser.All
  • Directory.ReadWrite.All
  • Group.ReadAll
  • Group.Member.Read.All
  • Member.Read.Hidden
  • User-LifeCycleInfo.ReadWrite
  • User.ReadWrite.All


6) In the Status section, select the above API that needs to grant the API permissions.

7) Click "Grant admin consent for xxxxx(Admin Account)"




1-7. Remember the following three information that should to be entered into the "Directory Integration" of the Settings in BioStar 2.


1) Client ID: You can find in the registered application.


2) Client Secret: You can find in the registered "Client secret" for the registered application. Note, as mentioned above, you should remember the Value of the created Client secret, NOT the Secret ID, in the following picture.3) Primary Domain: You can find it by clicking the Overview.


Step 2. BioStar 2 Configuration


2-1. Go to the "Directory Integration" In the Settings of BioStar 2.


2-2. Select "Microsoft Entra ID" in the Directory Service. And, enter the three information mentioned in #7 of Step 1 into the Directory Server. Then, click the Connect S


2-3. You can see the users registered in the Entra ID on the User Group Filter.


Warning

1) Update button: click to refresh the user group information.


2) Icon "Magnifier button: Use to search for the desired user group 


2-4. You can configure the Entra ID field to be mapped to the user field of BioStar 2. You need to select the field of Entra ID to use as the user field of BioStar 2 in User Field Configuration.


Warning

1) Each "BioStar 2 User Field" is basically set by default to map to the user information corresponding to the Entra ID.

2) However, if you want to change it to a field value other than the default, click the field in "Entra ID Field" and select the desired field value. However, the field value in the "Entra ID Field" corresponding to the User ID field in the "BioStar 2 User Field" CAN'T be changed because it is automatically generated and fixed by BioStar 2.



2-5. Enable the BioStar 2 Login with Entra ID function to enable login to BioStar 2 using Entra ID SSO. 

And, copy the URL by clicking the button marked in the picture below, and then, register it as an added redirect URI mentioned in #1-5 of Step 1.


2-6. By configuring the Synchronization, you can synchronize the user information changes in Entra ID to the BioStar 2.

There are two types of synchronization, either the Manual or the Automatic as the follows.

  1. Manual: Each time you click the Sync Now, user information is retrieved and synchronized from Entra ID.
  2. Automatic: User information is retrieved and synchronized from Entra ID at the interval set in the Auto Sync Interval item. The synchronization interval can be set in minutes. The minimum value is 30 minutes, and the maximum value is 10,080 minutes (7 days). Even in Automatic synchronization mode, you can still use the Sync Now button to trigger immediate synchronization.
    Warning

You can check the date and time of the most recent synchronization in the Last Sync.



2-7. Click Apply. Then, all steps will be completed.



How to log in to BioStar 2 using Entra ID 


Warning

You need to assign the operator level, except for "None", in advance to the account that will log in to BioStar 2 with Entra ID. 



1. Access to the BioStar 2 server and then, you will see the below login page. In this page, click "Login with Microsoft Entra ID"
2. Then, the login web page will be converted automatically to the Dashboard page.



Caution

When integrating with Entra ID through the Directory Integration feature, users who do not exist in the directory service may be deleted from BioStar 2. If there are users that you do not want to be deleted, you can exclude them from the integration using the following method.


1. Log in to BioStar 2 with an administrator account.

2. Go to the User menu.

3. Click on the user you want to exclude from the integration in the All Users list.

4. When the detail information screen of the selected user appears, click the checkbox of Exclude from Directory Integration in Advanced.

5. Click Apply.


Then, the selected user will be excluded from the integration when using the Directory Integration feature.