Authentication

Datafi authenticates every request using JSON Web Tokens (JWT) issued by your identity provider. The platform integrates with industry-standard identity providers and enforces strict token validation, key rotation, and expiration policies.

Supported Identity Providers

Datafi supports the following identity providers out of the box. You configure your provider at the tenant level, and all users within that tenant authenticate through it.

Provider	Protocol	MFA Support	Directory Sync
Auth0	OIDC / OAuth 2.0	Yes	Yes
AWS Cognito	OIDC / OAuth 2.0	Yes	Via User Pools
Microsoft Entra ID	OIDC / OAuth 2.0	Yes	Yes

info

You can configure exactly one identity provider per tenant. If you need to support multiple IdPs, create separate tenants or use your IdP's federation capabilities to consolidate authentication.

JWT Token Lifecycle

Every authenticated session in Datafi revolves around a JWT access token and an optional refresh token.

Token Structure

Datafi expects JWTs with the following claims:

{
  "iss": "https://your-idp.example.com/",
  "sub": "user_abc123",
  "aud": "https://api.datafi.io",
  "exp": 1700000000,
  "iat": 1699990000,
  "tenant_id": "tenant_001",
  "roles": ["editor"],
  "email": "[email protected]"
}

Claim	Required	Description
iss	Yes	Token issuer URL, must match your IdP configuration
sub	Yes	Unique user identifier
aud	Yes	Audience, must include Datafi's API identifier
exp	Yes	Expiration timestamp (Unix epoch)
iat	Yes	Issued-at timestamp
tenant_id	Yes	The tenant this user belongs to
roles	No	RBAC roles assigned to the user
email	No	User's email address

Token Expiration

You can configure token expiration to balance security and user experience. Shorter expirations are more secure but require more frequent re-authentication.

Setting	Range	Default	Recommendation
Access token TTL	5 min -- 24 hr	1 hour	15--60 minutes for interactive users
Refresh token TTL	1 hr -- 30 days	7 days	1--7 days for standard applications
Absolute session limit	1 hr -- 30 days	30 days	Align with your organization's session policy

# Example tenant authentication configuration
authentication:
  provider: auth0
  domain: your-tenant.auth0.com
  client_id: abc123def456
  audience: https://api.datafi.io
  token_expiration:
    access_token_ttl: 3600      # 1 hour in seconds
    refresh_token_ttl: 604800   # 7 days in seconds
    absolute_session: 2592000   # 30 days in seconds

warning

Setting access token TTL beyond 1 hour increases the window of exposure if a token is compromised. For sensitive environments, keep it at 15 minutes or less and rely on refresh tokens.

JWKS Rotation

Datafi validates JWT signatures using JSON Web Key Sets (JWKS) published by your identity provider. The platform fetches keys on demand and caches them to minimize latency.

How Key Rotation Works

1. Your identity provider publishes a JWKS endpoint (e.g., https://your-idp.example.com/.well-known/jwks.json).
2. Datafi fetches the key set when it encounters a kid (Key ID) it has not seen before.
3. The new key is cached and used for subsequent validations.
4. Old keys remain cached until they are no longer referenced by incoming tokens.

Rotation Best Practices

• Rotate keys periodically. Most IdPs support automatic key rotation on a configurable schedule.
• Overlap keys during rotation. Publish the new key before revoking the old one to avoid invalidating in-flight tokens.
• Monitor JWKS fetch failures. If Datafi cannot reach your IdP's JWKS endpoint, new keys cannot be fetched, which will cause validation failures for tokens signed with unknown keys.

Configuring Your Identity Provider

Auth0

authentication:
  provider: auth0
  domain: your-tenant.auth0.com
  client_id: YOUR_CLIENT_ID
  audience: https://api.datafi.io

AWS Cognito

authentication:
  provider: cognito
  region: us-east-1
  user_pool_id: us-east-1_AbCdEfGhI
  client_id: YOUR_CLIENT_ID
  audience: https://api.datafi.io

Microsoft Entra ID

authentication:
  provider: entra
  tenant_id: YOUR_AZURE_TENANT_ID
  client_id: YOUR_CLIENT_ID
  audience: https://api.datafi.io

Token Validation Failures

When token validation fails, Datafi returns a 401 Unauthorized response. Common failure reasons:

Error Code	Cause	Resolution
TOKEN_EXPIRED	The access token has passed its exp claim	Use the refresh token to obtain a new access token
INVALID_SIGNATURE	The token signature does not match any key in the JWKS	Verify that the IdP and Datafi are configured with the same audience and issuer
MISSING_CLAIMS	A required claim (e.g., tenant_id) is missing	Update your IdP's token configuration to include required claims
INVALID_AUDIENCE	The aud claim does not match Datafi's expected audience	Check the audience setting in your authentication configuration
ISSUER_MISMATCH	The iss claim does not match the configured IdP	Verify the domain or issuer URL in your authentication configuration