How Azure AD 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 Azure AD. 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.
|
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 Azure AD, please follow these steps:
1. Register your Bizagi Work portal as an authorized app in your Azure AD.
2. Configure the authentication type with the Management Console.
3. Synchronize the users into Bizagi.
|
The steps oriented toward configuring integration with Azure AD, 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 Azure AD
The first step is to set up the configuration needed to Register Bizagi Work portal (its URL) in Azure AD.
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 Azure AD 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 on Active Directory option at the left panel and click your on 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.
•For on-premises Bizagi projects, this URL is specified as:
https://[your_server]/[your_project]/oauth2/client/callback
While replacing [your_server] and [your_project] depending on how you set up your 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 who can consent Admins and users:
|
Adequate authorization settings are usually set OK by default, which means you should not need to configure this setting. 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 OK 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 on New client secret.
At the next screen, make sure you add a long descriptive number for your key. Input such number within Description. 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 Branding details 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 Azure AD
Open the Authentication module. In there, 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 Overview and look up the Endpoints to gather these URLs that you will need to configure later on in Bizagi.
Make sure you copy down the endpoints for the following:
•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 Azure AD 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 Azure AD is adequate, you will now need to input the Azure AD details into Bizagi.
Do this by using Bizagi Management Console targeting the environment you want this configuration to apply to (e.g, Development environment, Testing environment, Production environment).
2.1 Open your project with the Management Console.
Open the Bizagi Management Console and load your project.
2.2 Go to the security settings
Click on the Security module.
2.3 Select Azure authentication.
To do this, click on Authentication in the middle panel, and use the following settings for the parameters in the rightmost panel:
•Type: OAuth2.
•Client: Azure AD.
Click Update.
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 Azure AD. |
Client Secret's value |
Should match the VALUE of the generated Key for that App set in Azure AD. |
Redirect Uri |
Should match the Response URI as registered in Azure AD, 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 Azure AD. Use the following URL: https://login.microsoftonline.com/[tenant]/oauth2/authorize
Consider: •[tenant]: Should specify your Tenant id (based on your Azure's subscription). |
Token Endpoint |
Should match the OAuth 2.0 Token endpoint as per your Azure AD. 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 Azure AD, 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. |
|
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 Azure AD 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.
|
If you will not synchronize users about yet, then you may test that the authentication works as expected by simply creating one user manually in Bizagi Work portal for validation purposes. To create such 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 Azure AD. |
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 Bizagi Work portal loads, it redirects you to your Azure AD login page:
After you sign in successfully to Azure AD, you are redirected back to Bizagi 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 |