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 Stardog
   1. Example
3. Usage
4. User Management
   1. Role Mapping
      1. Mechanism 1: allowedGroupIdentifiers (and optionally rolesField)
      2. Mechanism 2: rolesClaimPath
5. OAuth 2.0 Identity Providers
   1. Azure Active Directory
      1. Configure Azure AD Application
      2. Azure Authentication and Token Creation
      3. Configure Stardog Server

---

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 the JWT identity token to be in the Authorization HTTP header with the format bearer <token>.

Configuring Stardog

By default, Stardog is configured to issue authentication tokens. In order to provide customization and to provide secrets to increase the security of authentication tokens, 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.

# Signer 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.
    autoCreateUsers: boolean # (optional) `true` will create new users in Stardog, defaults to `false`.
    allowedGroupIdentifiers: array # (optional) The groups that are allowed to be mapped to Stardog roles.
    rolesField: string # (optional) The name of the field containing the roles claim; used together with `allowedGroupIdentifiers`.
    rolesClaimPath: string # (optional) The path to the roles claim; used instead of `rolesField`/`allowedGroupIdentifiers`.
    # `algorithms` object is optional; by default, Stardog will use the url of the issuer to query the
    # issuer's 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.

The license uuid is used as part of the signing key; therefore, the same license must be used on every node in the cluster. If the license uuid is different on the nodes, the token will only work against the node that generated it.

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-client-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 connect via an external Identity Provider (IDP) OAuth Token should either already exist in the Stardog User system or have the autoCreateUsers property set to true. Existing usernames should match what is being returned in the usernameField setting for the Issuer.

When autoCreateUsers is set to true, Stardog will attempt to create a new user with the value of the usernameField claim. The token must also include at least one role for the user that already exists in Stardog. If a new user does not have an existing role specified, a Stardog user will not be created.

See Managing Users and Roles for more information.

Role Mapping

Stardog provides two mechanisms for specifying how it should read the roles claim embedded in a token issued by an IDP. The first method is to define the allowedGroupIdentifiers property (and optionally the rolesField property); the second method is to define the rolesClaimPath property.

If both the allowedGroupIdentifiers and rolesClaimPath properties are specified, then the rolesClaimPath is used, and the allowedGroupIdentifiers and rolesField properties are ignored.

Mechanism 1: allowedGroupIdentifiers (and optionally rolesField)

The rolesField property specifies the name of the roles claim in the token. If the rolesField property is not specified in the issuer definition, a default value of "stardogRoles" is used.

If the value associated with the rolesField claim is a string array, Stardog will look at each string in the array and include it in the set of requested Stardog roles (if that string is listed in the allowedGroupIdentifiers list).

If the value associated with the rolesField is a map, Stardog requires the keys in the map be strings and the value for each key be an array of strings. For each key (the group identifier) that is included in allowedGroupIdentifiers, Stardog includes the strings from its value array in the set of requested Stardog roles.

If no roles match any of the strings specified in the string arrays for each allowedGroupIdentifier, the associated user will not be assigned any permissions in Stardog.

In the following example, only the AD groups readers and writers will be allowed to match Stardog roles.

allowedGroupIdentifiers: [ readers,writers ]

Mechanism 2: rolesClaimPath

The rolesClaimPath property specifies a JSON path to the roles being claimed. This is based on the format Keycloak uses for specifying a claim it adds to a JWT:

Name of the claim to insert into the token. This can be a fully qualified name like address.street. In this case, a nested JSON object will be created. To prevent nesting and use dot literally, escape the dot with backslash. (See the Keycloak server admin documentation for more information.)

For example, setting rolesClaimPath=the.best.roles, Stardog expects a JWT from the IDP to look something like:

{
  "iss": "https://my.idp.server",
  "the": {
    "best": {
      "roles": [ "reader", "writer"]
    },
  },
  <more claims>
}

and Stardog would add reader and writer to the requested Stardog roles.

It is possible to embed a period (.) in the JSON path by escaping it with a backslash. For example, with rolesClaimPath=stardog\.com.great\.roles, Stardog would expect the JWT from the IDP to look something like:

{
  "iss": "https://my.idp.server",
  "stardog.com": {
    "great.roles": [ "reader", "writer"]
  },
  <more claims>
}

Similarly to the previous example, Stardog would add reader and writer to the requested Stardog roles.

Note that auto-created users cannot be assigned roles within Stardog, even by a superuser. Their roles will always be managed by the role mapping process described above. This is to ensure there is a single source for managing the roles of a user and that the administrators do not need to update multiple places to manage a user’s role.

OAuth 2.0 Identity Providers

Stardog supports OAuth 2.0 authentication using tokens from supported identity providers. This section provides information about configuring and using them.

Azure Active Directory

Stardog can use OAuth 2.0 JWT Tokens generated by Azure AD using OpenId to authenticate against existing users or optionally to create new users. There are several ways (known as flows) that can be used to obtain tokens. This documentation explains how to set up AD authentication using authorization code flow and configure role-based access using a token with roles.

You can find more information on Azure Active Directory and the Microsoft identity platform here.

Configure Azure AD Application

If you have an existing Azure application, you can skip these steps.

• In your Azure portal, go to Home->App Registrations and click New Registration to add a new application.
• Take note of the Application (client) ID and the Directory (tenant) ID.
• Add any necessary client credentials and generate a client secret.
• Add a redirect URL of localhost.
• Click endpoints and note the V2 authorization endpoint URL.
• From the portal, go to Home->Azure Active Directory->Enterprise Applications and confirm your application is there; add it if it is not.
• Click on your application and add your users with their desired application role. Create new roles as needed.

Azure Authentication and Token Creation

• Use your browser to navigate to the authorization endpoint URL that you noted above, filling in your tenant and client ids. Sign in using your application credentials.

https://login.microsoftonline.com/<tenant_id>/oauth2/v2.0/authorize?client_id=<client id>&response_type=id_token&scope=openid&nonce=<nonce value>&state=<state value>

• Capture the identity token that is returned in the redirect URL you specified while setting up your Azure application. The string value for URL parameter id_token is the token.

http://localhost/#id_token=<id token value>&session_state=01e749c6-459a-460b-a35e-42c5f122999d

Configure Stardog Server

This example JWT config expects to find existing Stardog usernames in the preferred_username token claim value.

confVersion: "1.0"
deploymentName: stardog-server

issuers:
  https://login.microsoftonline.com/<azure-tenant-id>/v2.0:
    audience: <azure-client-id>
    usernameField: preferred_username
    algorithms:
      RS256:
        keyUrl: https://login.microsoftonline.com/<azure-tenant-id>/discovery/v2.0/keys

Fill in <azure-tenant-id> and <azure-client-id> with the values noted from above. Restart Stardog and authenticate using the token, as instructed above.

---