External Auth Provider Integration

Integrating Tasker’s API security with external identity providers via JWKS endpoints.

See also: Auth Documentation Hub for architecture overview, Configuration for full TOML reference.

JWKS Integration

Tasker supports JWKS (JSON Web Key Set) for dynamic public key discovery. This enables key rotation without redeploying Tasker.

Configuration

[auth]
enabled = true
jwt_verification_method = "jwks"
jwks_url = "https://your-provider.com/.well-known/jwks.json"
jwks_refresh_interval_seconds = 3600
jwt_issuer = "https://your-provider.com/"
jwt_audience = "tasker-api"
permissions_claim = "permissions"  # or custom claim name

How It Works

On first request, Tasker fetches the JWKS from the configured URL
Keys are cached for the configured refresh interval
When a token has an unknown kid (Key ID), a refresh is triggered
RSA keys are parsed from the JWK n and e components

Auth0

Auth0 Configuration

Create an API in Auth0 Dashboard:
- Name: Tasker API
- Identifier: tasker-api (this becomes the audience)
- Signing Algorithm: RS256
Create permissions in the API settings matching Tasker’s vocabulary:
- tasks:create, tasks:read, tasks:list, etc.
Assign permissions to users/applications via Auth0 roles

Tasker Configuration for Auth0

[auth]
enabled = true
jwt_verification_method = "jwks"
jwks_url = "https://YOUR_DOMAIN.auth0.com/.well-known/jwks.json"
jwks_refresh_interval_seconds = 3600
jwt_issuer = "https://YOUR_DOMAIN.auth0.com/"
jwt_audience = "tasker-api"
permissions_claim = "permissions"

Token Request

curl --request POST \
  --url https://YOUR_DOMAIN.auth0.com/oauth/token \
  --header 'content-type: application/json' \
  --data '{
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "audience": "tasker-api",
    "grant_type": "client_credentials"
  }'

Keycloak

Keycloak Configuration

Create a realm and client for Tasker
Define client roles matching Tasker permissions
Configure the client to include roles in the permissions token claim via a protocol mapper

Tasker Configuration for Keycloak

[auth]
enabled = true
jwt_verification_method = "jwks"
jwks_url = "https://keycloak.example.com/realms/YOUR_REALM/protocol/openid-connect/certs"
jwks_refresh_interval_seconds = 3600
jwt_issuer = "https://keycloak.example.com/realms/YOUR_REALM"
jwt_audience = "tasker-api"
permissions_claim = "permissions"  # Configure via protocol mapper

Okta

Okta Configuration

Create an API authorization server
Add custom claims for permissions
Define scopes matching Tasker permissions

Tasker Configuration for Okta

[auth]
enabled = true
jwt_verification_method = "jwks"
jwks_url = "https://YOUR_DOMAIN.okta.com/oauth2/YOUR_AUTH_SERVER_ID/v1/keys"
jwks_refresh_interval_seconds = 3600
jwt_issuer = "https://YOUR_DOMAIN.okta.com/oauth2/YOUR_AUTH_SERVER_ID"
jwt_audience = "tasker-api"
permissions_claim = "scp"  # Okta uses "scp" for scopes by default

Custom JWKS Endpoint

Any provider that serves a standard JWKS endpoint works. The endpoint must return:

{
  "keys": [
    {
      "kty": "RSA",
      "kid": "key-id-1",
      "use": "sig",
      "alg": "RS256",
      "n": "<base64url-encoded modulus>",
      "e": "<base64url-encoded exponent>"
    }
  ]
}

Static Public Key (Development)

For development or simple deployments without a JWKS endpoint:

[auth]
enabled = true
jwt_verification_method = "public_key"
jwt_public_key_path = "/etc/tasker/keys/jwt-public-key.pem"
jwt_issuer = "tasker-core"
jwt_audience = "tasker-api"

Generate keys with:

tasker-ctl auth generate-keys --output-dir /etc/tasker/keys

Permission Claim Mapping

If your identity provider uses a different claim name for permissions:

permissions_claim = "custom_permissions"  # Default: "permissions"

The claim must be a JSON array of strings:

{
  "custom_permissions": ["tasks:create", "tasks:read"]
}

When strict_validation = true (default), tokens containing unknown permission strings are rejected. Set to false if your provider includes additional scopes/permissions not in Tasker’s vocabulary:

strict_validation = false
log_unknown_permissions = true  # Still log unknown permissions for monitoring

Tasker Documentation