Further info about OIDC-based single sign-on

In version 9.6, we separated the settings in appsettings.json into two files:

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

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

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.

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.