.Stat Suite documentation

Authentication

Table of Content


Version history:
New authority_aliases property in the tenants.json under oidc entry for any app since January 11, 2023 Release .Stat Suite JS tachyon
OpenID compliance fully empowered since December 14, 2021 Release .Stat Suite JS 11.0.0
Allow to force DE authentication since October 5, 2021 Release .Stat Suite JS 10.0.0
Empower both anonymous and authenticated modes with March 05, 2020 Release .Stat Suite JS 4.0.1
Make DE authentication optional with November 30, 2020 Release .Stat Suite JS 6.1.0

Generic OpenID Compliance

.Stat Suite is based on OpenID-Connect authentication. Any OpenID-Connect compliant identity provider can be used. The .Stat Suite DevSecOps environment uses the third party tool Keycloak for that purpose. In that context, this tool also serves as a proxy for the GitHub and GitLab identity providers. These providers must be accessible through a secured HTTPS connection.

For information about how to configure Keycloak as identity provider, see here. For information about how to configure Keycloak as proxy to other identity providers, see here.


Authentication in the DE

The Data Explorer can be configured to whether support authentication or be fully public (anonymous mode). Authentication is made through an external dentity provider, see here.

The authentication is configured per organisation:scope in the tenants.json file in the config-data/configs folder with the oidc object. This means that each scope of a DE can have a dedicated authentication configuration. If oidc is not defined then the DE works without authentication (anonymous public access).

oidc setting description
required true: the user is required to login before using the DE
false: both anonymous and authenticated access are permitted
authority authority url of token issuer
authority_aliases array of alternative urls in addition to the main authority url
client_id client/application Id

Example:
in tenants.json:

      "de": {
        "oidc": {
          "required": false,
          "authority": "https://keycloak.siscc.org/auth/realms/OECD",
          "authority_aliases": [],
          "client_id": "app"
        }

Note that, even if the DE is only accessible by authenticated users, the shared views generated from it will still be publicly accessible. It is thus possible to disable the share option: see documentation.


Authentication in the DLM

The Data Lifecycle Manager requires an authentication configuration. Authentication is made through an external dentity provider, see here.

The authentication is configured per organisation:scope in the tenants.json file in the config-data/configs folder with the oidc object. This means that each scope of a DLM can have a dedicated authentication configuration.

oidc setting description
authority authority url of token issuer
authority_aliases array of alternative urls in addition to the main authority url
client_id client/application Id

Example:
in tenants.json:

      "dlm": {
        "oidc": {
          "authority": "https://keycloak.siscc.org/auth/realms/OECD",
          "authority_aliases": [],
          "client_id": "app"
        }

Authentication in the CORE services

The .Stat Suite CORE services do actually not allow authenticating a user, but simply expect a JWT token obtained from a previous independent authentication. The token is to sent as a Bearer header. The CORE services validate that the token was issued by the expected Authority for the expected Client and that it is not expired. In use-case where an HTTP request has no token or the token is not valid, 401 Unauthorized http code is returned.

Independently from the fact if the user is authenticated or not, the permissions defined with the Authorisation web service are being applied.

SDMX (NSI) web service

The complete documentation for the SDMX (NSI) web service openid-connect authentication configuration can be found here (mirrored here).

To enable OpenID middleware set OpenIdMiddlewareBuilder under <appSettings> in middlewareImplementation of the main configuration file. Please see the PLUGINS (mirrored here) for more information regarding middleware configuration in the SDMX (NSI) web service.

Example: e.g. in app.config in the config folder:

<add key="middlewareImplementation" value="OpenIdMiddlewareBuilder"/>

The authentication details are then configured in the auth.json file in the config folder with the auth object.

auth setting Description
enabled Is openid authentication enabled
allowAnonymous Is anonymous access allowed (request without JWT token)
authority Authority url of token issuer
clientId Client/application Id
requireHttps Is HTTPS connection to OpenId authority server required
validateIssuer Is iss (issuer) claim in JTW token should match configured authority

Example:
in auth.json:

{
    "auth": {
        "enabled":true,
        "allowAnonymous": false,
        "authority": "https://keycloak.siscc.org/auth/realms/OECD",
        "clientId": "app",
        "requireHttps": true,
        "validateIssuer": true
    }
}

Notes:

  • Set allowAnonymous=true in case the SDMX (NSI) web service is configured to process the received JWT token and if the Data Explorer is configured to allow for anonymous access.
  • (Since release .NET 6.0.0), the openid-connect authentication is enabled by default.
  • When the openid-connect authentication is enabled, on data retrieval the permissions are checked if the user has a data read permissions even if request is anonymous.
  • When the openid-connect authentication is disabled, all users (necessarily unauthenticated) can get all (even non-public) data.

Transfer web service

The complete documentation for the transfer web service openid-connect authentication configuration can be found here.

The authentication is configured in the dataspaces.private.json file in the config folder with the auth object.

auth setting Description
enabled Is openid authentication enabled
authority Authority url of token issuer
clientId Client/application Id
requireHttps Is HTTPS connection to OpenId authority server required
validateIssuer Is iss (issuer) claim in JWT token should match configured authority
claimsMapping Key/value mapping of a key used in the C# code to JWT token claim.
authorizationUrl Authorization url (used in swagger UI interface)
tokenUrl Token url (used in swagger UI interface), optional, if not defined will be constructed based on authorizationUrl
scopes Requested openId scopes (used as parameters for authorization url)

Example:
in dataspaces.private.json:

{
    "auth": {
        "enabled":true,
        "authority": "https://keycloak.siscc.org/auth/realms/OECD",
        "clientId": "app",
        "requireHttps": true,
        "validateIssuer": true,
        "claimsMapping": {
            "email": "email",
            "groups": "groups"
        },
        "authorizationUrl": "https://keycloak.siscc.org/auth/realms/OECD/protocol/openid-connect/auth",
        "tokenUrl": "https://keycloak.siscc.org/auth/realms/OECD/protocol/openid-connect/token",
        "scopes": [ "openid", "profile", "email" ]        
    }
}

Note: See the above linked transfer service documentation about authorisation token claims mapping. This is required in a scenario when the user’s email address/groups not set as default claim keys in JWT token configuration contains a claims mapper.

Authorisation Management web service

The complete documentation for the authorisation management web service openid-connect authentication configuration can be found here.

The authentication is configured in a xxxxx.json config file with the auth object.

auth settingg Description
enabled Is openid authentication enabled
authority Authority url of token issuer
clientId Client/application Id
requireHttps Is HTTPS connection to OpenId authority server required
validateIssuer Is iss (issuer) claim in JWT token should match configured authority
claimsMapping Key/value mapping of a key used in the C# code to JWT token claim.
authorizationUrl Authorization url (used in swagger UI interface)
tokenUrl Token url (used in swagger UI interface), optional, if not defined will be constructed based on authorizationUrl
scopes Requested openId scopes (used as parameters for authorization url)

Example:
in xxxxx.json:

{
    "auth": {
        "enabled":true,
        "authority": "https://keycloak.siscc.org/auth/realms/OECD",
        "clientId": "app",
        "requireHttps": true,
        "validateIssuer": true,
        "claimsMapping": {
            "email": "email",
            "groups": "groups"
        },
        "authorizationUrl": "https://keycloak.siscc.org/auth/realms/OECD/protocol/openid-connect/auth",
        "tokenUrl": "https://keycloak.siscc.org/auth/realms/OECD/protocol/openid-connect/token",
        "scopes": [ "openid", "profile", "email" ]        
    }
}

Note: See the above linked authorisation management service documentation about authorisation token claims mapping. This is required in a scenario when the user’s email address/groups not set as default claim keys in JWT token configuration contains a claims mapper.