Single Sign-On with Microsoft Entra ID (formerly Azure AD)

Prerequisites

To set up SSO with Microsoft Entra ID, formerly Azure Active Directory, you will need a Microsoft Azure Premium account. While Microsoft's cloud platform, Azure, remains unchanged, the identity and access management service previously known as Azure Active Directory is now called Microsoft Entra ID.

Step 1: Creating an Enterprise App for Beekeeper

1. Navigate to your Microsoft Azure Portal for Enterprise Applications.
   
   
2. Click on New application.
   
   
   
3. Select Create your own application.
   
   
   
   
4. Provide a name for the app, e.g. "Beekeeper SSO".
   Choose to Integrate any other application you don't find in the gallery (Non-gallery).
   Click Create.
   
   

Step 2: Managing User Assignments for the Application

You can assign specific users and groups to access the application or make user/group assignment optional. 

Option 1: Assign Users and Groups

1. In the created Application, click on Users and groups.
   
   
   
   
2. Select Add user/group.
   
   
   
   
3. Click on None Selected.
   
   
4. Choose the desired user or group and click Select.
   
   
   
   
5. Click Assign.
   
   

Option 2: Making User/Group Assignment Optional

1. Click on Properties.
   
   
   
   
2. Under User assignment required?, select No.
   
   
   
3. Click Save.
   
   

Step 3: Setting Up Single Sign-On

1. For SAML configuration, go to Single sign-on.

2. Click on SAML.

3. In the Basic SAML Configuration section, click Edit.

Enter the Identifier (Entity ID) and Reply URL (Assertion Consumer Service URL) in the following format:

• Your Identifier: https://yoursubdomain.us.beekeeper.io/saml/sso/metadata.xml
• Your Reply URL in this form: https://yoursubdomain.us.beekeeper.io/saml/sso/

4. Click Save.

Note: Ensure URLs include your Beekeeper subdomain and your datacenter reference (e.g., us, ch, or de, there is no reference for the European data center).

Step 4: Configuring User Attributes

You can populate a user’s Beekeeper profile fields during login by defining which information will be sent in the SAML token. You will need the Placeholder value for each Beekeeper profile field, which you can find in the Beekeeper Dashboard under Settings > Profile Fields.

1. In the Attributes & Claims section, click on Edit.

2. Select Unique User Identifier (Name ID) field

1. Click on the Name identifier format field and select Persistent.
   
   
   
   
2. In the Source attribute field, select the attribute you want to use as the Beekeeper User ID.
   
   
   
   
3. Click Save.

3. Optional: Edit the additional claims by clicking on them.

While you can add other claims listed below, please note that the only required claim for successful SSO setup is the Unique User Identifier (Name ID). It's important to note that modifying other profile fields in Beekeeper through SSO is not recommended, especially if you enable automated user sync (e.g.: from Azure).



Below, you can see an example set of token attributes:

* Ensure that each attribute corresponds to the placeholder value of the respective Profile Field in the Beekeeper Dashboard. Note that only the attributes listed above are supported when filling out the related Beekeeper profile fields.

** Please note: The Beekeeper username does not accept special characters except for "_". Therefore, when selecting an attribute, consider this restriction.

1. Enter the profile field placeholder value in the Name field.
   
   
2. Ensure that the Namespace field is cleared and left blank. This is essential because Azure adds a namespace to attribute names by default. If left unchanged, it will send an attribute named http://schemas.xmlsoap.org/ws/2005/05/identity/claims/email, which Beekeeper will not recognize, instead of simply "email" as expected by the server.

3. Click Save.

4. Optional: Create a claim for the attribute user.jobtitle.
   1. Click on Add new claim.
      
   2. Enter the profile field placeholder value in the Name field.
      
   3. In the field Source attribute, search for user.jobtitle and select it.
      
      
   4. Click Save.

After you have edited/added all necessary claims, your claim overview should look similar to the following:

Step 5: Copy SAML Signing Certificate

1. In the SAML Signing Certificate section, download the Federation Metadata XML file.

2. Open the file and copy the content.
   
   
3. Open the Beekeeper Dashboard and navigate to Settings > General > Single Sign-On.
   
   
4. Select which authentication option you want to be enabled for the platform (you can find more information on the differences here)
   
   
   
5. Paste the content from the downloaded file into the SAML Metadata box.
   
   
   
6. Specify your preference for automatic user account provisioning for new users.
   

Enabling auto-provisioning through SSO can help troubleshoot during setup, but it may not always be the best choice. Depending on your setup, it could create duplicate user accounts, causing data problems.

7. Click on Save settings.
   
   

Step 6: Test Configuration

Navigate back to the single sign-on configuration window of your SSO enterprise application. In the last box of the configuration overview, click Test to verify the successful configuration.

For any inquiries or assistance, please contact your CSM.