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

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

Prerequisites:

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

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. In the SYSTRAN Gateway service config file (in /opt/systran/apps-node/translation-gateway/config/), ensure the same Public URL is set for the 2 following entries:

...
authorizationUrl: https://SPN9_CONSOLE_PUBLIC_URL
...
ses8Url: https://SPN9_CONSOLE_PUBLIC_URL
...

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

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

Translate using Oauth2 authentication

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 https://SPN9_CONSOLE_PUBLIC_URL/administration/users) 

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)

Note : The ‘Last Used’ column is updated each time a request is made to generate an access token.

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' \
--data-raw '{
"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.

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

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>' \
--data-raw '{"input" : "This is a test using oauth2!", "source" : "en","target" : "fr"}'

If needed, ask your SYSTRAN representative for a detailed Oauth2 documentation.