Set up OIDC-based single sign-on on a memoQ server - Part 1 - for the company system administrator

When registering your memoQ server 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 server as a client at the ID provider, the memoQ server receives a ClientID and a ClientSecret. You will need these to configure the Authentication Manager.

Notes for registering the memoQ server in Azure AD:

• You do not need Implicit Grant options (access tokens or ID tokens)
• You need a User.Read type of delegated permission
• You should set /logout as the default logout URL.

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

1. The network administrator or security officer installs the certificate on the server machine.
2. 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:

• Path to the SSL certificate
• Details of communication with the database
• Host name(s) it must answer

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 server database. Enter the memoQ server 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 "\\".

Logging

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 server, 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 server 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:

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.

MemoQ.Security.Oidc.Backend.ConfigTool.exe AddIdProvider -f [<absolute_or_relative_path>\]<your_settings_file>.json

If you are setting up a new icon for the ID provider, add its path (on your computer) with the -i parameter.

MemoQ.Security.Oidc.Backend.ConfigTool.exe AddIdProvider -f AzureAD.settings.json
MemoQ.Security.Oidc.Backend.ConfigTool.exe AddIdProvider -f C:\SSO-Ingredients\OktaOrg.settings.json -i C:\SSO-Ingredients\OktaIcon.png

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.

MemoQ.Security.Oidc.Backend.ConfigTool.exe SetClientSecret -s <client_secret> -n Okta

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.

MemoQ.Security.Oidc.Backend.ConfigTool.exe SetBackendBaseUrl -u <auth_man_base_url>

The base URL is constructed:

MemoQ.Security.Oidc.Backend.ConfigTool.exe SetBackendBaseUrl -u https://memoqserver.mycompany.com:5001

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.

MemoQ.Security.Oidc.Backend.ConfigTool.exe SetMemoQWebBaseUrls -u <memoqweb_base_url>

MemoQ.Security.Oidc.Backend.ConfigTool.exe SetMemoQWebBaseUrls -u https://memoqserver.mycompany.com/memoqweb

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

We recommend:

• having the memoQ server in a domain,
• in that domain, having a dedicated user account who runs all memoQ services (the memoQ server service and the MemoQ OIDC Backend Service)
• this dedicated user account should have access to the certificate.

MemoQ.Security.Oidc.Backend.ConfigTool.exe InstallService -t VirtualService
MemoQ.Security.Oidc.Backend.ConfigTool.exe InstallService -t ServiceUser -a AuthMan -p L0ngEn0ughIsStr0ngEn0ugh -s true

Grant the Authentication Manager service read access for the certificate

1. On the memoQ server machine, run the certlm.msc command.
2. In the Manage Computer Certificates window, find the certificate in the Certificates - Local Computer/Personal/Certificate folder.
3. Right-click the certificate. In the menu, choose All Tasks > Manage Private Keys.
4. In the Permissions for <certificate> private keys window, click the Add button.
5. 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.
6. When Windows recognizes the service name, click the OK button.
7. 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 server 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 server. 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 server 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 server (see Part 2 of this document).