[SPN9] How to set-up and use Oauth2 as an authentication method for API requests

Introduction

Starting SPNS 9.5 the new OAuth2 authentication mechanism has been introduced. This article aims to guide thoroughly on how to configure your system to use oauth2 then how use Oauth2 (Client credentials flow) as an authentication method for API requests (for instance a translation). To perform this we need an user with Admin role/access to configure and then a user to use Oauth2.

In Oauth2 workflow, entities involved are:
- Authorization Server: systran-ses-console component that grants access to resource.
- Resource Server: systran-ses-gateway component that gives access to translation.
- Client: we will use cUrl

Main steps:

1) Configure (or check configuration of) your SPN9 server for Oauth2
2) Translate using Oauth2 authentication
3) Advanced checks

1) Configure (or check configuration of) your SPN9 server for Oauth2

1.1) Prerequisites:

- a valid FQDN to access the Web UI: https://SPN9_CONSOLE_PUBLIC_URL
- a SSL certificate signing it.

1.2) Configure your SPN9

1. Make sure that the Public URL of the SYSTRAN Console is configured using your FQDN: from Web UI: Administration > Settings > Console Settings > Public URLs. If not, update it, restart systran-ses-console service and test it.

2. Ensure Public URL is define on SYSTRAN Gateway side. To do that, first, let's create a config file using your server hostname. If this file already exists, you have to update it.

touch /opt/systran/apps-node/translation-gateway/config/`hostname`.yaml
chown systran:systran /opt/systran/apps-node/translation-gateway/config/`hostname`.yaml

Set Gateway config file (adjust URL variable first)

URL=[Console Public URL]

echo -e "Gateway:
  InputInterfaces:
    translate-api:
      authorizationUrl: https://$URL
      ses8Url: https://$URL
  
      OfficePluginsAPI:
        host: $URL
        port: 8904
        Settings:
          authenticationMode: spnsOAuthPkce # [spnsOAuthPkce, spnsPro]
          resourceUrl: https://$URL:8904
          authorizationUrl: https://$URL/oidc
" > /opt/systran/apps-node/translation-gateway/config/`hostname`.yaml

/!\ YAML files require proper indentation /!\
(Note that we will also add the Office 365 entry valid from version 9.7+)

then run the command

systemctl restart systran-ses-gateway

Note 1: If you use Firewalld to redirect external 443 port to default 3443 Console port, note that you have to add the following rule to ensure internal connection will not be blocked:

firewall-cmd --permanent --direct --add-rule ipv4 nat OUTPUT 0 -p tcp -o lo --dport 443 -j REDIRECT --to-ports 3443

Note 2: If you use "multiple frontends" (Gateway services dispatcher on multiple servers ), ensure the following file is the same across your servers: /opt/systran/apps-node/translation-gateway/certificates/credentials.json

Note 3: For integration with Microsoft latest addins (SYSTRAN Translator for Word, Excel and PowerPoint ; SYSTRAN Translator for Outlook), SYSTRAN App and Chrome&Firefox extensions (through "Login" option) you need to be at least release SPNS 9.8.2 in order to meet the OAuth Device Flow authentication.

1.3) Quick configuration Checklist

To ensure your configuration is valid, you can:
1) Check you can connect to Web UI using a valid FQDN
2) Ensure the same FQDN is used in Gateway
3) Test you can connect to this FQDN from SSH via:

curl https://SPN9_CONSOLE_PUBLIC_URL

2) Translate using Oauth2 authentication

2.1) Step 1 - Generate Oauth2 (Client credentials flow) credentials

Required credentials are a Client Id and a Client Secret. If you already have it, go to the next step.

From 9.6, this can be done via the Web UI...

1) Connect to https://SPN9_CONSOLE_PUBLIC_URL/user or personal info

2) Click as described below:

Fill up with a Client Name and then click on submit

On the next screen take a note of the client ID and client secret (visible one time; only upon creation)

...Or via an API call

It requires a Legacy API Key:

curl --location --request POST '<https://SPN9_CONSOLE_PUBLIC_URL>/oidc/reg?apikey=<API_KEY>' \
--header 'Content-type: application/json' \
-d 
'{
"client_name": "[CLIENT_NAME]",
"grant_types": ["client_credentials"],
"introspection_endpoint_auth_method": "none",
"revocation_endpoint_auth_method": "none",
"response_types": [],
"redirect_uris": ["https://<SPN9_CONSOLE_PUBLIC_URL>"]
}'

Response will be a JSON including a client_id and a client_secret.

2.2) Step 2 - Get a Token

Now we need to generate an access token to authenticate.

curl --location --request POST '<https://SPN9_CONSOLE_PUBLIC_URL>/oidc/token' \
--header 'content-type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=<client_id>' \
--data-urlencode 'client_secret=<client_secret>'

2.3) Step 3 - Translate!

Now use this access token to authenticate and translate!

Token should be added in the header and endpoint is SYSTRAN Gateway

Authorization: Bearer <ACCESS_TOKEN>

Example

curl --location --request POST '<https://SPN9_GATEWAY_PUBLIC_URL>/translation/text/translate' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <access_token>' \
-d '{"input" : "This is a test using oauth2!", "source" : "en","target" : "fr"}'

Note: you may require to explicitly specify which port to use (ie 8904) when sending a translation request. For instance, a test with a real-life server may look like the following:

curl --location --request POST 'https://clientName.mysystran.com:8904/translation/text/translate' \

3) Advanced checks

In some cases, you may have to re-set the Redirect URI in the existing credentials (URI redirect error for instance). Prerequisite is to identify your [Console Public URL].

First step is to connect to MongoDB:

mongo -u XXXXXXXXXXXX-p XXXXXXXXXXXX--authenticationDatabase admin

Switch to user DB

use user

And list credentials (if too many credentials are displayed, see note below)

db.getCollection('client').find({}).pretty()

If you identify redirect_uris entries with an "OLD_URL":

{
  [...]
    "redirect_uris": ["https://OLD_URL/oidc/cb"],
  [...]
}

You will have to update it:

db.getCollection('client').update({"payload.redirect_uris": "https://OLD_URL/oidc/cb"},
{"$set":{"payload.redirect_uris.$":"https://[Console Public URL]/oidc/cb"}}
, {multi: true}
)

And finally restart console:

systemctl restart systran-ses-console

Note:

 - In most cases, OLD_URL is localhost:3443

 - If too many credentials are displayed, you can filter on credentials having the wrong URL:

db.getCollection('client').find({"payload.redirect_uris.0": { $exists: true, $ne: "https://[Console Public URL]:3443/oidc/cb" }})