OpenId Connect Authentication / Authorization
Configuration steps on OpenID Connect Provider
The following describes the configuration that is needed on the OpenID Connect Provider.
Firstly you need to create a client to use with InterFormNG2.
Secondly, InterFormNG2 uses role-based security, so a number of roles need to be defined. The OpenID Connect standard does not detail how roles should be handled, so this can vary between providers. The following roles must be created:
Firstly you need to create a client to use with InterFormNG2.
Secondly, InterFormNG2 uses role-based security, so a number of roles need to be defined. The OpenID Connect standard does not detail how roles should be handled, so this can vary between providers. The following roles must be created:
Role name | Description |
ROLE_SYSTEM_ADMIN | System administrator access |
ROLE_TENANT_ADMIN | Tenant administration access |
ROLE_USER | Regular user access |
ROLE_READ_ONLY | Read-only access |
ROLE_WEB_SERVICE | Minimal access for web service clients. |
The following is a description on how to create the needed client and roles in the Keycloak user interface:
- Select an existing realm or create a new one.
- Go to Clients → Create client. Select client type “OpenID Connect”. Give it an appropriate client id such as “interformng2”. The client id must be valid in a URL without encoding, so only use alphanumeric characters.
- Press Next to get to Capability Config. Switch on “Client authentication”. As a minimum enable “Standard flow”. You may also want to enable “Service accounts role” (see the next section on webservice input).
4. Press Next to get to “Login Settings”. Under “Valid Redirect URIs”, add the URL of your InterFormNG2 installation with “/OpenId” added at the end. For instance, https://example.com:8086/openId. Under
“Web origins” put a plus character “+”.
Now save the client.
5. Go to the “Roles” tab of the client. Create Role → ROLE_SYSTEM_ADMIN. Repeat this process for all the roles in the above table.
In an InterFormNG2 multi-tenant configuration, it is also necessary to create a role for each tenant, to grant access to that tenant. For each tenant, create a role with the name TENANT_<tenantid> where you replace <tenantid> with the ID of the tenant in InterFormNG2, so for instance for the default home tenant, create role TENANT_home.
The created roles can be assigned to users. Note the important limitation that in a multi-tenant configuration, each user can only have access to ONE tenant. I.e. only assign one of the TENANT_ roles to each tenant. If you do not assign a TENANT_ role, the user will as default have access to the home tenant.
Also note that it is possible for a user to have both ROLE_SYSTEM_ADMIN as well as roles on a tenant. When logging in as a user with both ROLE_SYSTEM_ADMIN and a tenant role, you will be asked after login to choose between system admin access and tenant access.
Assigning roles to users
The defined roles can be assigned to the users that should have access to InterFormNG2. Note that in addition to these roles, it is mandatory to also assign the default role “offline_access” to all users, so InterFormNG2 can create a refresh token to maintain the user's access while the user is active.
In Keycloak, user roles are assigned under Users on the “Role mapping” tab.
In Keycloak, user roles are assigned under Users on the “Role mapping” tab.
Additional roles (InterFormNG2 user groups)
With the addition of user groups configuration in InterFormNG2, a number of new authorizations (roles) have been added. These can also created and assigned with OpenID, in the same way as the regular roles. The list of roles is quite long so note that it is only necessary to create the ones that are going to be used. The following roles can be created:
Display name | Value |
Approver - Templates | ResourceApprove-template |
Approver - Translations | ResourceApprove-translation |
Approver - Images | ResourceApprove-image |
Approver - Fonts | ResourceApprove-font |
Approver - Sample documents | ResourceApprove-document |
Approver - Workflows | ResourceApprove-workflow |
Approver - Velocity e-mail templates | ResourceApprove-mailTemplate |
Approver - Template components | ResourceApprove-templateComponent |
Approver - Template styles | ResourceApprove-style |
Approver - Validation rules | ResourceApprove-validationRule |
Approver - Transformations | ResourceApprove-transform |
Approver - Other resources | ResourceApprove-other |
Editor - Templates | ResourceUpdate-template |
Editor - Translations | ResourceUpdate-translation |
Editor - Images | ResourceUpdate-image |
Editor - Fonts | ResourceUpdate-font |
Editor - Sample documents | ResourceUpdate-document |
Editor - Workflows | ResourceUpdate-workflow |
Editor - Velocity e-mail templates | ResourceUpdate-mailTemplate |
Editor - Template components | ResourceUpdate-templateComponent |
Editor - Template styles | ResourceUpdate-style |
Editor - Validation rules | ResourceUpdate-validationRule |
Editor - Transformations | ResourceUpdate-transform |
Editor - Other resources | ResourceUpdate-other |
Due to the number of different roles, it can be a good idea to make use of groups where several different roles can be assigned to a single group. All the users that are a member of that group, will then have all of those roles.
Configuration for webservice input
When using workflows with webservice input, it is recommended to use the client credentials authentication flow, as this is simpler for machine-machine communication. The remote output client can only operate with the client credentials flow. To use client credentials flow, firstly make sure that the authentication provider allows this. In Keycloak this is done by enabling the “Service account roles” authentication flow on the client.
Secondly, make sure that the authentication provider includes the client id in the Audience (aud) claim in the access token. In Keycloak this can be configured as follows:
- Under client scopes, create a new scope for this purpose. Call it for instance “client-self-audience”. Make sure the switch “Include In Token Scope” is off.
- On the new scope, select the “Mappers” tab, then Add Mapper → By Configuration → Audience. Give it a name and under “Included Client Audience” select your client id. Make sure “Add to access token” is enabled.
3. Finally navigate back to the client and under the “Client scopes” tab, add the new client-self-audience scope to the client scopes as “Default” type.
Configuration steps on InterFormNG2
Once the OpenID Connect provider has been configured, then the InterFormNG2 configuration can be updated in the application-default.properties file. The following properties must be set:
Property | Value |
authentication.provider | OpenIdConnect |
authentication.provider.resourceId | The ID of the client that was created on the provider. |
authentication.provider.discoveryUrl | The OpenID discovery URL. For keycloak this will be https://HOST:PORT/realms/REALM/.well-known/openid-configuration, where HOST and PORT are the host and port of the Keycloak server and REALM is the name of the realm that contains the client created for InterFormNG2. |
authentication.provider.redirectUri | The redirect URI that was specified in the provider configuration. |
authentication.provider.secret | The secret defined on the provider. With Keycloak this is found on the “Credentials” tab of the client. Alternatively this setting can be set in the settings user interface for Authentication Provider instead. The advantage to setting this in the UI is that the value will be stored with encryption. When it is set in the UI, it is not needed in these properties. |
Example values:
authentication.provider=OpenIdConnect
authentication.provider.resourceId=interformng2
authentication.provider.discoveryUrl=https://192.168.151.77:8080/realms/interform/.well-known/openid-configuration
authentication.provider.redirectUri=https://localhost:8086/openId
authentication.provider.secret=4uz7MzcvBXwhqf8BJwOIFib4eYtPu1CX
Multi-tenant configuration for web service clients
Refer to the section, Microsoft Entra ID Authentication, and the sub-section, Configuration for web service clients on Microsoft Entra ID.
Using remote output client with OpenID authentication
Refer to the section, Microsoft Entra ID Authentication
and the sub-section, Using remote output client with Microsoft Entra ID authentication.
and the sub-section, Using remote output client with Microsoft Entra ID authentication.
Using web-service input workflows with OpenID authentication
When InterFormNG2 is configured for OpenID authentication, then web-service clients will also need to authenticate with the OpenID provider when invoking workflows that have the OAuth2 web-service input component.
We recommend using the client credentials flow for authentication. As described above, this means that the access token does not contain a tenant access role, so for multi-tenant environments, requests to InterFormNG2 workflows need to include the APIKey HTTP header.
Errors related to APIKey checks are printed to the system log, so if you experience authentication problems with webservice clients, then look in the system log for error messages that start with “Webservice Input:".
We recommend using the client credentials flow for authentication. As described above, this means that the access token does not contain a tenant access role, so for multi-tenant environments, requests to InterFormNG2 workflows need to include the APIKey HTTP header.
Errors related to APIKey checks are printed to the system log, so if you experience authentication problems with webservice clients, then look in the system log for error messages that start with “Webservice Input:".
Related Articles
Microsoft Entra ID Authentication
This section describes the authentication for integration with AzureAD. Configuration steps on Microsoft Entra ID First create and configure the application in Microsoft Entra ID Active Directory Admin Center as follows. Create an app registration ...Two factor authentication
Registration process In addition to user name and password, you can choose to enable two-factor authentication. The option to enable is available from the top-right user menu: Once enabled, the option to disable is available in the same menu: Once ...Users of InterFormNG2
This section covers everything about users in InterFormNG2, and covers these areas: 1.Get started: Sign on to InterFormNG2 2.User types and authority. 3.Create/delete a user 4.Assign tenant(s) to user(s). 5.Change the password for a user 6.User roles ...Install InterFormNG2 on Windows and connect to IBM i
This section concerns the scenario, where you want to install InterFormNG2 on Windows and still be able to process spooled files coming from a connected IBM i machine e.g. via monitored output queues. The reasons why you would want to go with this ...Tenant E-mail server
This section concerns E-mail servers (SMTP setup) for a tenant. A similar setup is available for system emails. For a normal setup you need to configure at least one email server, before you can send emails in InterFormNG2. This is covered below. In ...