Authentication and Authorization¶

OPCTL Installation¶

docker pull ontotext/opctl

docker run -it ontotext/opctl --help

OPCTL Configuration¶

This is a minimal opctl.yaml configuration example for provisioning Ontotext Semantic Services FusionAuth (identity and authentication).

Provisioning of users and roles can also be achieved by including them in the YAML configuration:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51

platform:
  fusion:
    address: 'http://fusionauth:9011'
    provision: true
  kong:
    provision: false
security:
  # JSON web tokens (HMAC only)
  jwt:
    secret: 78zabV4MFtspweovcC5D1dirQ5rnju67GJlSqGyuTAI=
    # In seconds (Default: 5 minutes)
    token-ttl: 1200
  # Fusion Auth specific options
  fusion:
    tenant:
      uuid: 340ba0db-90f5-4a7e-9cb5-7e26670f1717
    # The platform application
    application:
      # This is an UUID that can be provided to authentication requests to the login API
      uuid: 0afceebe-cfc6-4ddf-81b9-a7fd658b30d4
      oauth:
        clientSecret: Q0xyxiI1fN1w-Q1yj6nbLpaa-uzWFTxDXapGKGEIKB4
        redirect_urls:
          # OTP Workbench
          - 'http://localhost:8000/workbench/'
  roles:
    - name: ReadOnly
      superRole: false
      default: false
    - name: WriteOnly
      superRole: false
      default: false
    - name: DeleteOnly
      superRole: false
      default: false
  users:
    - username: ReadOnlyUser
      email: ReadOnlyUser@example.com
      password: 1234567890
      roles:
        - ReadOnly
    - username: WriteOnlyUser
      email: WriteOnlyUser@example.com
      password: 1234567890
      roles:
        - WriteOnly
    - username: DeleteOnlyUser
      email: DeleteOnlyUser@example.com
      password: 1234567890
      roles:
        - DeleteOnly

Login API¶

FusionAuth exposes a REST endpoint /api/login that produces JWT access and refresh tokens when the login data in the request body is correct.

Example request body:

{
  "loginId": "admin@example.com",
  "password": "admin123",
  "applicationId": "10000000-0000-0002-0000-000000000001"
}

A request header X-FusionAuth-TenantId is also expected during the login request.

This type of login is suitable for use by other applications and services or by custom login forms.

See FusionAuth Login API for more information.

OAuth and Login Forms¶

This type of login is suitable when securing existing applications without having to implement custom logging forms. The implementation requirement is to handle the session, keep it in a cookie or in the local storage, and redirect to FusionAuth’s login when needed.

Example implicit flow:

1. Upon loading, the application checks the presence of an access token in the URL or in the local storage.
2. If present, it uses it as Authorization header.
3. If not present, it performs a redirection to FusionAuth’s logging form.
4. If the user credentials are correct, FusionAuth redirects back to the application with an access token in the URL.

Example redirect URL to FusionAuth:

http://example.com:9011/oauth2/authorize?client_id=<client-id>&redirect_uri=<redirect-uri>&response_type=token&tenantId=<tenant-id>

Where:

• tenantId is the tenant ID
• client_id is the application ID in which we are logging
• redirect_url is the URL to which FusionAuth will redirect upon successful authentication

See FusionAuth OAuth for more information about OAuth in FusionAuth.

See FusionAuth login authentication workflows for more details on the different kinds of authentication flows.

Semantic Services Gateway¶

The Ontotext Semantic Services Kong API gateway must only authorize HTTP requests that include a valid JWT token. When security is enabled, only those requests that include a valid Authorization: Bearer {JWT} token header (signed with the configured signing key) are granted access. All other requests will be unauthorized.

See the Semantic Services Gateway documentation for more information about configuring and deploying Kong.

consumers:
  - username: ontotext-platform-consumer
    custom_id: ontotext-platform-consumer

jwt_secrets:
  - consumer: ontotext-platform-consumer
    key: "localhost"
    secret: "XXXXXXXXX"
    algorithm: HS256

plugins:
  - name: jwt
    service: semantic-objects
    config:
      claims_to_verify: ["exp"]
      key_claim_name: iss

services:
  - name: semantic-objects

Semantic Objects RBAC¶

Semantic Objects¶

RBACs can be enabled and disabled.

One configuration property controls if RBACs are turned on or off:

• security.enabled to true or false

Another sets the JWT signing key that will be used to decode ‘Authorization: Bearer {JWT TOKEN}’ HTTP headers into role and username claims.

• security.secret to the Semantic Services JWT signing key (FusionAuth and Kong)

Configuration can be applied by updating the Semantic Objects application.properties file. It can be provided to the Semantic Objects by using an environment variable.

Once the Semantic Objects are running with security enabled, all requests must include an Authorization HTTP header that includes a JWT token provided by the authentication flow.

The header should look like this:

"Authorization": "Bearer token"

Ontotext Semantic Services Workbench¶

The Semantic Services Workbench is secured using an authorization code grant flow with JWTs and refresh tokens.

It manages JWT access and refresh tokens in the local storage under the workbench_access_token and workbench_refresh_token keys.

GraphDB¶

GraphDB is secured separately from the rest of the Ontotext Semantic Services.

You can find instructions for securing GraphDB in its user documentation.

GraphDB repositories that are secured with a username and password can be easily accessed by the service. This is done by setting two configuration parameters. The combination of username and password will then be sent to the SPARQL endpoint as part of an authentication header.

sparql.endpoint.username: "username"
sparql.endpoint.credentials: "password"

This approach has been tested to work with RDF4J endpoints.

Docker Containers¶

This docker-compose.yaml configuration starts FusionAuth and Kong to enable authentication, authorization, and RBACs.

This .env file customizes the container environment.

And this Kong declarative configuration specifies services, routes, and JWT validation.

To deploy the Docker Compose, use:

docker-compose up -d

Within about a minute, FusionAuth will be up and running behind the Kong API Gateway. You can access it on http://localhost:8000/admin.

You can also deploy the OPTCL CLI together with the security components to automate the provisioning instead of doing it manually.

Here are the minimal example opctl.yaml configuration and the example docker-compose-cli.yaml.

You can deploy the two compose files together by using the following shell command:

docker-compose -f docker-compose.yaml -f docker-compose-cli.yaml up -d

To stop and remove all services, use:

# Without removing persisted data
docker-compose down

# With removing persisted data
docker-compose down --volumes

# In case the provisioning was deployed as well
docker-compose -f docker-compose.yaml -f docker-compose-cli.yaml down --volumes

Fusion Auth¶

FusionAuth is an authentication and authorization provider. In the Ontotext Semantic Services, it is used for user management, OAuth authentication, and JWT token issuer.

You can find the official installation requirements and tutorial here.

Setup wizard¶

After installing FusionAuth, you are redirected to a setup wizard page where a system administrator for FusionAuth is created. This system administrator will be able to configure tenants, applications, roles, and users.

See the official documentation for a complete tutorial.

function populate(jwt, user, registration) {
   jwt.roles = registration.roles || [];
}

Tenant and application management¶

This is the main step in configuring security with FusionAuth.

Tenants are organizational units in which applications reside. FusionAuth by default has its own tenant and application after completing the setup wizard. However, for the purposes of the Ontotext Semantic Services, you need to create a new tenant and application.

Creating a Tenant¶

1. Go to System ‣ Tenants ‣ Create new tenant.

2. Insert the tenant name. The ID can also be specified but it should be a UUID.

3. In the General tab, select the issuer. This should be the domain where the Semantic Services are deployed.

4. In the JWT tab:

   • Specify the access and refresh token durations. Normally, the access token should be short-lived, e.g., 300 seconds.
   • For signing keys, select the key that was created earlier.

Examples:

• JWT tab

Creating an Application¶

1. Go to Applications and start creating a new one.

2. Enter the application name and select the tenant to which the application will belong. The ID can also be specified but it should be a UUID.

3. In the Roles tab, you can specify a default set of roles:

   • Create an admin super role
   • Create a user default role

4. In the OAuth tab:

   • Configure the authorized redirect URLs. This is mandatory, and only requests with the specified values will be allowed to log in.
   • Configure the enabled grants: Authorization Code, Implicit, and Refresh Token.

5. In the JWT tab:

   • Specify the access and refresh token durations. Normally, the access token should be short-lived, e.g., 300 seconds.
   • For signing keys, select the key that was created earlier.
   • Select the lambda that was created earlier to enable token decoration.

6. In the Security tab:

   • Deselect API key unless you plan to provide an API key with each request for authentication.
   • Allow refresh tokens.

Examples:

• Roles

• OAuth

• JWT

• Security

Information about creating an application can be found in the FusionAuth documentation.

Health Checks¶

The Ontotext Semantic Services have an aggregate health check that checks all deployed services for their health status.

The __health endpoint can be accessed at http://{soaas_host}:{soaas_port}/__health.

An example response is as follows:

{
  "status": "OK",
  "healthChecks": [
    {
      "status": "OK",
      "id": "1200",
      "name": "SPARQL checks",
      "type": "sparql",
      "impact": "SPARQL Endpoint operating normally, writable and populated with data.",
      "troubleshooting": "http://localhost:9995/__trouble",
      "description": "SPARQL Endpoint checks.",
      "message": "SPARQL Endpoint operating normally, writable and populated with data."
    },
    {
      "status": "OK",
      "id": "1300",
      "name": "SOML Checks",
      "type": "soml",
      "impact": "SOML bound, service operating normally.",
      "troubleshooting": "http://localhost:9995/__trouble",
      "description": "SOML checks.",
      "message": "SOML bound, service operating normally."
    },
    {
      "status": "OK",
      "id": "1350",
      "type": "soml-rbac",
      "impact": "Security is disabled. SOML RBAC healthcheck is inactive.",
      "troubleshooting": "http://localhost:9995/__trouble",
      "description": "SOML RBAC checks.",
      "message": "Security is disabled. SOML RBAC healthcheck is inactive."
    },
    {
      "status": "OK",
      "id": "1400",
      "name": "Query service",
      "type": "queryService",
      "impact": "Query service operating normally.",
      "troubleshooting": "http://localhost:9995/__trouble",
      "description": "Query service checks.",
      "message": "Query service operating normally."
    },
    {
      "status": "OK",
      "id": "1500",
      "name": "Mutations Service",
      "type": "mutationService",
      "impact": "Mutation Service operating normally.",
      "troubleshooting": "http://localhost:9995/__trouble",
      "description": "Mutation Service checks.",
      "message": "Mutation Service operating normally."
    }
  ]
}

Good to Go¶

The Ontotext Semantic Services have an aggregate good to go check that checks all configured services for good to go status.

The __gtg endpoint can be accessed at http://{soaashost}:{soaas_port}/__gtg.

An example response is as follows:

{
    "gtg": "OK"
}

Troubleshooting¶