Skip to main content

Localization for the Authorization Server

The Authorization Server supports localization by allowing administrators to configure specific strings for certain elements in multiple languages. Depending on the end-user's language selection and browser configuration, FPX can return values in the specified language (if so configured).

This chapter will illustrate the different commands that need to be executed to set up additional languages for the Authorization Server.

note

For the purposes of this guide, the creation of a new Resource Definition will be used as an example to illustrate language configuration commands. The same exercise can be carried out for the Resource Server, Client, Capability Ticket and Wallet configurations within the Authorization Server.

To define multiple languages when creating a new element (Resource Definition, Client etc.) within the Authorization Server, you can follow one of two approaches:

  1. Adding translations for one language at a time
  2. Adding translations for multiple languages at once

The first method uses the 'Accept-Language' header to define the language whereas the second method uses the JSON-API patch extension as defined in the 'Content-Type' header.

Adding translations for one language at a time

Using the 'Accept-Language' header

When creating entries in the database using the Wallet Admin API, you may include an Accept-Language header with the request, where the value is the language code.

You can find a full list of language codes in the IANA Language Subtag Registry (search for "Type: language"). These codes (and the value used in the Accept-Language header) are case insensitive.

Be aware that although the Authorization Server Admin API will not restrict which language codes you may use and configure translations for, there is a setting at the Authorization Server that does. Therefore it is important to ensure that the language translations you add and the languages that the Authorization Server is configured to accept are in alignment. At the Authorization Server, this configuration is defined by the i18n.allLanguages property in its application config.

Create a new Resource Server with localized values in a new language

Run a CURL POST command by inserting the 'Accept-Language' header as illustrated below:

curl --location --request POST '{{AS_ADMIN_URI}}/resource-server' \
--header 'ApiVersion: v1.0' \
--header 'Content-Type: application/vnd.api+json' \
--header 'Authorization: {{AS_ADMIN_STATIC_TOKEN}}' \
--header 'Accept-Language: en' \
--data-raw '{
"data": {
"type": "resource-server",
"id": "1",
"attributes": {
"baseUrl": "https://fpxrs-alpha.rs.dev.identos.ca",
"name": "Resource Server Alpha",
"resourceServerId": "fpx-alpha"
}
}
}'

In the above example, a new Resource Server is created with the default language of English as specified in the 'Accept-Language' header. The name attribute is localizable. Because we have supplied an Accept-Language header, this value will be automatically entered into the database as a localized value in English.

Updating an existing Resource Server with localized values

curl --location --request PATCH '{{AS_ADMIN_URI}}/resource-server/1' \
--header 'ApiVersion: v1.0' \
--header 'Content-Type: application/vnd.api+json' \
--header 'Authorization: {{AS_ADMIN_STATIC_TOKEN}}' \
--header 'Accept-Language: fr' \
--data-raw '{
"data": {
"type": "resource-server",
"id": "1",
"attributes": {
"baseUrl": "https://fpxrs-alpha.rs.dev.identos.ca",
"name": "Resource Server Alpha Localized",
"resourceServerId": "fpx-alpha"
}
}
}'

In this example, we change the value of the Accept-Language header and perform an update operation using the PATCH method as we would normally. The new value will automatically be entered into the database as a localized value in French.

Getting information about an existing Resource Server in a specific language

curl --location --request GET 'https://authapi.fpx-admin-api.dev.identos.ca/json-api/resource-server/1' \
--header 'ApiVersion: v1.0' \
--header 'Content-Type: application/vnd.api+json' \
--header 'Authorization: c94856c7-50ac-4fd3-b395-89af4c7d7bbc' \
--header 'Accept-Language: fr'

Here we use a simple GET request. The language that is returned for any localizable values is determined by the Accept-Language header.

Assuming the French translation was inserted according to the previous steps, the response to this request would be as follows:

{
"data": {
"type": "resource-server",
"id": "1",
"attributes": {
"baseUrl": "https://fpxrs-alpha.rs.dev.identos.ca",
"dateCreated": "2022-07-19T17:02Z",
"lastUpdated": "2022-07-19T17:02Z",
"name": "Resource Server Alpha Localized",
"resourceServerId": "fpx-alpha",
"version": 0
},
"relationships": {
"oAuthClient": {
"data": {
"type": "oauth-client",
"id": "2"
}
},
"resources": {
"data": [
{
"type": "resource",
"id": "1"
}
]
}
}
}
}

Adding translations for multiple languages at once

A common use case is one where you may have many translations to enter at once for a given entity. To do this, the Authorization Server Admin API provides an alternative method to the above.

This method makes use of the JSON-API patch extension. The Content-Type header in the request must specify this extension by appending "ext=jsonpatch" to the base value, as follows:

important

Do not include an Accept-Language header in your request when using this method.

Create a new entity with new translations in multiple languages

curl -X PATCH '{{AS_ADMIN_URI}}' \
--header 'Content-Type: application/vnd.api+json; ext=jsonpatch' \
--header 'ApiVersion: v1.0' \
--header 'Authorization: {{AS_ADMIN_STATIC_TOKEN}}' \
--data-raw '[
{
"op": "add",
"path": "/purpose",
"value": {
"type": "purpose",
"id": 1,
"attributes": {
"name": "purpose-name-translation-key-12345678"
}
}
},
{
"op": "add",
"path": "/language-translation",
"value": {
"type": "language-translation",
"id": 42,
"attributes": {
"locale": "en",
"messageKey": "purpose-name-translation-key-12345678",
"messageContent": "READ"
}
}
},
{
"op": "add",
"path": "/language-translation",
"value": {
"type": "language-translation",
"id": 42,
"attributes": {
"locale": "fr",
"messageKey": "purpose-name-translation-key-12345678",
"messageContent": "WRITE"
}
}
}
]'

Update an existing entity with new translations in multiple languages

When the original request was made, the AS Admin API automatically created a translation key for the localizable fields. You must therefore retrieve the existing translation key(s) for the localizable field(s) of that existing entity. This is done by simply making a GET request without an Accept-Language header, as shown here:

curl -X GET '{{WS_ADMIN_URI}}/purpose' \
--header 'Content-Type: application/vnd.api+json' \
--header 'ApiVersion: v1.0' \
--header 'Authorization: {{WS_ADMIN_STATIC_TOKEN}}'

Response

{
"data": {
"type": "purpose",
"id": "1",
"attributes": {
"dateCreated": null,
"lastUpdated": null,
"name": "Purpose-name-453d4e9b-f493-4543-8552-2e102633b3cd",
"version": 1
}
}
}

You must then use this key to make the next request where you will add multiple new translations in other languages:

curl -X PATCH '{{AS_ADMIN_URI}}' \
--header 'Content-Type: application/vnd.api+json; ext=jsonpatch' \
--header 'ApiVersion: v1.0' \
--header 'Authorization: {{AS_ADMIN_STATIC_TOKEN}}' \
--data-raw '[
{
"op": "add",
"path": "/language-translation",
"value": {
"type": "language-translation",
"id": 42,
"attributes": {
"locale": "fr",
"messageKey": "Purpose-name-453d4e9b-f493-4543-8552-2e102633b3cd",
"messageContent": "READ in French"
}
}
},
{
"op": "add",
"path": "/language-translation",
"value": {
"type": "language-translation",
"id": 42,
"attributes": {
"locale": "es",
"messageKey": "Purpose-name-453d4e9b-f493-4543-8552-2e102633b3cd",
"messageContent": "READ in Spanish"
}
}
}
]'