OAuth / OpenID Connect
OAuth is an open standard that allows access of web application by authentication via a third party authentication server. OpenID Connect is a layer on top of OAuth that standardizes the profile information shared with the web application. Txture supports both bare OAuth and OpenID Connect to manage access control for users of your organization.
The configuration of OAuth-based authentication can be done directly in the txture.properties file or in the System Configuration for SaaS instances. All settings regarding OAuth have to be prefixed by
txture.security.auth.*
Note
A restart of the Txture instance is required for the settings to be applied. To initiate a restart of your SaaS instance contact support@txture.io.
The below table explains each of the contained settings and its meaning.
| Name | Example value | Description |
|---|---|---|
| enabled | oauth2 | Indicates that oauth will be used. |
| oauth2.clientId | clientid1234.apps.googleusercontent.com | ID of the application at your identity provider. |
| oauth2.clientSecret | thisissecret | Corresponding secret |
| oauth2.uri.accessToken | https://example.provider.com/oauth2/token | URL to obtain the access token |
| oauth2.uri.authorization | https://example.provider.com/oauth2/auth | URL for authorization |
| oauth2.uri.userInfo | https://example.provider.com/oauth2/userinfo | URL to obtain the user profile information |
| oauth2.scope | openid email | Space-separated list of OAuth scope settings - set this to include openid to adhere to OpenID Connect specifications. A good starting point is to include the scope email in order have a user's email mapped as its username. |
| oauth2.createUser.enabled | true | When set to true, users that are authorized by the provider will get their user account created automatically for Txture. Otherwise a corresponding user account with a corporate id set to the user subject (the sub claim for the user at your OAuth provider) is required to be present. |
| oauth2.corporateIdClaims | customUserID | Txture looks for the unique corporate ID in the following claims (in this order): oid, sub, username, preferred_username. If your authentication provider uses a different claim, you can set this here. Can be one claim or a space-separated list of claims in the preferred order. |
| oauth2.usernameClaims | my_username_claim | Txture looks for a username in the following claims (in this order): username, preferred_username, userPrincipalName, email, sub. If your authentication provider uses a different claim, you can set this here. Can be one claim or a space-separated list of claims in the preferred order. |
| oauth2.roleName | my_default_role | The name of the role that should be assigned to all newly created OAuth users. If the role is not found in the database, the default user-role is assigned. |
| oauth2.redirectOnStart | true | If set to true, user will be immediately forwarded to the configured OAuth login page upon reaching Txture |
Once you have provided the described property values in your txture.properties, restart Txture for the settings to take effect. Note that the Txture login form will change its appearance once OAuth is enabled. It will provide a "Login with OAuth" in addition to the option of logging in with local credentials (e.g. for administrative access).
Once a previously unknown user logs into Txture, it will try to fill all possible user form fields with the information provided by OAuth.
Redirect URLs
When setting up the allowed redirect URLs at your OAuth provider, please use the base URL of your Txture with a trailing slash as the redirect URL e.g. if your instance is reachable at https://txture.yourcompany.com use https://txture.yourcompany.com/ as the redirect URL. Additionally, there are two more redirect URLS that need to be added:
| URL | Purpose |
|---|---|
https://txture.yourcompany.com/survey.html | survey functionality |
https://txture.yourcompany.com/embed.html | Embedding reports in third party tools |
https://txture.yourcompany.com/ | Base |
Microsoft Azure Active Directory
The information needed for Azure Active Directory can be found on the App registrations page.
After adding Txture as a registered app you can use the following configuration within txture:
txture.security.auth.enabled=oauth2
txture.security.auth.oauth2.clientId={CLIENT_ID}
txture.security.auth.oauth2.clientSecret={CLIENT_SECRET}
txture.security.auth.oauth2.uri.accessToken=https://login.microsoftonline.com/{TENANT_ID}/oauth2/v2.0/token
txture.security.auth.oauth2.uri.authorization=https://login.microsoftonline.com/{TENANT_ID}/oauth2/v2.0/authorize
txture.security.auth.oauth2.uri.userInfo=https://graph.microsoft.com/oidc/userinfo
txture.security.auth.oauth2.scope=openid email profile
txture.security.auth.oauth2.createUser.enabled=true
The placeholders in curly braces must be replaced by the values found on the detail page of the registered txture app.
{CLIENT_ID}is listed as "Application (client) ID"{TENANT_ID}is listed as "Directory (tenant) ID"
The {CLIENT_SECRET} can be configured in the Certificates & secrets section.
FAQ
I use Azure AD authentication, and when I try to log in with OpenID, I now receive a 401 error message
Error message:
Failed to authenticate against https://login.microsoftonline.com/... /oauth2/v2.0/token. ('401 Unauthorized: [no body]')
The {CLIENT_SECRET} might have expired.
To solve this issue, a new secret needs to be created in Azure AD and entered in the settings OAuth2: Client Secret in the system configuration.