Azure AD Authentication
This section provides instructions on how to configure WorkflowGen delegated authentication with Azure AD authentication via the Microsoft Identity Platform v2.0 or API endpoint v1 providers, 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
.- Make sure to have a licensed copy of WorkflowGen installed and running on an IIS web server in HTTPS secure connection mode.
- 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 WorkflowGen and that the user has WorkflowGen administrator permissions. This is important because once you've activated the delegated authentication with Azure AD, you'll still need to be able to manage the WorkflowGen web application.
- AES encryption mode and its key are required for the authentication to work.
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 in order to be able to register other custom applications to access it.
- 1.In the Azure portal, click App registrations in the Azure Active Directory section.
- 2.Click New registration, and fill in the properties form:
- Name:
WorkflowGen Web app
- Supported account type:
Account in this organizational directory only (Single tenant)
✏️ Note: Depending on the context, you should choose the right option for your use case for the Supported account type value. - Redirect URI:
- Type:
Web
- Value:
https://<workflowgen url>/auth/callback
📌 Example:https://mycompany.com/wfgen/auth/callback
- 3.Click Register at the bottom of the page.
You should now see the
WorkflowGen Web app
application registration's Overview page.Now, you have to generate a client secret to be used by the WorkflowGen OIDC authentication module.
- 1.Click Certificates & secrets.
- 2.In the Client secrets section, click New client secret.
- Description:
My secret
, or something to know that this is the client secret. - Expires: Choose 24 months or your desired expiration period.
- 3.Click Add.
- 4.The auto-generated client secret is now displayed under the Value column. Copy the client secret value and save it somewhere safe, since you won't be able to retrieve it afterwards.
Since the latest Azure portal update, it's no longer possible to set client secrets to never expire. You'll need to manually regenerate a new client secret every two years (if the 24 months option was selected) before it expires. Then, update the client secret used by WorkflowGen instance in its web configuration file (
ApplicationSecurityAuthClientSecret
key).In order for the communication between the WorkflowGen instance and Azure to work, you need to add one more authorized redirect URI to the
WorkflowGen Web app
application registration.- 1.Click Authentication.
- 2.In the Redirect URIs section, click Add URI.
- 3.Enter the following information:
- 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.
- 4.Click Save at the top of the section.
If you don't need WorkflowGen GraphQL API access, you can skip this application registration and configuration in Azure (steps 4 through 6). In this case, continue the configuration procedure from Review the registrations through WorkflowGen configuration completely. Finally, follow the configuration in the Configuring the authentication without the GraphQL API section.
In order to expose the WorkflowGen GraphQL API, you need to add a new application registration in Azure AD that will represent it. To do this:
- 1.In the Azure portal, click App registrations in the Azure Active Directory section.
- 2.Click New registration, and fill in the properties form:
- Name:
WorkflowGen GraphQL API
- Supported account type:
Account in this organizational directory only (Single tenant)
- Redirect URI: Leave this blank.
- 3.Click Register at the bottom of the page.
You've now successfully registered the
WorkflowGen GraphQL API
application in Azure AD.- 1.Click Expose an API.
- 2.To the right of Application ID URI, click Set and enter the URI
https://<workflowgen url>/graphql
📌 Example:https://mycompany.com/wfgen/graphql
- 3.Click Save.
- 4.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 WorkflowGen GraphQL API
- Admin consent description:
Allows the application to get access to WorkflowGen GraphQL API.
- User consent display name:
Default access to the WorkflowGen GraphQL API
- User consent description:
Allows the application to get access to WorkflowGen GraphQL API.
- 5.Click Add scope.
You should now have a new scope defined (e.g.
https://<workflowgen url>/graphql/default
).- 1.On the
WorkflowGen Web app
application registration page, click API permissions. - 2.Click Add a permission, then select the tab My APIs.
- 3.Click the
WorkflowGen GraphQL API
application in the list. - 4.Click Delegated permissions and check
default
under the Permission column. - 5.Click Add permissions.
- 6.On the API permissions page, click Grant admin consent for <your tenant name>, then click Yes.
You should now have all of the information you need to configure your WorkflowGen instance to delegate authentication to Azure AD. Here's a review:
- A client ID. This is the application (client) ID of the
WorkflowGen Web app
application registration in Azure AD. You can find it on its Overview page. - A client secret. This is the secret previously generated in step 2 for the
WorkflowGen Web app
. - An audience. This is the
Application ID URI
property (e.g.https://<workflowgen url>/graphql
) in the Expose an API section of theWorkflowGen GraphQL API
application registration. - The metadata endpoint URL. This URL is bound to your Azure directory. To find it:
- 1.Go to the Overview page of your Azure Active Directory section.
- 2.Copy the
Tenant ID
value. - 3.The metadata endpoint URL is built by replacing
<Tenant ID>
with your Tenant ID as follows: For Microsoft Identity Platform v2.0 (recommended):https://login.microsoftonline.com/<Tenant ID>/v2.0/.well-known/openid-configurationFor Azure v1:https://login.microsoftonline.com/<Tenant ID>/.well-known/openid-configuration
By now, you should have all the information needed to link your WorkflowGen instance to Azure AD.
Now, you have to configure WorkflowGen to delegate its authentication to Azure AD.
- 1.Open the WorkflowGen
web.config
file and add and/or update the following properties under<appSettings>
For Microsoft Identity Platform v2.0 (recommended):<!-- Microsoft Identity Platform v2 --><add key="ApplicationSecurityAuthProvider" value="ms-identity-v2"/><add key="ApplicationSecurityAuthClientId" value="<CLIENT ID>" /><add key="ApplicationSecurityAuthClientSecret" value="<CLIENT SECRET>" /><add key="ApplicationSecurityAuthMetadataUrl" value="<METADATA URL>" /><add key="ApplicationSecurityAuthAppIdClaim" value="appid" /><add key="ApplicationSecurityAuthUsernameClaim" value="preferred_username" /><add key="ApplicationSecurityAuthClockTolerance" value="60" /><add key="ApplicationSecurityAuthSessionRefreshEnableIFrame" value="Y"/><add key="ApplicationSecurityAuthAccessTokenUsernameClaim" value="upn" /><add key="ApplicationSecurityAuthAdditionalScopes" value="https://<workflowgen url>/graphql/default" />For Azure v1:<!-- Azure v1 auth --><add key="ApplicationSecurityAuthProvider" value="azure-v1"/><add key="ApplicationSecurityAuthClientId" value="<CLIENT ID>" /><add key="ApplicationSecurityAuthClientSecret" value="<CLIENT SECRET>" /><add key="ApplicationSecurityAuthMetadataUrl" value="<METADATA URL>" /><add key="ApplicationSecurityAuthAppIdClaim" value="appid" /><add key="ApplicationSecurityAuthUsernameClaim" value="upn" /><add key="ApplicationSecurityAuthClockTolerance" value="60" /><add key="ApplicationSecurityAuthSessionRefreshEnableIFrame" value="Y"/><add key="ApplicationSecurityAuthCheckSessionUrl" value="<CHECK SESSION URL>" />✏️ Note: Check session iFrame (e.g.ApplicationSecurityAuthCheckSessionUrl
) is not supported in Microsoft Identity Platform v2.0. - 2.Replace
<CLIENT ID>
with theWorkflowGen Web app
application (client) ID from Azure. - 3.Replace
<CLIENT SECRET>
with theWorkflowGen Web app
application registration's generated secret from Azure. - 4.Replace
<METADATA URL>
with the metadata endpoint URL that you built earlier from theTenant ID
value of your Azure Active Directory. - 5.For Microsoft Identity Platform v2.0, replace
<workflowgen url>
with your WorkflowGen URL in the value of theApplicationSecurityAuthAdditionalScopes
key (e.g.https://mycompany.com/wfgen/graphql/default
) if you have configured theWorkflowGen GraphQL API
application registration (steps 4 through 6). Otherwise, remove theApplicationSecurityAuthAdditionalScopes
key completely. - 6.For Azure v1, replace
<CHECK SESSION URL>
(which is usuallyhttps://login.microsoftonline.com/<Tenant ID>/oauth2/checksession
) with the value of the metadata endpoint'scheck_session_iframe
property. To do this, you'll have to make an HTTP GET request to your metadata endpoint URL (e.g.https://login.microsoftonline.com/<Tenant ID>/.well-known/openid-configuration
), then copy and paste the value. See the examples below on how to request the metadata endpoint.Linux/macOS request example:curl "<METADATA URL>" | python -m json.tool✏️ Note: Remove| python -m json.tool
if you don't have Python; this is for pretty printing.Windows PowerShell request example:Invoke-RestMethod -Uri "<METADATA URL>" -Method GET | ConvertTo-JSON
Table of
web.config
optionsOption | Description |
ApplicationSecurityAuthProvider | 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: azure-v1 , ms-identity-v2 ,auth0 , adfs , orokta |
ApplicationSecurityAuthClientId | Each identity provider generates a code that uniquely identifies your application. In this case, this is the code that uniquely identifies the WorkflowGen Web app application in Azure. |
ApplicationSecurityAuthClientSecret | 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. |
ApplicationSecurityAuthMetadataUrl | 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 web.config . Take note that the metadata endpoint URL is different for Microsoft Identity Platform v2.0 and Azure v1. |
ApplicationSecurityAuthAppIdClaim | 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. |
ApplicationSecurityAuthUsernameClaim | 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. |
ApplicationSecurityAuthAccessTokenUsernameClaim | This is used by the GraphQL API when receiving an access token. ✏️ Note: It's recommended to keep the default value. |
ApplicationSecurityAuthClockTolerance | 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. |
ApplicationSecurityAuthSessionRefreshEnableIFrame | When enabled ( Y ), this option activates the session auto-refresh feature using an invisible <iframe> . This allows users to enter their password less often by refreshing their session in the background while they're working. ✏️ Note: This option is only available when using WorkflowGen with OIDC authentication. |
WorkflowGen should now be linked to your Azure AD. The last thing left to do is to configure a few more options in order to finish the internal wiring of WorkflowGen so that it can delegate its authentication.
WorkflowGen uses an internal session token to manage the user session and identify the current user for all the HTTP requests made to the web application after the user has logged in to Azure AD. In order to generate a session token, you need to add a few more settings to the
web.config
.- 1.Open the WorkflowGen
web.config
file and add and/or update the following property under<appSettings>
:<add key="ApplicationSecurityAuthSessionTokenSigningSecret" value="<SECRET>" /> - 2.Replace
<SECRET>
with a custom value that can't be guessed, such as a UUID or a complex password.
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.
You now need to activate the delegation by replacing the authentication system in IIS and pointing WorkflowGen's modules to the correct authentication module.
- 1.In IIS Manager, click on the WorkflowGen website in the tree view.
- 2.Click the Authentication button.
- 3.Enable Anonymous Authentication, and disable all other authentications.
- 4.Perform these steps for all sub-applications as well.
Certain sub-applications need to have their authentication checked by the special
Advantys.Security.JWTAuthenticationModule
WorkflowGen authentication module, but certain other sub-applications (such as /wfgen/auth
, /wfgen/hooks
and /wfgen/scim
) should not because they are either public or aren't part of the global authentication system.- 1.Add the following property to the WorkflowGen
web.config
file:<configuration><system.webServer><modules><add name="ApplicationSecurityAuthenticationModule" type="Advantys.Security.Http.JWTAuthenticationModule" /></modules></system.webServer></configuration> - 2.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
If you skipped the WorkflowGen GraphQL API application registration steps earlier, it is required to apply the configuration in the Configuring the authentication without the GraphQL API section.
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.
- This method is only supported with the Microsoft Identity Platform v2.0 provider (e.g.
ms-identity-v2
). - Your third-party APIs must support an access token (JWT) for authentication and be able to validate the user by verifying the access token's content.
This configuration does have some drawbacks. For example, the WorkflowGen Plus v2 mobile application will not be compatible with this setup.
By default, the only recipient of the access token is the
WorkflowGen GraphQL API
application. This means that the access token can only be used to send queries to the GraphQL API only. In order to use the same access token to call your own APIs from WorkflowGen (e.g. web forms), you will need to perform the following steps in your Azure portal, and then modify the WorkflowGen web.config
file.- 1.In the Azure portal, click App registrations in the Azure Active Directory section.
- 2.Click New registration, and fill in the properties:
- Name:
My APIs
- Supported account types:
Account in this organizational directory only (Single tenant)
✏️ Note: Depending on the context, you should choose the right option for your use case for the Supported account type value. - Redirect URI: Leave this blank
- 3.Click Register at the bottom of the page.
- 1.Click Expose an API.
- 2.To the right of Application ID URI, click Set and enter the URI
api://my-apis
. - 3.Click Save.
- 4.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 WorkflowGen GraphQL API
- Admin consent description:
Allows the application to get access to WorkflowGen GraphQL API.
- User consent display name:
Full access to the WorkflowGen GraphQL API
- User consent description:
Allows the application to get access to WorkflowGen GraphQL API.
- 5.Click Add scope.
- 6.Add any other scopes that seem necessary for your other APIs.
- 1.Click Manifest.
- 2.Find the
appRoles
JSON property and add the following JSON object to the JSON array:{"allowedMemberTypes": ["Application"],"description": "Allows the application to get access to WorkflowGen GraphQL API.","displayName": "wfgen-graphql-full-access-role","id": "<NEW ID>","isEnabled": true,"lang": null,"origin": "Application","value": "wfgen-graphql-full-access-role"}✏️ Note: Replace<NEW ID>
with the value generated by the[guid]::NewGuid().ToString()
PowerShell command or use any GUID generators. - 3.Click Save.
- 1.On the
WorkflowGen Web app
application registration page, click API permissions. - 2.In the Configured permissions section, click Add a permission.
- 3.Click My APIs, then select the
My APIs
application in the list. - 4.Click Delegated permissions and check
wfgen-graphql-full-access
under the Permission column. - 5.Click Add permissions.
- 6.On the API permissions page, click Grant admin consent for <your tenant name>, then click Yes.
For each of your automated applications in Azure (e.g. server-side script, background service, or application) that requires access to the
My APIs
application, do the following:- 1.Go to the application's registration page, then click API permissions.
- 2.In the Configured permissions section, click Add a permission.
- 3.Click My APIs, then select the
My APIs
application in the list. - 4.Click Application permissions and check
wfgen-graphql-full-access-role
under the Permission column. - 5.Click Add permissions.
- 6.On the API permissions page, click Grant admin consent for <your tenant name>, then click Yes.
Open the WorkflowGen
web.config
file, add and/or update the following application settings, then save the file:<add key="ApplicationSecurityAuthAudience" value="api://my-apis"/>
<add key="ApplicationSecurityAuthAdditionalScopes" value="api://my-apis/wfgen-graphql-full-access" />
<add key="ApplicationSecurityAuthGraphQLScope" value="wfgen-graphql-full-access" />
<add key="ApplicationSecurityAuthGraphQLAppRole" value="wfgen-graphql-full-access-role" />
You also need to define any additional scopes in the
ApplicationSecurityAuthAdditionalScopes
key that refer to the other APIs you defined in step 2 of the Azure portal steps above. The scopes must be separated by a comma.The
WorkflowPage
class in the WorkflowGen.My
library provides a public CurrentUserAccessToken
method to easily retrieve the current user's shared access token that can be used to query the GraphQL API and your third-party APIs. See the snippet code below.protected void Page_Load(object sender, EventArgs e)
{
base.Page_Load(sender, e);
string accessToken = this.CurrentUserAccessToken();
// Use accessToken to query GraphQL API or your third-party APIs...
}
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:
- 1.Create a new separate WorkflowGen directory for the SOAP API users.
- 2.Provision it with users and groups as needed.
- 3.In the IIS Manager, enable the Basic authentication method for the
\ws\wfgen
application. - 4.In the
web.config
file (located in\Inetpub\wwwroot\wfgen
), add the following under<location path="ws" inheritInChildApplications="false">
:<system.webServer><modules><remove name="ApplicationSecurityAuthenticationModule" /></modules></system.webServer>
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.
For a complete list of configurable options, see the Web and Application Configuration Parameters appendix in the WorkflowGen Technical Guide.
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 |
ApplicationSecurityAuthSessionTokenCookie | The name of the session cookie that is generated by the authentication module.
Default: wfgen_token
✏️ Note: This is useful when you have multiple instances of WorkflowGen running and you want to have access to both and be authenticated on both instances at the same time. |
ApplicationSecurityAuthSessionTimeOut | The duration of the session in seconds. It defaults to the ID token expiration time received.
Default: The exp value of the ID token |
ApplicationSecurityAuthMobileSessionTimeOut | The duration of the session in seconds when requested from mobile devices on the token endpoint.
Default: 7200 seconds |
ApplicationSecurityAuthAudience | The intended recipient of the access token (e.g. the target API). Default: https://<workflowgen url>/graphql |
ApplicationSecurityAuthAdditionalScopes | Additional scopes to add to the authentication request. They will appear in the access token content. ✏️ Note: The openid , profile , and email scopes are always in the request. |
ApplicationSecurityAuthGraphQLScope | Custom GraphQL scope value that will be verified when validating the authorized scopes in the access token returned from the OIDC provider. |
ApplicationSecurityAuthGraphQLAppRole | 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 ms-identity-v2 provider. |
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.
If for some reason you can't register the
WorkflowGen GraphQL API
application and you don't need GraphQL API authentication configured with the provider, you can avoid creating the registration and configure WorkflowGen with the Microsoft Graph API instead, which is included by default in all application registrations. To configure it, you only have to change some configuration options in the web.config
file:<configuration>
<appSettings>
<add key="ApplicationSecurityAuthAudience" value="https://graph.microsoft.com"/>
<add key="ApplicationSecurityAuthDecodeAccessToken" value="N"/>
</appSettings>
</configuration>
- 1.Change the
ApplicationSecurityAuthAudience
key to the Microsoft Graph API URL, e.g.https://graph.microsoft.com
. - 2.Set the
ApplicationSecurityAuthDecodeAccessToken
option toN
.
- Keep in mind that by setting
ApplicationSecurityAuthDecodeAccessToken=N
, the expiration date of the session token generated by WorkflowGen will be based on that of the ID token. - You won't be able to use the access token received from Azure to query the GraphQL API. This access token will give you access to the Microsoft Graph API and nothing else. To query the GraphQL API, you'll need to configure its authentication with another method, like Basic authentication.
Last modified 2mo ago