OAuth 2.0 Integration

This page discusses Stardog’s support for OAuth 2.0 JWT Tokens as a means for authenticating users.

Page Contents

1. Overview
2. Configuring Token Auth
   1. Example
3. Usage
4. User Management

---

Overview

Stardog can use OAuth 2.0 JWT Tokens for authentication. While Stardog can validate tokens it has no means to fetch a new token from an Identity Provider (IDP) this is normally done by a web application or authentication proxy. This document describes the configuration changes that are needed to allow Stardog to issue JWT Tokens for users and optionally trust tokens issued by a given IDP.

Stardog expects this Token to be in the Authorization HTTP header with the format bearer <token>.

Configuring Token Auth

By default, starting in version 7.8.0, Stardog is configured to issue authentication tokens. In order to provide customization and to increase the security of authentication token by providing secrets you will need to include the following property in stardog.properties:

The jwt.conf property must point to a valid YAML file with the following schema:

confVersion: string # The version of the configuration file currently `1.0`
deploymentName: string # (optional) Name for this deployment

# Singer is required. This allows Stardog to issue tokens to be used instead of Basic Auth.
signer:
  algorithm: [ HS256 | HS384 | HS512 | RS256 | RS384 | RS512 ] # Algorithm type to sign with.
  audience: string # (optional) audience to include as `aud` field, default "stardog"
  issuer: string # This is the name of the local issuer and will be automatically added to `issuers`
  secret: string # (Required for HMAC only) secret key used to sign tokens.
  publicKey: string # (Required for RSA only) Absolute path to an RSA public key.
  privateKey: string # (Required for RSA only) Absolute path to an RSA private key.
  tokenTTL: string # (optional) ISO-8601 duration format https://en.wikipedia.org/wiki/ISO_8601, default "P7D"

# Issuers are optional and there should be an entry for each issuer that is trusted.
issuers:
  [ url ]: # The URL of the IDP to trust should match the `iss` field. Example `https://url-of-idp-to-trust`
    audience: string # (required) limit trust to tokens issued for this audience in the `aud` field.
    usernameField: string  # (optional) the field to use as the username, defaults to `sub` field.
    # algorithms object is optional by default Stardog will use the url of the issuer to query the
    # issuers public key information at the address `<issuer url>/.well-known/jwks.json`.
    algorithms:
      [ HS256 | HS384 | HS512 ]: # Valid HMAC encryption types, see the `signer` fields
        secret: string # (required) secret key used to sign tokens.
      [ RS256 | RS384 | RS512 ]: # Valid RSA encryption types
        # either keyUrl or publicKey must be provided but not both
        keyUrl: string # URL to fetch jwks signing information from.
        publicKey: string # Absolute path to an RSA public key.
        privateKey: string # Absolute path to an RSA private key.

Example

Here’s an example stardog.properties file:

jwt.conf = /var/opt/stardog/jwt.yaml

This properties file points to a valid YAML file specified by the jwt.conf property. Here is an example:

---
confVersion: "1.0"
deploymentName: stardog-server

# This allows Stardog to issue a token for authentication against itself.
signer:
  algorithm: HS256
  audience: my-stardog
  secret: "this-should-be-randomly-generated-secret-key"
  issuer: http://my-domain.com
  tokenTTL: "P30D"

issuers:
  # An example of Azure auth that requires a special `keyUrl`
  https://login.microsoftonline.com/<azure-tenant-id>/v2.0:
    usernameField: email
    audience: <azure-tenant-id>
    algorithms:
      RS256:
        keyUrl: https://login.microsoftonline.com/<azure-tenant-id>/discovery/v2.0/keys

  # An example using apps.stardog.com
  https://apps.stardog.com:
    usernameField: username
    audience: https://fqdn.of.stardog:5820

  # An example of an IDP that supports the '.well-known' urls
  https://my-domain.auth0.com/:
    audience: <auth0-client-id>
    usernameField: email

Usage

Stardog will issue a token if you provide a valid username and password with basic auth.

$ curl -u anonymous:anonymous https://express.stardog.cloud:5820/admin/token
{"token": "..."}

Once you have obtained a valid token you can call a properly configured Stardog via the HTTP API:

$ export BEARER_TOKEN=<insert valid token here>
$ curl -H "Authorization: bearer ${BEARER_TOKEN}" https://express.stardog.cloud:5820/admin/users
{"users": ["anonymous"]}

User Management

All users who wish to connection via an external IDP OAuth Token must exist in the Stardog User system. The username should match what is being returned in the usernameField setting for the Issuer. See Managing Users and Roles for more information.

---