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

Use a certificate issued by a trusted certification authority

1. The network administrator or security officer installs the certificate on the server machine.
2. Edit the appsettings.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
• Logging details

Set these up in the file %PROGRAMDATA%\MemoQ Server\Oidc Backend\appsettings.json.

Path to the SSL certificate

In a production environment, the certificate should be in a certificate store.

Add this section to the beginning of appsettings.json:

"Kestrel": {

"Certificates": {

"Default": {

"Subject": "<subject-value-you-wrote-down-before>",

"Source": "Store",

"StoreName": "My",

"Location": "LocalMachine",

"AllowInvalid": "true",

},

},

},

Later in the setup process, you need to grant the Authentication Manager read access on this certificate.

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: Define one or more domains (for example, “*.company.com”) or specific host names (for example, "machine1.company.com") by entering names or URLs 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 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 rest of the 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.

Set parameters for your ID provider

Note: As of September 2020, memoQ supports Azure AD 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, OktaCustom.settings.json, OktaOrg.settings.json), and put it into the %PROGRAMFILES%\Kilgray\MemoQ Server\Oidc folder. Open it in a text editor, and add your values:

Generic fields (in all settings files)

Template	The template file that you are filling in with the parameter values. DO NOT CHANGE!
Parameters
Name	The ID provider’s name in the memoQ server 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.
ClientId	The Client ID that the ID provider generated for your memoQ server. You need to change the default value.
CallbackPath	The last part of the callback URL that you registered at the ID provider. You need to change the default value.

 

IDP-specific fields

Tenant	Your Microsoft Azure tenant. You need to change the default value.
OktaDomain	Your Okta domain. You need to change the default value.
AuthServerId	Default value: default. Change if needed for your custom Okta setup.

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

Example:

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 SetMemoQWebBaseUrl -u <memoqweb_base_url>

Example:

MemoQ.Security.Oidc.Backend.ConfigTool.exe SetMemoQWebBaseUrl -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).

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 server also runs this way. But if your memoQ server'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.

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

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. In the Permissions for <certificate> private keys window, click the Add button.
4. 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.
5. When Windows recognizes the service name, click the OK button.
6. 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 can accept:

• SSO logins: Users choose the ID provider service and perform the login with company’s central Identity Management system.
• Local logins: Users who have no ID provider credentials 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).