Okta Integration
This section provides instructions on:
- Okta configuration for WorkflowGen Plus v2: How to authorize WorkflowGen access to mobile applications using Okta.
- Okta configuration for server-side scripts: How to authorize WorkflowGen access to server-side scripts using OpenID Connect and Okta.
- Okta configuration for single-page applications: How to authorize WorkflowGen access to single-page applications using Okta.
- Okta configuration for the WorkflowGen CLI: How to authorize Okta access to the WorkflowGen command line interface.
- Generating a universal link for WorkflowGen Plus v2: How to generate a universal link to simplify the WorkflowGen Plus mobile app user login.
In the instructions, substitute
<workflowgen url>
with the domain and path to your WorkflowGen instance; for example, localhost/wfgen
or mycompany.com/wfgen
.This section provides instructions on how to configure WorkflowGen delegated authentication with Okta. At the end of this section, you'll have a working WorkflowGen instance using Okta to authenticate your users.
If you don't need the GraphQL API, you won't need to create an authorization server. See the Configuring the authentication without the GraphQL API for instructions.
- 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 an Okta administrator access to be able to configure it properly.
- Make sure to have provisioned an existing Okta 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. (The Okta user is in fact a user of an identity provider that's linked to Okta, such GitHub or Google. You have to provision at least one of the users.)
- AES encryption mode and its key are required for the authentication to work.
- The WorkflowGen user's username must match their Okta user's username in order to identify and authenticate the correct user from Okta.
- To test your configuration after the steps below, you can add an Okta user in the Okta portal's Users section.
- When importing users into WorkflowGen from the Okta database, make sure to set the username as the email (e.g.
[email protected]
).
The configuration of Okta will be done in several steps. First, you have to configure an authorization server in the web interface; then, you have to add a regular web application.
The WorkflowGen GraphQL API (authorization server) configuration is required if you want to use the WorkflowGen Plus v2 mobile app.
An Okta authorization server is a logic element that defines the security boundaries of your system when an application wants to access your resources via an API.
An authorization server defines your security boundary, and is used to mint access and identity tokens for use with OIDC clients and OAuth 2.0 service accounts when accessing your resources via API. Within each authorization server you can define your own OAuth scopes, claims, and access policies. Source: Information sidebar in Okta's administrative panel
To create an authorization server with a classic usage:
- 1.Go to the Okta Developer portal and log in to your account.
- 2.In the left panel, choose API under the Security menu.
- 3.Click the Add Authorization Server button on the Authorization Servers tab.
- 4.Enter the following information:
- Name:
WorkflowGen GraphQL API
- Audience:
<workflowgen url>/graphql
- Description:
WorkflowGen GraphQL API
(or whatever description you want)
- 5.Click the Save button.
To create an authorization server with multi-audience support:
- 1.Go to the Okta Developer portal and log in to your account.
- 2.In the left panel, choose API under the Security menu.
- 3.Click the Add Authorization Server button on the Authorization Servers tab.
- 4.Enter the following information:
- Name:
My APIs
- Audience:
my-apis
- Description:
Authorization server for all my APIs
(or whatever description you want)
- 5.Click the Save button.
For classic usage:
- 1.Go to the WorkflowGen GraphQL API authorization server's Scopes tab.
- 2.Click the Add Scope button.
- 3.Enter the following information:
- Name:
default
- Display phrase:
default
- Description:
Use the default scope if no other scope is specified
- Default scope: Check
Set as a default scope
- 4.Click the Create button.
For multi-audience support:
- 1.Go to the WorkflowGen GraphQL API authorization server's Scopes tab.
- 2.Click the Add Scope button.
- 3.Enter the following information:
- Name:
wfgen-graphql-full-access
- Display phrase:
wfgen-graphql-full-access
- Description:
Full access to the WorkflowGen GraphQL API
- 4.Click the Create button.
You've now properly configured your Okta authorization server for the WorkflowGen GraphQL API.
- 1.Go to the Claims section, then click the Add Claim button.
- 2.Enter the following information:
- Name:
com.workflowgen.api.username
- Include in token type: Select
Access Token
- Value Type: Select
Expression
- Value: Enter the following Okta code:appuser.username != null ? appuser.username : appuser.email != null ? appuser.email : appuser.nickname != null ? appuser.nickname : null
- Include in: Select
Any scope
✏️ Note: This step will ensure that WorkflowGen and the GraphQL API will always get a username through the same claim instead of having to make a lot of conditional statements. - 3.Click the Create button.
- 4.Add a second claim with the same information, but this time, set the Include in token type property to
ID Token
. - 5.Click the Create button.
You now need to configure the authorization server access policy.
- 1.Go to the WorkflowGen GraphQL API authorization server's Access Policies tab.
- 2.Click the Add Policy button.
- 3.Enter the following information:
- Name:
All Clients Policy
- Description:
Enables all clients to have access to this application server›.
- Assign to:
All clients
- 4.Click the Create Policy button.
- 5.Click the Add Rule button.
- 6.Enter the following information:
- Rule Name:
All Grant Types; Any Scopes; Any User assigned
- Leave the other settings set to their defaults.
- 7.Click the Create Rule button.
You've now successfully configured the authorization server access policy. There's just one more step needed in order for the client credentials flow to work, which will enable you to use machine-to-machine authentication with Okta and the WorkflowGen GraphQL API.
- 1.Go to the Okta Developer portal.
- 2.In the Applications item under the Applications menu, click the Create App Integration button.
- 3.Select the following options in Create a new app integration, then click Next:
- Sign-in method:
OIDC - OpenID Connect
- Application type:
Web Application
- 4.Enter the following information:
- App integration name:
WorkflowGen
- Grant type: Check
Authorization Code
- Sign-in redirect URIs:
<workflowgen url>/auth/callback
- Sign-out redirect URIs:
<workflowgen url>/auth/logout/return
- Base URIs:
<workflowgen url>
without any path (just the base URL); for example,https://localhost
, if<workflowgen url>
ishttps://localhost/wfgen
- Controlled access: Check
Allow everyone in your organization to access
- Leave the remaining properties set to their defaults.
- 5.Click the Save button.
- 6.On the General tab of your WorkflowGen web application page, click the Edit button in the General Settings section.
- 7.Enter the following information:
- Initiate login URI:
<workflowgen url>/auth/callback
- 8.Click Save.
You've now successfully configured Okta for your WorkflowGen instance.
You should now have all the information you need to configure WorkflowGen to delegate the authentication to Okta. Here's a review:
- A
client ID
and aclient secret
which can be found on the Okta WorkflowGen web application's General tab. - An
audience
and ametadata endpoint (Metadata URI)
which can be found on the Okta WorkflowGen GraphQL API authorization server page.
Now, you need to configure WorkflowGen to delegate its authentication to Okta.
Open the WorkflowGen
web.config
file and add/update the following properties:Classic usage:
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
<appSettings>
<!-- Okta auth -->
<add key="ApplicationSecurityAuthProvider" value="okta"/>
<add key="ApplicationSecurityAuthClientId" value="<CLIENT ID>" />
<add key="ApplicationSecurityAuthClientSecret" value="<CLIENT SECRET>" />
<add key="ApplicationSecurityAuthMetadataUrl" value="<METADATA URL>" />
<add key="ApplicationSecurityAuthUsernameClaim" value="com.workflowgen.api.username" />
<add key="ApplicationSecurityAuthAppIdClaim" value="sub" />
<add key="ApplicationSecurityAuthClockTolerance" value="60" />
<add key="ApplicationSecurityAuthSessionRefreshEnableIFrame" value="Y"/>
</appSettings>
</configuration>
With multi-audience support:
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
<appSettings>
<!-- Okta auth -->
<add key="ApplicationSecurityAuthProvider" value="okta"/>
<add key="ApplicationSecurityAuthClientId" value="<CLIENT ID>" />
<add key="ApplicationSecurityAuthClientSecret" value="<CLIENT SECRET>" />
<add key="ApplicationSecurityAuthMetadataUrl" value="<METADATA URL>" />
<add key="ApplicationSecurityAuthUsernameClaim" value="com.workflowgen.api.username" />
<add key="ApplicationSecurityAuthAppIdClaim" value="sub" />
<add key="ApplicationSecurityAuthClockTolerance" value="60" />
<add key="ApplicationSecurityAuthSessionRefreshEnableIFrame" value="Y"/>
<add key="ApplicationSecurityAuthAudience" value="my-apis"/>
<add key="ApplicationSecurityAuthAdditionalScopes" value="wfgen-graphql-full-access"/>
<add key="ApplicationSecurityAuthGraphQLScope" value="wfgen-graphql-full-access"/>
</appSettings>
</configuration>
- Replace
<CLIENT ID>
with the client ID of the WorkflowGen web application from Okta. - Replace
<CLIENT_SECRET>
with the client secret of the WorkflowGen web application from Okta. - Replace
<METADATA_URL>
with the Metadata URI property found in the WorkflowGen GraphQL API's settings page. Then, replace the last part,/.well-known/oauth-authorization-server
, with/.well-known/openid-configuration
(e.g.https://{YOUR_OKTA_DOMAIN}/oauth2/{AUTH_SERVER_ID}/.well-known/openid-configuration
).
You have probably noticed that the setting with the
ApplicationSecurityAuthUsernameClaim
key is set to the value entered in a rule earlier. Therefore, you could use any value here provided that you also modify the rule.For information about available configuration options to use with your instance, see the Web and Application Configuration Parameters appendix.
WorkflowGen is now linked to Okta 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.
In order to generate a session token, you need to add a few more settings to the
web.config
file.- 1.Open the WorkflowGen
web.config
file and add/update the following property:<?xml version="1.0" encoding="UTF-8"?><configuration><appSettings><!-- Auth --><add key="ApplicationSecurityAuthSessionTokenSigningSecret" value="<SECRET>" /></appSettings></configuration> - 2.Replace
<SECRET>
with a value that can't be easily 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.
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
- 1.In IIS Manager, click on the WorkflowGen application in the tree view.
- 2.Click the Authentication button.
- 3.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 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.- 1.Open the WorkflowGen
web.config
file and add/update the following property:<?xml version="1.0" encoding="UTF-8"?><configuration><system.webServer><modules><add name="ApplicationSecurityAuthenticationModule" type="Advantys.Security.Http.JWTAuthenticationModule" /></modules></system.webServer></configuration> - 2.In the
auth
module'sweb.config
, add/update the following property:<?xml version="1.0" encoding="UTF-8"?><configuration><system.webServer><modules><remove name="ApplicationSecurityAuthenticationModule"/></modules></system.webServer></configuration>This line removes the authentication Node.js module from the global authentication system, because this Node.js application encapsulates the OpenID Connect authentication mechanisms. - 3.Repeat the above two steps for the
hooks
andscim
modules as well. - 4.Copy the following .NET assemblies and dependency libraries from
\wfgen\bin
to each custom webform'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 Okta through the OpenID Connect protocol. Make sure to have provisioned your users to WorkflowGen in order for them to successfully access WorkflowGen.
If for some reason you can't add an authorization server in your Okta account and you don't need GraphQL API authentication configured with the provider, you can avoid creating the server and configure WorkflowGen with the default Okta authorization server.
- 1.Go to the Okta Developer portal.
- 2.In the Applications item under the Applications menu, click the Create App Integration button.
- 3.Select the following options in Create a new app integration, then click Next:
- Sign-in method:
OIDC - OpenID Connect
- Application type:
Web Application
- 4.Enter the following information:
- App integration name:
WorkflowGen
- Grant type: Check
Authorization Code
- Sign-in redirect URIs:
<workflowgen url>/auth/callback
- Sign-out redirect URIs:
<workflowgen url>/auth/logout/return
- Base URIs:
<workflowgen url>
without any path (just the base URL); for example,https://localhost
, if<workflowgen url>
ishttps://localhost/wfgen
- Controlled access: Check
Allow everyone in your organization to access
- Leave the remaining properties set to their defaults.
- 5.Click the Save button.
- 6.On the General tab of your WorkflowGen web application page, click the Edit button in the General Settings section.
- 7.Enter the following information:
- Initiate login URI:
<workflowgen url>/auth/callback
- 8.Click Save.
You've now successfully configured Okta for your WorkflowGen instance.
Add or update the following configuration options in the WorkflowGen
web.config
file.- Change
MetadataUrl
tohttps://<YOUR OKTA DOMAIN>/.well-known/openid-configuration
. - Change
UsernameClaim
topreferred_username
. - Change
AuthAudience
to the client ID of the configured WorkflowGen web application from Okta. - 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 Okta to query the GraphQL API. This access token will give you access to the Okta API and nothing else. To query the GraphQL API, you'll need to configure its authentication with another method, like Basic authentication.
Classic usage:
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
<appSettings>
<!-- Okta auth -->
<add key="ApplicationSecurityAuthProvider" value="okta"/>
<add key="ApplicationSecurityAuthClientId" value="<CLIENT ID>" />
<add key="ApplicationSecurityAuthClientSecret" value="<CLIENT SECRET>" />
<add key="ApplicationSecurityAuthMetadataUrl" value="https://<YOUR OKTA DOMAIN>/.well-known/openid-configuration" />
<add key="ApplicationSecurityAuthUsernameClaim" value="preferred_username" />
<add key="ApplicationSecurityAuthAppIdClaim" value="sub" />
<add key="ApplicationSecurityAuthClockTolerance" value="60" />
<add key="ApplicationSecurityAuthSessionRefreshEnableIFrame" value="Y"/>
<add key="ApplicationSecurityAuthAudience" value="<CLIENT ID>"/>
<add key="ApplicationSecurityAuthDecodeAccessToken" value="N"/>
</appSettings>
</configuration>
In order to generate a session token, you need to add a few more settings to the
web.config
file.- 1.Open the WorkflowGen
web.config
file and add/update the following property:<?xml version="1.0" encoding="UTF-8"?><configuration><appSettings><!-- Auth --><add key="ApplicationSecurityAuthSessionTokenSigningSecret" value="<SECRET>" /></appSettings></configuration> - 2.Replace
<SECRET>
with a value that can't be easily 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.
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
- 1.In IIS Manager, click on the WorkflowGen application in the tree view.
- 2.Click the Authentication button.
- 3.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 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.- 1.Open the WorkflowGen
web.config
file and add/update the following property:<?xml version="1.0" encoding="UTF-8"?><configuration><system.webServer><modules><add name="ApplicationSecurityAuthenticationModule" type="Advantys.Security.Http.JWTAuthenticationModule" /></modules></system.webServer></configuration> - 2.In the
auth
module'sweb.config
, add/update the following property:<?xml version="1.0" encoding="UTF-8"?><configuration><system.webServer><modules><remove name="ApplicationSecurityAuthenticationModule"/></modules></system.webServer></configuration>This line removes the authentication Node.js module from the global authentication system, because this Node.js application encapsulates the OpenID Connect authentication mechanisms. - 3.Repeat the above two steps for the
hooks
andscim
modules as well. - 4.Copy the following .NET assemblies and dependency libraries from
\wfgen\bin
to each custom webform'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 Okta through the OpenID Connect protocol. Make sure to have provisioned your users to WorkflowGen in order for them to successfully access WorkflowGen.
The self-provisioning connector is a directory connector that automatically creates and synchronizes a user based on the user's session token claims that contain claims from the OpenID Connect provider ID token. This feature is only compatible with an OpenID Connect authentication.
- Make sure to have a working WorkflowGen instance.
- Make sure to know the instance's IP address or its fully qualified name.
- Make sure to know the address of the instance.
- Make sure to have configured Okta or one of the other OIDC-compliant authentication methods (Azure Active Directory, AD FS, Auth0, or Microsoft Identity Platform v2.0).
This section will guide you through the WorkflowGen configurations necessary to set up the self-provisioning feature with a directory.
This directory will contain all of the users that are not provisioned elsewhere. To create a self-provisioning directory, do the following:
- 1.On the Directories page in the WorkflowGen Administration Module, click New directory.
- 2.Fill in the form:
- Name:
SELF_PROVISONING
(or something else) - Description: A good description of the directory
- Directory connector:
Self-provisioning