Azure AD Authentication
Overview
This section provides instructions on how to configure WorkflowGen delegated authentication with Azure AD authentication API endpoint v1 or Microsoft Identity Platform v2.0, and will show you how to set up a working WorkflowGen instance that uses Azure to authenticate your users.
In the instructions, substitute <workflowgen url>
with the domain and path to your WorkflowGen instance; for example, localhost/wfgen
or www.mycompany.com/wfgen
.
Prerequisites
Make sure to have a licensed copy of WorkflowGen installed and running on a server. You must be a WorkflowGen administrator.
Make sure to have Azure AD administrator access to be able to configure Azure AD.
Make sure to have provisioned an existing Azure AD user that you can authenticate with to WorkflowGen and that the user has administrator privileges. This is important because once you've activated the delegation, you'll still need to be able to manage the application.
AES encryption mode and its key are required for the authentication to work.
Azure Active Directory configuration
The configuration of Azure AD is done in two parts. First, you have to register the WorkflowGen web application and link it to your instance of WorkflowGen; then, you have to register the WorkflowGen GraphQL API to be able to register custom applications to access it.
Step 1: Create a new application registration for WorkflowGen
In the Azure portal, click App registrations in the Azure Active Directory section.
Click New registration, and fill in the properties form:
Name:
WorkflowGen Web app
Supported account type:
Account in this organizational directory only
Redirect URI:
Type:
Web
Value:
https://<workflowgen url>/auth/callback
āļø Note: Depending on the context, you should choose the right option for your use case for the Supported account type value. š Example:
https://mycompany.com/wfgen/auth/callback
Click Register at the bottom of the page.
You should now see the WorkflowGen registered application's overview page.
Step 2: Create a client secret for the application
Now, you have to generate a client secret to use in the WorkflowGen Authentication Module.
Click Certificates & secrets.
In the Client secrets section, add a new client secret.
DESCRIPTION:
secret
, or something to know that this is the client secret.EXPIRES: Choose Never.
VALUE: Anything with sufficient entropy that it can't be guessed, such as a UUID.
Click Save. The value you entered will now be encrypted.
Save the generated value, since you won't be able to retrieve it afterwards.
Step 3: Add a redirect URI
In order for the communication between WorkflowGen and Azure to work, you need to add one more authorized redirect URI to the registered WorkflowGen Web app
web application.
Click Authentication.
In the Redirect URIs section, enter the following information:
Type:
Web
Redirect URI:
https://<workflowgen url>/auth/logout/return
š Example:https://mycompany.com/wfgen/auth/logout/return
āļø Note: You should also seehttps://<workflowgen url>/auth/callback
in this list.
Click Save at the top of the section.
Step 4: Create a new application registration for the WorkflowGen GraphQL API
In order to expose the GraphQL API, you need to add a new application that will represent it. To do this:
In the Azure portal, click App registrations in the Azure Active Directory section.
Click New registration, and fill in the properties form:
Name:
WorkflowGen GraphQL
Supported account type:
Account in this organizational directory only
Click Register at the bottom of the page.
You've now successfully registered the GraphQL API in Azure AD.
Step 5: Expose the API in the WorkflowGen GraphQL API application registration
Click Expose an API.
To the right of Application ID URI, click Set and enter the URI
https://<workflowgen url>/graphql
. š Example:https://mycompany.com/wfgen/graphql
Click Add a scope and enter the following information:
Scope name:
default
Who can consent?:
Admins and users
Admin consent display name:
Default access to the GraphQL API
Admin consent description:
Allows the application to get access to WorkflowGen's GraphQL API.
User consent display name: Use the admin consent display name
User consent description: Use the admin consent description
Click Add scope.
Click Save.
Step 6: Give access to WorkflowGen
On the WorkflowGen application registration page, click API permissions.
Click Add a permission, then My APIs.
Click
WorkflowGen GraphQL API
in the list.Click Delegated permissions and check
default
.Click Add permissions.
Review the registrations
You should now have all of the information you need to configure WorkflowGen to delegate authentication to Azure AD. Here's a review:
A client ID. This is the application ID of the registered WorkflowGen app on Azure. You can find it on its overview page.
A client secret. This is the secret previously generated.
An audience. This is the
Application ID URI
property in the Expose an API section.The metadata endpoint. This URL is bound to your Azure directory. To find it:
Go to your directory properties section.
Copy the
Tenant ID
value.The metadata endpoint is built like this: For Azure v1:
For Microsoft Identity Platform v2.0:
By now you should have all the information needed to link your WorkflowGen instance to Azure AD.
WorkflowGen configuration
Now, you have to configure WorkflowGen to delegate its authentication to Azure AD.
Step 1: Add Azure AD values to the WorkflowGen web.config
web.config
Open the WorkflowGen
web.config
file and add the following properties under<appSettings>
. For Azure v1:For Microsoft Identity Platform v2.0:
āļø Note: Check session iFrame is not supported in Microsoft Identity Platform v2.
Replace
<CLIENT ID>
with the application ID.Replace
<CLIENT SECRET>
with the the WorkflowGen registered application's generated secret on Azure.Replace
<METADATA URL>
with the URL that you built earlier from theTenant ID
value of your Azure AD directory.Replace
<CHECK SESSION URL>
with the value of the metadata endpoint'scheck_session_iframe
property. To do this, you'll have to make a request to the<METADATA URL>
, then copy and paste the value. (See the table below for more information about this property.)Linux/macOS request example:
āļø Note: Remove
| python -m json.tool
if you don't have Python; this is for pretty printing.Windows PowerShell request example:
Table of web.config
options
Option | Description |
| The name of the identity provider supported by WorkflowGen. At this time, there is support only for Azure Active Directory, Microsoft Identity Platform v2.0, Auth0, ADĀ FS, and Okta. Value: |
| Each identity provider generates a code that uniquely identifies your application. In this case, this is the code that uniquely identifies the WorkflowGen web application. |
| Like the client ID, this is also generated by the identity provider, but it is more like what a password is for a user. It's important to keep this secret because malicious software that has access to this can act on the behalf of the application. This value must be explicitly generated in Azure Active Directory. |
| The endpoint provided by the identity provider that supports the OpenID Connect Discovery standard. It enables WorkflowGen to get some public information about your Azure Active Directory domain. Without this, you'll have to manually enter much more configuration in the |
| The name of the claim contained in the access token obtained from the identity provider that uniquely identifies a non-interactive client. This is only used if you have a machine-to-machine application that needs to have access to the GraphQL API. To configure this, see the Azure Active Directory configuration for single-page applications section. āļø Note: It's recommended to keep the default value. |
| The name of the claim contained in the access token that identifies the user in WorkflowGen. This is used by WorkflowGen to generate a session token as well as by the GraphQL API when receiving an access token. āļø Note: It's recommended to keep the default value. |
| This is used by the GraphQL API when receiving an access token. āļø Note: It's recommended to keep the default value. |
| This value is used when verifying a token in WorkflowGen. It's essentially to deal with minor differences between servers' clocks. āļø Note: It's recommended to keep the default value. |
| When enabled ( āļø Note: This option is only available when using WorkflowGen with OIDC authentication. |
WorkflowGen is now linked to Azure AD and back. The last thing left to do is configure a few more options in order to finish the internal wiring of WorkflowGen so that it can delegate its authentication.
Step 2: Add security values for session generation
In order to generate a session token, you need to add a few more settings to the web.config
.
Open the WorkflowGen
web.config
file and add the following property under<appSettings>
:Replace
<SECRET>
with a value that can't be guessed, such as a UUID.
The secret will be only accessible inside your instance of WorkflowGen, so when generating a session token, WorkflowGen will sign it with this secret in order to check the validity of all session tokens passed to it.
Step 3: Activate the authentication delegation
You now need to activate the delegation by replacing the authentication system in IIS and pointing WorkflowGen's modules to the correct authentication module.
Configure IIS
In IIS Manager, click on the WorkflowGen application in the tree view.
Click the Authentication button.
Enable Anonymous Authentication, and disable all other authentications.
Perform these steps for all sub-applications as well.
Add properties to the web.config
files of certain modules
web.config
files of certain modulesCertain modules need to have their authentication checked by the special Advantys.Security.JWTAuthenticationModule
WorkflowGen authentication module, but certain other modules should not because they are either public or aren't part of the global authentication system.
Add the following property to the WorkflowGen
web.config
file:If you have developed custom web forms with their own
\bin
folders, you have to copy the following .NET assemblies and dependency libraries from\wfgen\bin
to each custom web form's\bin
folder (\wfgen\wfapps\webforms\<custom webform>\bin
):Advantys.My.dll
Advantys.Security.dll
Newtonsoft.Json.dll
jose-jwt.dll
You should now have a working WorkflowGen instance with the authentication delegated to Azure AD through the OpenID Connect protocol. Make sure to have provisioned your users to WorkflowGen in order for them to successfully access WorkflowGen.
Calling third-party APIs with the access token
This method is only supported with Microsoft Identity Platform (
ms-identity-v2
).If the WorkflowGen User Portal or Administration Module is displayed without the main header menu, this feature will not work. For example, this scenario could occur when the User Portal home page or a request follow-up form is displayed inside an iFrame in an external solution.
The GraphiQL module (
/wfgen/graphql
) doesn't support session management when displayed in a browser.
By default, the only recipient of the access token is the GraphQL API. This means that it can only be used to send queries to that API only. In order to call your own APIs, you will need to perform the following steps in your Azure portal, and then modify the WorkflowGen web.config
file.
In your Azure portal:
Step 1: Add a new application registration that represents your APIs
In the Azure portal, click App registrations in the Azure Active Directory section.
Click New registration, and fill in the properties form:
Name:
My APIs
Supported account types:
Account in this organizational directory only
Click Register at the bottom of the page.
Step 2: Expose your APIs in the registration
Click Expose an API.
To the right of Application ID URI, click Set and enter the URI
api://my-apis
.Click Add a scope and enter the following information:
Scope name:
wfgen-graphql-full-access
Who can consent?:
Admins and users
Admin consent display name:
Full access to the GraphQL API
Admin consent description:
Allows the application to get access to WorkflowGen's GraphQL API.
User consent display name: Use the Admin consent display name
User consent description: Use the Admin consent description
Click Add scope.
Add any other scope that seems necessary for your other APIs.
Click Save.
Step 3: Add an application role
Click Manifest.
Find the
appRoles
JSON property and add the following JSON object to the JSON array:āļø Note: Replace
<NEW ID>
with the value generated by the[guid]::NewGuid().ToString()
PowerShell command .Click Save.
Step 4: Give access to the WorkflowGen application registration
Go to your WorkflowGen app registration page.
Click API permissions, then click Add a permission.
Click My APIs, then choose
My APIs
in the list.Click Delegated permissions and check
wfgen-graphql-full-access
.Click Add permissions.
Step 5 (optional): Give access to your automated applications (client credentials flow)
For each of your applications:
Go to the application's registration page.
Click API permissions, then click Add a permission.
Click My APIs, then select
My APIs
in the list.Click Application permissions and check
wfgen-graphql-full-access-role
.Click Add permissions.
In the WorkflowGen web.config
file:
web.config
file:Open the WorkflowGen web.config
file, add the following application settings, then save the file:
You also need to define any additional scopes (ApplicationSecurityAuthAdditionalScopes
) that refer to other APIs that you defined in Step 3 of the Azure portal steps. The scopes must be separated by a comma.
Additional information
SOAP services support
WorkflowGen only supports requests to the SOAP API using classic authentication methods. If you still need to use this API, you have to perform some additional steps to configure it properly:
Create a new separate WorkflowGen directory (i.e. users and groups) for the SOAP API users.
Provision it with users and groups as needed.
In IIS Manager, enable the Basic authentication method for the
\wfgen\ws
application.In the
web.config
file (located in\Inetpub\wwwroot\wfgen
), add the following under<location path="ws" inheritInChildApplications="false">
:
About session management
Azure Active Directory supports OpenID Connect Session Management, an extension draft standard, in addition to the core OpenID Connect standard. This standard defines the rules to handle SSO session of the provider from the client. An example use is that if a user logs out of their Azure AD session from any device, a regular web client will receive a message that enables it to remove the same user's local session. WorkflowGen supports this feature when activating delegated authentication with Azure AD.
Configurable options
This table lists all configurable options in WorkflowGen that you can use to customize your authentication experience; these are located in the WorkflowGen web.config
file.
Option | Description |
| The name of the session cookie that is generated by the authentication module.
Default: |
| The duration of the session in seconds. It defaults to the ID token expiration time received. Default: The exp value of the ID token |
| The duration of the session in seconds when requested from mobile devices on the token endpoint. Default: 7200 seconds |
| The intended recipient of the access token (e.g. the target API). Default: |
| Additional scopes to add to the authentication request. They will appear in the access token content. āļø Note: The |
| Custom GraphQL scope value that will be verified when validating the authorized scopes in the access token returned from the OIDC provider. |
| Custom GraphQL application role value that will be verified when validating the roles in the access token returned from the OIDC provider in a client credentials flow. āļø Note: Only available for the |
Current limitations
If the WorkflowGen User Portal or Administration Module is displayed without the main header menu, this feature will not work. For example, this scenario could occur when the portal home page or a request follow-up form is displayed inside an iFrame in an external solution.
The GraphiQL module (
/wfgen/graphql
) doesn't support session management when displayed in a browser.
Last updated