Set up OIDC-based single sign-on on a memoQ TMS - Part 1 - for the company system administrator
memoQ TMS has different kinds of single sign-on: This document is mainly about OIDC-based SSO. The phrases "single sign-on" and "SSO" refer to the OIDC-based solution. The phrases "Windows SSO" and "Windows AD SSO" refer to memoQ TMS's older, Windows Active Directory-based SSO solution. From version 9.7, Windows SSO users can switch to OIDC SSO just like regular memoQ TMS users.
What you need
Before you start configuring, gather the information below. You will need these at different points during the process.
- A settings.json file for your identity provider (or IDP) (find them in the %PROGRAMFILES%\Kilgray\MemoQ Server\Oidc\examples folder)
- The Subject value from the certificate the Authentication Manager will use. It should be a commercial (not self-signed) certificate. It can be the one your memoQ TMS uses. On the server machine, open the Manage Computer Certificates application (or run the certlm.msc command). Find the certificate in the Certificates - Local Computer/Personal/Certificate folder. Double-click the certificate, click the Details tab and write down the hostname in the Subject field (for example, *.mycompany.com).
- The connection string for your memoQ TMS database: Open the folder %PROGRAMDATA%\MemoQ Server, and open Configuration.xml in a text editor. Copy the value between the <SQLConnectionString> tags.
- The port that memoQ's Authentication Manager will use. You need to open this port on the firewall. By default, it is 5001.
- A name for the IDP - this will be the IDP's name in the memoQ TMS database, and a part of the Account origin info in memoQ's User management window.
- A display name - the text on the "Sign in with IDP" button on the login page.
If you run into a problem during the setup, contact memoQ support.
Setup and configuration
The Authentication Manager is a separate service next to the memoQ Server service. It is installed together with memoQ TMS, but to make it work, you need to configure it (after registering your memoQ TMS at an ID provider).
When registering your memoQ TMS as the client of an identity provider service, you need to set a callback URL. This is where the IDP can reach the Authentication Manager. The callback URL looks like this:
The Authentication Manager needs a port (3) for communication with the IDPs. By default, this is port 5001. This port should be open for inbound and outbound communication. If needed, you can configure a different port in the application settings file.
You can choose the callback URL’s last part (4) as needed, but:
- It must not be “login”, “logout”, or “auth”.
- If you register at more than one ID provider, this part must be unique for each of them.
When you register the memoQ TMS as a client at the ID provider, the memoQ TMS receives a ClientID and a ClientSecret. You will need these to configure the Authentication Manager.
Make sure your firewall is set up correctly: The ID provider might require opening some ports on the company firewall. To learn more, search your ID provider's documentation.
Use a certificate issued by a trusted certification authority. This can be the same certificate that memoQ TMS uses.
- The network administrator or security officer installs the certificate on the server machine.
- Edit the appsettings.User.json file. Enter the Subject value in the Kestrel.Certificates.Default.Subject field.
The Authentication Manager needs to learn about these system configuration data:
Set these up in the file %PROGRAMDATA%\MemoQ Server\Oidc Backend\appsettings.User.json.
Logging details are now stored in a separate file, %PROGRAMFILES%\Kilgray\MemoQ Server\Oidc\appsettings.json.
Path to the SSL certificate
In a production environment, the certificate should be in a certificate store. The default settings under appsettings.User.json's Kestrel key are set up this way. Change only the Subject key's value: replace localhost with the certificate subject you wrote down before. Do not change other values.
Later in the setup process, you need to grant read access on this certificate to the Authentication Manager's service account.
Hosts allowed to call the Authentication Manager
In this example, “*” stands for any host name. If you want to limit access, edit the value of the AllowedHosts key: Enter one or more domains (for example, “*.company.com”) or specific host names (for example, "machine1.company.com"), separated by semicolons (;). Else, leave the AllowedHosts value unchanged.
If you changed the port number from the default, change the part after the colon (:) in the urls key:
Else, leave the urls value unchanged.
Communication with the database
The Authentication Manager communicates with the memoQ TMS database. Enter the memoQ TMS database’s connection string as a value for the ConnectionStrings.OidcLoginData key:
Do not simply copy and paste: In the JSON file, you need to escape the backslash character - that is, change "\" to "\\".
The %PROGRAMFILES%\Kilgray\MemoQ Server\Oidc\appsettings.json file defines the logging details.
Find the key "Name": "File" under Serilog.WriteTo. The keys under Args here define important parameters:
path: By default, the log is stored in the file %PROGRAMDATA%\MemoQ Server\Oidc Backend\LogFiles\log-.txt.
rollingInterval, rollOnFileSizeLimit, fileSizeLimitBytes: Logs are written to daily files (do not change this), but if the file size reaches the limit (100 MB by default), a second file will be created for that day.
retainedFileCountLimit: By default, the last 31 log files are kept on the server.
By default, logging level is Information. If you need more info, change the Serilog.MinimumLevel.Default key's value to Debug or Verbose.
Verbose lists everything, even names and secrets – use it only when it is really needed, and only if it complies to your organization's data protection policies.
These settings are not permanent: When you update memoQ TMS, its whole folder under %PROGRAMFILES% is overwritten. This means that all settings in appsettings.json will change back to their default values. We recommend not changing them - unless you really need to.
Set a safer working folder for the Authentication Manager (optional)
Because of a known issue with the .NET Framework, the program files for the Authentication Manager and the OIDC Configuration Tool might be deleted by 3rd-party software, for example, an anti-virus app. To avoid this: Create an environment variable called DOTNET_BUNDLE_EXTRACT_BASE_DIR, with Machine or System scope. Set its value to %PROGRAMDATA%\Temp\.net.
This may affect other .NET-based software on the memoQ TMS machine. Before this step, check if there are any other programs on the server that use self-extracting single-file executables. If yes, check if the change can disrupt them.
This step will not be necessary later: When memoQ is updated to .NET 5, this issue will be solved automatically.
Set parameters for your ID provider
Note: As of February 2023, memoQ supports Azure AD, Google, Microsoft, Okta (both standard and custom), and OneLogin instances. If your company uses another OIDC-based ID provider service, contact our Business Services department, who can provide the resources you need.
Choose the settings file for your company’s ID provider type (AzureAD.settings.json, Google.settings.json, Microsoft.settings.json, OktaCustom.settings.json, OktaOrg.settings.json, or OneLogin.settings.json), and put it into the %PROGRAMFILES%\Kilgray\MemoQ Server\Oidc folder. Open it in a text editor, and add your values:
|Template||The template file that you are filling in with the parameter values.
DO NOT CHANGE!
|Parameters||See each sub-key's description below.|
|Name||The ID provider’s name in the memoQ TMS database, the key value in the oidc.IDProviderSettings table.
Change as needed.
|DisplayName||The text on the ID provider's button you’ll see on the login page.
Change as needed.
|ButtonIconUrl||URL for the ID provider’s icon that appears on the login page. There is a default icon URL, but you can set another one.|
|ButtonBackgroundColor||Color for the ID provider’s button that appears on the login page. There is a default color, but you can set another one.|
|ButtonTextColor||Text color for the ID provider’s button that appears on the login page. There is a default color, but you can set another one.|
|ClientId||The Client ID that the ID provider generated for your memoQ TMS.
You need to change the default value.
The client secret or secret key you received when registering your memoQ TMS at this ID provider.
You should not save the client secret into this unencrypted json file - unless it is absolutely necessary. Leave this value blank, and enter the client secret only when you set up the ID provider with the configuration tool.
The last part of the callback URL that you registered at the ID provider.
|Scope||The OIDC scope that the Authentication Manager will send to the ID provider. By default, it includes all standard scope values. You can remove values as needed, but the scope must contain the openid value. Else, single sign-on will not work.|
|Tenant||Your Microsoft Azure tenant. You need to change the default value.|
|OktaDomain||Your Okta domain. You need to change the default value.|
|AuthServerId||Your Okta authorization server's ID. You need to change the default value.|
|OktaOrg||Your Okta organization's base URL (without http://). You need to change the default value.|
The OIDC Configuration Tool is a command-line application that is designed to:
- Register an identity provider connection
- Configure connection details
- Install the Authentication Manager as a Windows service
- Start the service
It is in the %PROGRAMFILES%\Kilgray\MemoQ Server\Oidc folder. Open a Command prompt or PowerShell window with admin rights in this folder.
Add your ID provider configuration with the Configuration Tool's AddIdProvider command.
If you are setting up a new icon for the ID provider, add its path (on your computer) with the -i parameter.
Set the client secret you received from the IDP
The client secret is a password, so it is not secure to save it to a config file. Set it manually with the Configuration Tool.
|Parameter||Parameter’s name||Required or not||Description|
Use the same value as “Name” in the settings file.
The client secret value you received when registering the memoQ TMS in the ID provider service.
The client secret will be stored in hashed form in the database.
Set the base URL for the Authentication Manager
Do this with the Configuration Tool's SetBackendBaseUrl command. Required option: -u for the URL.
The base URL is constructed:
Set memoQweb base URLs
This information is important as this tells the Authentication Manager from what URLs it should accept calls as from memoQweb. Login attempts from this URL will be processed as memoQweb logins.
Set the same URL you use for logging in to memoQweb. It can be found on the Server administrator > Configuration and logging > Web addresses tab.
Use the Configuration Tool's SetMemoQWebBaseUrls command. Required option: -u for the URL.
Install the Authentication Manager service in Windows
Do this with the Configuration Tool's InstallService command.
Note: The account that you choose for running the service needs to have read and write access to the memoQ TMS database, and read access to the certificate you set up in the appsettings file. This is true for all account types (LocalSystem, NetworkService, VirtualService, or ServiceUser).
- having the memoQ TMS in a domain,
- in that domain, having a dedicated user account who runs all memoQ services (the memoQ TMS service and the MemoQ OIDC Backend Service)
- this dedicated user account should have access to the certificate.
|Parameter||Parameter’s name||Required or not||Description|
|-t||AccountType||required||The type of the account which will run the service. Possible values: LocalSystem, NetworkService, VirtualService, ServiceUser. In general, use a virtual service to run the Authentication Manager - memoQ TMS also runs this way. But if your memoQ TMS's database is on another server, you may need to use a service user instead.|
|-a||Account||optional||The account which will run the service. Required and used only if the AccountType option is ServiceUser.|
|-p||Password||optional||The password for the account which will run the service. If not specified, and the AccountType option is ServiceUser, the application will ask for the password interactively.|
If true, starts the service after installation. Default value is false.
Depending on other options, the service may not start automatically, After installation, run the services.msc command in Windows, and start the MemoQ OIDC Backend Service manually, if it is not running.
Grant the Authentication Manager service read access for the certificate
- On the memoQ TMS machine, run the certlm.msc command.
- In the Manage Computer Certificates window, find the certificate in the Certificates - Local Computer/Personal/Certificate folder.
- Right-click the certificate. In the menu, choose All Tasks > Manage Private Keys.
- In the Permissions for <certificate> private keys window, click the Add button.
- In the Select users... window, enter the name of the Authentication Manager service (if needed, run services.msc to see the list of all services), and click the Check names button.
- When Windows recognizes the service name, click the OK button.
- In the Permissions for <certificate> private keys window, click the service's name. Make sure the service only has Read permission, then click the OK button.
Restart software components
At this point, you need to restart:
- the memoQ TMS service
- the IIS application pool that runs memoQweb
the Authentication Manager service (called MemoQ OIDC Backend Service in Windows's Services console
Make sure this service is set to Automatic, so that you do not need to start it manually after server machine restarts.
Authentication Manager is now configured on your memoQ TMS. The server accepts:
- SSO logins: Users choose an ID provider service, and sign in with the usernames and passwords they have at that ID provider.
- Legacy SSO logins: Users sign in with the usernames and passwords they have in the company's Windows Active Directory. From the OIDC point of view, these users behave like local logins, and from memoQ TMS version 9.7, they can be changed to OIDC-based SSO.
- Local logins: Users who have neither ID provider credentials nor Windows AD accounts can still use their memoQ usernames and passwords.
You can now tell a memoQ admin user to start creating or updating users on the memoQ TMS (see Part 2 of this document).
Using multiple ID providers with a memoQ TMS
A memoQ TMS can accept user authentication from more than one ID provider system. For example, two departments of a company might use different Azure AD tenants, or in-house employees might use Okta, while external vendors (freelance translators) can sign in with their personal Google or Microsoft accounts.
In addition, you can have the “traditional” users who can log in with memoQ TMS credentials.
No multiple IDP systems per user: One memoQ user can only be connected to a single IDP system - or none, if they use the “traditional” memoQ login.
OpenID Connect-based SSO works only in versions 9.5 and up. Earlier versions of memoQ TMS cannot recognize and manage users of OIDC origin.
No rollback to earlier versions: When installing OIDC-based SSO on your memoQ TMS, the Configuration Tool adds new tables to the memoQ TMS database. This means you cannot use rollback to get back to your previous version.
See Part 2 of this document (for memoQ admins) here.
See troubleshooting tips, general user authentication schemas and a few tips for test environments here.