Further info about OIDC-based single sign-on

In versions 9.6 and newer, the settings in the earlier appsettings.json are stored in two files:

• %PROGRAMDATA%\MemoQ Server\Oidc Backend\appsettings.User.json contains all the settings which stay unchanged when you update or upgrade memoQ TMS.
• %PROGRAMFILES%\Kilgray\MemoQ Server\Oidc\appsettings.json contains the settings which revert to their default values when you update or upgrade memoQ TMS.

The upgrade does not touch the appsettings.json file you used in version 9.5. To start the Authentication Manager's service again, you need to clean things up:

1. In the %PROGRAMDATA%\MemoQ Server\Oidc Backend folder, open the files appsettings.json and appsettings.User.json in a text editor.
2. Copy everything from appsettings.json to appsettings.User.json, except the parts under the Serilog key.
3. If you changed any of the logging settings, copy the parts under the Serilog key to %PROGRAMFILES%\Kilgray\MemoQ Server\Oidc\appsettings.json.
4. Delete appsettings.json from the %PROGRAMDATA%\MemoQ Server\Oidc Backend folder.
5. Restart the MemoQ Server service using the memoQ TMS Deployment Tool or the services.msc Windows management console.
6. Start the MemoQ OIDC Backend Service.

In this case, you only need to start the Authentication Manager's service. Run the services.msc command, right-click MemoQ OIDC Backend Service in the list, and in the menu, click Start.

To do this, execute any command with the MemoQ.Security.Oidc.ConfigTool. The safest one is GetBackendBaseUrl, as it does not change anything in the configuration.

In a command prompt with admin rights, run these commands:

cd "%PROGRAMFILES%\Kilgray\MemoQ Server\Oidc"

MemoQ.Security.Oidc.Backend.ConfigTool.exe GetBackendBaseUrl

After the command prompt returns, the database upgrade is done.

This is caused by a known issue of the .NET Framework. The exe files in the %PROGRAMFILES%\Kilgray\MemoQ Server\Oidc folder are self-extracting archives. Their contents (the actual programs) are extracted to (and run from) a subfolder of the user's %TEMP% folder. It can happen that something (for example, anti-virus software, a .NET update, etc.) cleans up the %TEMP% folder, and then the Authentication Manager and its config tool cannot run.

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. Then start the Authentication Manager service again: Run the services.msc command, right-click MemoQ OIDC Backend Service in the list, and in the menu, click Start.

If something is wrong with your OIDC sign-in, go through this list before contacting memoQ support.

• Run MemoQ.Security.Oidc.Backend.ConfigTool.exe, located in the in the %PROGRAMFILES%\Kilgray\MemoQ Server\Oidc folder to make sure the OIDC part in memoQ TMS's database is on the latest version (running the ConfigTool automatically does the update).

• Run MemoQ.Security.Oidc.Backend.ConfigTool.exe with the GetIdProvider command to list the configured ID providers. This is very useful if memoQWeb's sign-in page does not show the OIDC buttons or if the Use an external identity provider option is disabled in the memoQ desktop app. (These things should not happen if you have at least one ID provider set up.)

• If there are issues with memoQWeb's sign-in page, run MemoQ.Security.Oidc.Backend.ConfigTool.exe with the GetMemoQWebBaseUrls command. Check if memoQWeb's base URL is configured properly.

• Open the memoQ TMS's database in Microsoft SQL Server Management Studio and check if it has a table called dbo.__EFMigrationsHistory. If not, you need to install the database's OIDC part: run MemoQ.Security.Oidc.Backend.ConfigTool.exe with the GetMemoQWebBaseUrls command. This is needed for avoiding CORS issues on the Authentication Manager when used from memoQWeb. Then you need to set up OIDC as described here. Note that you can have multiple base URLs configured here.

• To check which OIDC identity providers are set up on memoQ TMS: Open https://<Authentication Manager host name>:<Authentication Manager port>/auth/id_providers (for example, https://memoq.mycompany.com:5001/auth/id_providers) in a browser. memoQ TMS returns a JSON with the configured ID providers' basic data.

• To check the OIDC sign-in possibilities on memoQ TMS: Open https://<Authentication Manager host name>:<Authentication Manager port>/login (for example, https://memoq.mycompany.com:5001/login) in a browser. memoQ TMS returns the sign-in page's OIDC part.

1. In memoQ, the user chooses to log in with an external ID provider (Okta, Azure AD, etc.)
2. The memoQ desktop app requests and gets the URL of the Authentication Manager's login page (to choose an ID provider).
3. The memoQ desktop app generates a random login ID for identifying the login session. It opens the login URL (received in step 2) in the machine's default browser, and passes the hash of the generated login ID to the login page. This page is served by Authentication Manager over HTTPS.
4. On the login page, the user chooses an ID provider. The login function of the Authentication Manager passes the login ID hash and the ID provider's name. As a response, it receives a redirect to the ID provider's login page, with the login ID hash and a callback path as parameters.
5. The browser is redirected to the ID provider, forwarding the login ID hash and the callback path as parameters.
6. The ID provider authenticates the user, and generates an auth code. Then it redirects the browser to the callback path, and passes the generated auth code.
7. The browser is redirected to the callback path, and forwards the login ID hash and the auth code to the Authentication Manager as parameters.
8. The Authentication Manager calls the ID provider to exchange the received auth code to an ID token. This happens via a more secure back-channel communication.
9. The Authentication Manager receives and validates the received ID token which contains the user claims (the authenticated user's details), and saves it into the memoQ database, using the ID token as the record's key.
10. The memoQ desktop app sends the login ID to the memoQ server, and requests a memoQ session.
11. The memoQ server creates a hash from the login ID, and tries to get the ID token based on that hash. If successful, it creates a memoQ session for the ID token's authenticated user.

The login flow from memoQweb follows the same logic as the desktop:

1. The user opens memoQWeb (practically, the central web-based login module) to work in webTrans or webPM. The login screen shows the list of the registered ID providers below the traditional memoQ login form.
2. On the login page, the user chooses an ID provider. The web client generates a random login ID for identifying the login session.
3. The browser is redirected to the ID provider, forwarding the login ID hash and the callback path as parameters.
4. The ID provider authenticates the user, and generates an auth code. Then it redirects the browser to the callback path, and passes the generated auth code.
5. The browser is redirected to the callback path, and forwards the login ID hash and the auth code to the Authentication Manager as parameters.
6. The Authentication Manager calls the ID Provider to exchange the received auth code to an ID token. This happens via a more secure back-channel communication.
7. The Authentication Manager receives and validates the received ID token which contains the user claims (the authenticated user's details), and saves it into the memoQ database, using the ID token as the record's key.
8. The memoQWeb front-end sends the login ID to the memoQ server, and requests a memoQ session.
9. The memoQ server creates a hash from the login ID, and tries to get the ID token based on that hash. If successful, it creates a memoQ session for the ID token's authenticated user.

In a test environment, you can use a self-signed certificate instead of a commercial one.

1. Download, unpack and run the CreateAndInstallSelfSignedCert.ps1 PowerShell script file in admin mode. This step will create a self-signed certificate, register it as trusted certificate and export it to a password protected .pfx file to the current folder.
2. Open the Manage Computer Certificates application and on the Certificates - Local Computer/Personal/Certificate and Certificates - Local Computer/Trusted Root Certification Authorities/Certificate nodes you should see the newly created certificate.
3. Edit the appsettings.json file, set the Kestrel.Certificates.Default.Subject property to the value used previously as <dns name for the certificate>.

On each client machine where someone will use the memoQ desktop app or memoQweb, you need to register the certificate as trusted:

1. Copy the certificate file created on the server machine to the client machine.
2. Double click on the file and the Certificate Import Wizard will open.
3. Select Current User as store location and click Next.
4. Click Next again.
5. Enter the certificate file's password (the one you set when exporting the certificate), and click Next.
6. Click Next again.
7. Click Finish.

If you need to use the Authentication Manager on the server machine, with self-signed certificates, you also need to do this on the server machine, starting from Step 2.

In a test environment, you can use a certificate file instead of a certificate store.

Replace the Kestrel section at the beginning of the file %PROGRAMDATA%\MemoQ Server\Oidc Backend\appsettings.json with this:

"Kestrel": {

"Certificates": {

"Default": {

"Path": "<absolute-path-of-certificate-file>",

"Password": "",

},

},

},

Grant the Authentication Manager read access on this certificate:

1. Open the folder that contains the PFX file.
2. Right-click the certificate. In the context menu, choose Properties.
3. In the <certificate> properties window, click the Security tab, then click the Edit button.
4. In the Permissions for <certificate> 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.