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
--header '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" }})