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

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 's older, Windows Active Directory-based SSO solution. From version 9.7, Windows SSO users can switch to OIDC SSO just like regular memoQ server 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 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 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 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 server, but to make it work, you need to configure it (after registering your at an ID provider).

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: sso-callback-url

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 receives a ClientID and a ClientSecret. You will need these to configure the Authentication Manager.

Notes for registering the 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.

Set up a certificate for the Authentication Manager

Use a certificate issued by a trusted certification authority. This can be the same certificate that 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.

Set up basic configuration

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.

sso-appsettings-cert-store

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: sso-appsettings-host-filtering

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: sso-appsettings-mqs-db-conn-string

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:

sso-appsettings-log-file

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 , 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 up the Authentication Manager using the OIDC Configuration Tool

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 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 December 2020, memoQ supports Azure AD, Google, Microsoft, and Okta (both standard and custom) 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, or OktaOrg.settings.json), and put it into the %PROGRAMFILES%\Kilgray\MemoQ Server\Oidc folder. Open it in a text editor, and add your values:

sso-idp-settings

Generic keys (in all settings files)
Parameter	Description
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 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 server. You need to change the default value.
ClientSecret	The client secret or secret key you received when registering your memoQ server 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.
CallbackPath	The last part of the callback URL that you registered at the ID provider. You need to change the default value.
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.

IDP-specific keys
Parameter	Description
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:

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.

Examples:

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

Parameter	Parameter’s name	Required or not	Description
-n	Name	required	Use the same value as “Name” in the settings file.
-s	ClientSecret	required	The client secret value you received when registering the 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.

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

The base URL is constructed: sso-auth-man-base-url

Example:

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

Set base URLs

This information is important as this tells the Authentication Manager from what URLs it should accept calls as from . Login attempts from this URL will be processed as logins.

Set the same URL you use for logging in to . 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>

Example:

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 in a domain,
in that domain, having a dedicated user account who runs all memoQ services (the 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 - also runs this way. But if your '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.
-s	Start	optional	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.

Examples:

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

Restart software components

At this point, you need to restart:

the service
the IIS application pool that runs
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 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 (see Part 2 of this document).

Using multiple ID providers with a memoQ server

A memoQ server 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 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.

Version compatibility

OpenID Connect-based SSO works only in versions 9.5 and up. Earlier versions of memoQ server cannot recognize and manage users of OIDC origin.

No rollback to earlier versions: When installing OIDC-based SSO on your , the Configuration Tool adds new tables to the database. This means you cannot use rollback to get back to your previous version.

Further information

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.