Okta Integration

Overview

This section provides instructions on:

It also provides additional information on SOAP services support.

Note: In the instructions, substitute <workflowgen url> with the domain and path to your WorkflowGen instance; for example, localhost/wfgen or www.mycompany.com/wfgen.

Okta authentication

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.

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 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.

Notes

  • 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. john.doe@example.com).

Okta configuration

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.

Step 1: Create an authorization server

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

You can find more information on authorization servers on the Okta developer website.

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 banner menu API drop-down list, choose Authorization Servers.

    Note: If you are in the Classic UI portal, choose the API item in the Security drop-down list.

  3. Click the Add Authorization Server button.

  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.

You should now be in the Settings section of your WorkflowGen GraphQL API authorization server. In this section, you'll see the Issuer property. Add /.well-known/openid-configuration to it and save it, since you'll need it for the WorkflowGen configuration later on.

Step 2: Add a claim

  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: Choose Access Token

    • Value Type: Choose Expression

    • Mapping: Enter the following Okta code:

      appuser.username != null ? appuser.username : appuser.email != null ? appuser.email : appuser.nickame != null ? appuser.nickname : null
    • Include in: Choose 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 Save button.

  4. Add another claim with the same information, but this time, set the Include in token type property to Id Token.

  5. Click the Save button.

Step 3: Add the server access policy

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.

  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.

Step 4: Add the scope

  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

    • Description: Use the default scope if no other scope is specified

    • Default scope: Check this option

  4. Click the Create button.

You've now properly configured your Okta authorization server for the WorkflowGen GraphQL API.

Step 5: Create a web application

  1. Go to the Okta Developer portal.

  2. In the Applications section, click the Add Application button.

  3. Click the Web button representing the type of application, then click Next.

  4. Enter the following information:

    • Name: WorkflowGen

    • Base URIs: <workflowgen url> without any path (just the base URL); for example, https://localhost, if <workflowgen url> is https://localhost/wfgen.

    • Login redirect URIs: <workflowgen url>/auth/callback

    • Leave the remaining properties set to their defaults.

  5. On the General tab of your WorkflowGen web application page, click the Edit button in the General Settings section.

  6. Click the Add URI button under the Logout Redirect URIs property.

  7. Enter <workflowgen url>/auth/logout/return in the field that appears.

  8. Click Save.

You've now successfully configured Okta for your WorkflowGen instance.

Review the registration

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, which can be found on the WorkflowGen web application's General tab.

  • A client secret, which can be found on the WorkflowGen regular application's General tab.

  • An audience, which can be found on the WorkflowGen GraphQL API authorization server page.

  • A metadata endpoint, which is the value you saved earlier when creating the authorization server.

WorkflowGen configuration

Now, you need to configure WorkflowGen to delegate its authentication to Okta.

Step 1: Add Okta values to the WorkflowGen web.config

Open the WorkflowGen web.config file and add the following properties:

<?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>
  • Replace <CLIENT ID> with the client ID of the WorkflowGen web app on Okta.

  • Replace <CLIENT_SECRET> with the client secret of the WorkflowGen web app on Okta.

  • Replace <METADATA_URL> with the URL that you built earlier from your Okta domain name.

You have probably noticed that the setting with the key ApplicationSecurityAuthUsernameClaim is set to the value entered in a rule earlier. Therefore, you could use any value here providing that you also modify the rule.

Table of web.config options

Option

Description

ApplicationSecurityAuthProvider

The name of the identity provider supported by WorkflowGen. At this time, there is support only for Okta, Azure Active Directory, Auth0, AD FS, and Microsoft Identity Platform v2.0. Value: okta, azure-v1, auth0, adfs, or ms-identity-v2

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 application.

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 is automatically generated by Okta.

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 authentication provider. Without this, you'll have to manually enter much more configuration in the web.config.

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 Okta 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.

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 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.

Step 2: Add some security values for session generation

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.conig file and add the following properties:

    <?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.

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

  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 modules

Certain 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. Add the following property to the WorkflowGen web.config file:

    <?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's web.config, add 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 and scim 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.

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

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 from the provider. 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

Okta user provisioning

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.

Prerequisites

  • 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).

WorkflowGen configuration

This section will guide you through the WorkflowGen configurations necessary to set up the self-provisioning feature with a directory.

Step 1: Create a self-provisioning 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

  3. Click Save.

Step 2: Configure the user fields-to-claims mapping

Now that you've created a new directory with the self-provisioning connector, you need to define which claims are mapped to which WorkflowGen user field. To do this:

  1. On the new directory's page, click Edit mapping.

  2. To the right of the name of the WorkflowGen user field, enter the name of the claim in the session token that you want to map.

    Here's an example of a session token generated by the auth node application from the Okta ID token connected with Google Apps:

    {
    "sub": "some.user@advantys.com",
    "iss": "https://<workflowgen_url>/auth",
    "aud": "https://<workflowgen_url>",
    "exp": 1535627127,
    "https://api.workflowgen.com/username": "some.user@advantys.com",
    "given_name": "Some",
    "family_name": "User",
    "nickname": "some-user",
    "name": "Some User",
    "picture": "https://lh4.googleusercontent.com/path/to/photo.jpg",
    "gender": "male",
    "locale": "en",
    "updated_at": "1970-01-01T00:00:00Z",
    "email": "some.user@advantys.com",
    "email_verified": true,
    "nonce": "ffdd6d95-31e6-4466-84c4-43f8c0fbaae7",
    "iat": 1535591128
    }

    These claims could be mapped in WorkflowGen like this:

    Note: The Username and Name fields are required.

  3. Click Save.

Okta configuration for mobile apps

Mobile applications must use an approach similar to that of regular web applications, which is called Authorization Code Flow with Proof Key for Code Exchange (PKCE). The main difference between this and the classic Authorization Code Flow is that the mobile application doesn't get a client secret, but instead exchanges a pair of codes to prove the origin of the authentication attempt. The issue is that a mobile application can't be trusted with a client secret because it's distributed directly to users and is therefore no longer under the developer's control, and the sources can be decompiled and analyzed to find secrets like this.

This section provides instructions on how to configure Okta for mobile apps so that your mobile users can benefit from delegated authentication as well.

Prerequisites

  • Make sure to have a licensed copy of WorkflowGen installed and running on a server.

  • Make sure to have administrative access to Okta to be able to configure it properly.

  • Make sure to have provisioned an existing Okta user with which you can authenticate to WorkflowGen so that you can use the application afterwards.

  • Make sure to have the WorkflowGen Plus mobile application installed on a device that you have access to.

  • Make sure to have the latest WorkflowGen Plus version installed on your device and that your device is supported.

  • Make sure to have successfully configured delegated authentication to Okta on your WorkflowGen instance following the instructions in the Okta authentication section.

Okta configuration

Step 1: Create a native application

  1. Go to the Applications tab in your Okta developer portal, then click the Add Application button.

  2. Choose the Native option, then click Next.

  3. Enter the following information:

    • Name: My Native Application (or the name of your application)

    • Login Redirect URIs: Add your custom redirect URIs here

    Note: Make sure to have checked the Authorization Code option.

  4. Click the Done button.

Step 2: Add a logout redirect URI

  1. Go to the General tab on your Okta native application page, then click the Edit button.

  2. Click the Add URI button next to the Logout redirect URIs property Title.

  3. Enter your custom logout redirect URI in the text field that appears.

  4. Click Save.

Step 3: Add callback URLs

On the Settings tab, scroll down to the Allowed Callback URLs and add the URL workflowgenplus://auth.authorize/okta.

Review the registration

If you've set up delegated authentication to Okta on your WorkflowGen server, you should have an access policy on your Okta WorkflowGen GraphQL API authorization server that will let any configured client access it. Therefore, there's nothing left to do on the Okta side. Here's a review of the information you need:

  • A client ID, which can be found on the native application page's Settings tab.

  • Your Okta domain name, which can be found directly to the left of your profile picture on the top right corner of the page.

All of this information must be given to the users who will be using the mobile application; they'll need to copy them directly into the app.

Okta configuration for server-side scripts

In some cases, you'll want to perform a specific task that can be automated but needs access to the WorkflowGen GraphQL API; this use case is often in the form as a server-side script. For this, OAuth2 provides a type of grant called Client Credentials that simply exchanges a client ID and secret for an access token. There is no ID token since it's not part of the OpenID Connect standard and there's no user involved.

This section provides instructions on how to configure Okta with a server-side script that has access to the GraphQL API. First, you'll need to configure a new web application in the Okta portal; then, you'll need to configure a new application in WorkflowGen.

Prerequisites

  • Make sure to have a licensed copy of WorkflowGen installed and running on a server.

  • Make sure to have administrative access to WorkflowGen.

  • Make sure to have administrative access to Okta to be able to configure it properly.

  • Make sure to have successfully configured delegated authentication to Okta on your WorkflowGen instance following the instructions in the Okta authentication section.

Okta configuration

  1. In the Applications section in your Okta developer portal, click the Add Application button.

  2. Choose the Service type, then click Next.

  3. Enter the name of your application, then click Done.

Review the registration

Here's a review of the information you need:

  • A client ID, which can be found on the registered application settings tab.

  • A client secret, which can be found on the registered application settings tab.

  • The WorkflowGen GraphQL API identifier, which can be found on its settings page.

WorkflowGen configuration

As with user provisioning, WorkflowGen needs to know which application is accessing the GraphQL API. Therefore, you have to register the application, which consists of your script.

Register a new application

  1. On the Applications page in the WorkflowGen Administration Module, click New application.

  2. Fill in the form:

    • Name: My Server Application

    • Description: A description that clearly identifies the script

    • Type: Non-interactive Client

    • Impersonate username: Any username that has the required access to the GraphQL API

    • Client ID: The client ID you retrieved earlier

    • Active: Check this checkbox

  3. Click Save.

Your application should now appear in the list of applications.

You should now have the necessary components in place to make GraphQL API requests with your script by passing the access token received from Okta from a Client Credentials Grant flow.

Okta configuration for single-page applications

JavaScript applications running in a browser are often hard to secure due to the open nature of the Web. Secure storage is nonexistent, and everything is in clear text (for HTTP version 1.1). Here's a quote from the Azure Active Directory team that summarizes the state of authentication with single-page applications:

The OAuth2 implicit grant is notorious for being the grant with the longest list of security concerns in the OAuth2 specification. And yet, that is the approach implemented by ADAL JS and the one we recommend when writing SPA applications. What gives? It’s all a matter of tradeoffs: and as it turns out, the implicit grant is the best approach you can pursue for applications that consume a Web API via JavaScript from a browser.

(Source: https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-dev-understanding-oauth2-implicit-grant)

It's therefore important that you make all of the necessary checks to verify the validity of your requests and the responses.

This section provides instructions on how to configure Okta with a single-page application (SPA) so that users can authenticate through it and make requests to the WorkflowGen GraphQL API. This configuration is done in two steps: registering your SPA, then setting some redirect URLs.

Prerequisites

  • Make sure to have a licensed copy of WorkflowGen installed and running on a server.

  • Make sure to have administrative access to Okta to be able to configure it properly.

  • Make sure to have provisioned an existing Okta user with which you can authenticate to WorkflowGen so that you can use the application afterwards.

  • Make sure to have successfully configured delegated authentication to Okta on your WorkflowGen instance following the instructions in the Okta authentication section.

Okta configuration

Step 1: Register a new single-page application

  1. On the Applications tab in your Okta developer portal, click the Add Application button.

  2. Choose the Single-Page App type, then click Next.

  3. Enter the following information:

    • Name: My SPA, or the name of your single-page application

    • Base URIs: The base URL of your application

    • Login redirect URIs: The redirect URI for your single-page application

  4. Click Done.

Step 2: Add a logout redirect URI

  1. Go to the General tab on your Okta native application page, then click the Edit button.

  2. Click the Add URI button next to the Logout redirect URIs property Title.

  3. Enter your custom logout redirect URI in the text field that appears.

  4. Click Save.

Review the registration

  • You need a client ID, which can be found on the General tab on the application page.

Your application should now successfully linked to the Okta infrastructure and users can log in through it. If you have met the prerequisites, your application will receive an access token that it can send to the WorkflowGen GraphQL API to make authorized requests as a Bearer token via the Authorization header.

Generating a universal link for WorkflowGen Plus

As of WorkflowGen Plus version 1.4.0 and WorkflowGen server version 7.14.0, you can generate a universal link to simplify the Okta login process for your WorkflowGen Plus mobile app users.

Base URL

  • protocol: workflowgenplus://

  • hostname: auth.init

Parameters

You'll need to specify the following parameters:

  • provider: okta

  • client_id: Use the client ID you created earlier in the configuration (e.g. 0o7gdj4hs92yh7)

  • domain: The Okta domain name without the URL protocol, whose value must be URL encoded (e.g. https://dev-958754.oktapreview.com/oauth2/{AUTH_SERVER_ID}/.well-known/openid-configuration%60)

  • audience: Your WorkflowGen URL, whose value must be URL encoded (e.g. http://workflow.mycompany.com/wfgen)

The universal link should follow this format:

workflowgenplus://auth.init?provider=okta&client_id=0o7gdj4hs92yh7&domain=https%3A%2F%2Fdev-958754.oktapreview.com%2Foauth2%2F{AUTH_SERVER_ID}%2F.well-known%2Fopenid-configuration&audience=http%3A%2F%2Fworkflow.mycompany.com%2Fwfgen

Once you've generated the universal link, give it to your users, who can use it to sign in to WorkflowGen Plus with the preset sign-in method.

Additional information on Okta integration

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.

  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 application.