How Entra ID integration works
OpenId is an authentication protocol, built on top of OAuth2.0 to extend the authorization specification. It can be used to securely sign users into web applications (in this case, the Work portal). By using this feature, you can outsource sign-up, sign-in, and other identity management experiences in your web applications to Entra ID. This allows you to provide Single Sign-On capabilities at the browser level.
This authentication mechanism introduces the concept of an id_token, which is a security token that allows for due verification of the identity of the user while obtaining some of his/her basic profile information.
Because OpenId extends OAuth 2.0 it also enables applications to securely acquire access_tokens. Access_tokens allows you to access resources that are secured by an authorization server.
|
An enterprise and on-premise environment must be used.
Currently supported standards in this mechanism are: OpenId v1.0, relying on the OAuth 2.0 authorization flow.
Though OAuth2.0 considers authorization aspects, these definitions apply to resources. This means, that for access rights definitions in the Bizagi Work portal (i.e. which profiles can see, work or use certain Bizagi options), you will still need to input authorization definitions in Bizagi. |
What you need to do
To configure Bizagi to sign in with Entra ID, please follow these steps:
1. Register your Bizagi Work portal as an authorized app in your Entra ID.
2. Configure the authentication type with the Management Console.
3. Synchronize the users into Bizagi.
|
The steps oriented toward configuring integration with Entra ID, will require specific technical details (e.g, endpoints, authorized credentials) which are usually managed by an IT admin. Therefore, these steps will require a profile having expertise on this matter, and having access to the information mentioned above. |
1. Register your Bizagi Work portal as an authorized app in your Entra ID
The first step is to set up the configuration needed to Register Bizagi Work portal (its URL) in Entra ID.
This includes inputting Bizagi endpoints to get access keys for an entitled connection.
1.1 Log in to your Azure services
Access your Azure subscription with the Entra ID service.
To do so, you will need to sign in to Azure's portal at https://portal.azure.com.
1.2. Go into your Active Directory
Click the Active Directory option at the left panel and click App registrations to then add a new application to it (by clicking New application registration).
1.3. Input the app's basic details
Give this app a name, and select Web App / API for its type.
For its Sign-on URL note that you need to input the base URL where your end-users access Bizagi Work portal.
Consider:
•For Automation Service (cloud projects), this URL is specified as:
https://[project_environment]-[your_project]-[your_company].bizagi.com/oauth2/client/callback
While replacing [your_company] and [your_project] for your subscription's values accordingly.
Similarly, replace [project_environment] with test for a Testing environment, or with nothing at all for a Production environment.
Click Create when done.
1.4 Create a new Application ID
Once the app is created, you need to create an application ID and the Scope related to it.
Edit the Scope, select the Admins and users option in the Who can consent? field:
|
Generally, the appropriate authorization settings are configured correctly by default, which means you should not need to configure them.. By default the new applications and their keys are granted with Sign in and read user profile, which is what Bizagi requires. Notice it is expected that this setting does NOT require Admin:
|
1.5 Create a valid access key for the app
Go to the Certificates & Secrets and then click New client secret.
At the next screen, make sure you add a long and descriptive secret for your access key. Input such secret in the Description field. Make sure you set the expiration for such key, and then click Add so that the key is generated and shown to you.
|
Note that the above access keys must have an expiration date, and you are therefore, in charge of managing and looking after its validity. |
At this point, you should copy the key's value.
Make sure you paste it into someplace you control having adequate measures for safekeeping and acknowledge that this value will be your Key.
1.6 Fill out additional URL details
You can register additional details in the Branding module like the name or the Home page URL. In the Home page URL you can set the Bizagi Work Portals URL.
1.7 Configure Bizagi endpoints in Entra ID
Open the Authentication module and make sure that the redirect URI (also referred as reply URL) Sign-on URL, has in its end the following suffix:
/oauth2/client/callback
Click Save when done.
1.8 Look up your AD endpoints
Go back to the Overview module and look up the Endpoints to obtain the URLs that you will need to configure later on in Bizagi.
Make sure you copy down the following endpoints:
•OAuth 2.0 Token Endpoint V1
•OAuth 2.0 Authorization Endpoint V1
|
OAuth 2.0 V2 enpoints are not supported. |
At this point, configuration directly in Entra ID is set and you may now go to Bizagi to complete the procedure.
2. Configure the authentication type in Bizagi with the Management Console
At this point, after having verified access in Entra ID is adequate, you will now need to input the Entra ID details into Bizagi.
Do this by using Bizagi's Management Console targeting the environment you want to apply this configuration (e.g, Development environment, Testing environment, Production environment).
2.1 Open your project with the Management Console.
Access Bizagi's Management Console by entering the following URL: https://manage-[CompanyName]-[EnvironmentName].bizagi.com
For more information, access the documentation on How to manage your environment with the Management Console.
2.2 Go to the security settings
Open the Security module.
2.3 Select Azure authentication.
To do this, click Authentication in the middle panel, and then start the environment maintenance. Use the following settings for the authentication parameters:
•Authentication Type: OAuth2.
•Sub Type: Entra ID.
•Active Flow: Authorization Code.
Click Save.
Once OAuth2 and AzureAD are chosen, you will notice that new parameters for such Authentication are displayed.
2.4. Configure the authentication parameters and endpoints
To do so, consider the detail as described below:
PROPERTY |
VALUE |
|---|---|
Client ID |
Should match the Application Id as registered in Entra ID. |
Client Secret's value |
Should match the VALUE of the generated Key for that App set in Entra ID. |
Redirect Uri |
Should match the Response URI as registered in Entra ID, which should correspond to the Reply URL (that one ending in /oauth2/client/callback). |
OAuth2 Authorization Endpoint |
Should match the OAuth 2.0 Authorization endpoint as per your Entra ID. Use the following URL: https://login.microsoftonline.com/[tenant]/oauth2/authorize
Consider: •[tenant]: Should specify your Tenant id (based on your Azure's subscription). |
OAuth2 Token Endpoint |
Should match the OAuth 2.0 Token endpoint as per your Entra ID. Use the following URL: https://login.microsoftonline.com/[tenant]/oauth2/token
Consider: •[tenant]: Should specify your Tenant id (based on your Azure's subscription). |
Logout Endpoint |
Should refer to a Logout endpoint as handled by Entra ID, usually having the following URL: https://login.microsoftonline.com/[tenant]/oauth2/logout?post_logout_redirect_uri=[homeRedirect]
Consider: •[tenant]: Should specify your Tenant id (based on your Azure's subscription). •[homeRedirect]: Should specify the URL used to direct after a log-out. Usually, you use the same login URL, which is the one directing to Bizagi Work portal. |
Bizagi Server URL |
Enter the complete URL which it was published and is accessed the Bizagi server. |
Cookie type |
•Persistent cookies: These remain on your hard drive until you erase them (log off) or they expire. How long a cookie remains on your browser depends on how long the Idle session time has been programmed. •Session cookies: These are temporary and are erased when you close your browser at the end of your session. The next time you visit the Bizagi Work Portal it will not save your previous session as if you were accessing the first time. |
Enable authentication logging in database |
Defines if the web application must log every authentication event to the database. |
Idle sessions time-out |
Determines the amount of minutes for a session before it expires. Default Value: 20 |
Redirect to a logoff page after logoff process |
By default, when you log off, Bizagi automatically redirects you to the login page. If you want to change this behavior and redirect to a static logout page, enable this option. |
Show detailed authentication error messages |
For security reasons, the causes of authentication error are not shown in the Bizagi Work Portal, instead, a generic message is shown without details of the cause of the error. If you want to show the causes of the authentication errors, enable this option. |
|
If you applied this change into an environment other than development, make sure such same changes are applied in your Development environment. To do this, follow the same procedure mentioned above while using Bizagi Studio. |
3. Synchronize the users from your Entra ID into Bizagi
At this point, the configuration is complete.
However, before using or testing the integrated authentication in runtime, you will need to explicitly import users from in Bizagi (as you are in charge of managing users). See how to Synchronize users documentation.
|
If you will not synchronize users yet, then you may test that the authentication works as expected by simply creating one user manually in the Bizagi's Work portal for validation purposes. To create such a user, consider: 1. You may need to temporarily switch back to using Bizagi authentication so that you can log in. 2. Make sure your created user is set with the exact domain\username combination matching your users in Entra ID. |
Authentication in runtime
Once these steps are carried out, authentication will be set for your end users in runtime.
End users will be able to sign-in, and you can verify them by using a browser to access Bizagi Work Portal.
The following image exemplifies access to the Testing environment's Work portal for Automation Service (using https://[project_environment]-[your_project]-[your_company].bizagi.com):
When the Work Portal loads, it redirects you to your Entra ID login page:
After you sign in successfully to Entra ID, you are redirected back to the Bizagi's Work Portal with a valid session:
|
If you are already logged in with a valid session, you will not need to input credentials. SSO capabilities are kept at the browser's level while having an authenticated valid session. Other properties like the idle session, depend on the configuration in Bizagi, and are not inherited from the IdP |
Last Updated 12/10/2024 12:28:50 PM