discover

Quickly validate tokens and display essential information without full decoding.

Synopsis

  entra-auth-cli discover [flags]

Description

The discover command provides a fast way to validate token format and get basic information about tokens without performing full JWT decoding. It’s useful for quick checks and validation in scripts.

This command is lighter than inspect and focuses on:

Token format validation
Basic validity checks
Quick metadata extraction
Fast status reporting

Flags

Input Options

`--profile`, `-p`

Check token from a profile.

  entra-auth-cli discover --profile production
entra-auth-cli discover -p dev

`--token`, `-t`

Check a specific token string.

  entra-auth-cli discover --token "eyJ0eXAiOiJKV1QiLCJh..."

`--file`, `-f`

Read token from a file.

  entra-auth-cli discover --file token.txt

Output Options

`--output`, `-o`

Output format.

  entra-auth-cli discover --output json
entra-auth-cli discover -o yaml

Options:

text - Human-readable text (default)
json - JSON format
yaml - YAML format

`--quiet`, `-q`

Only output validation result (exit code only).

  if entra-auth-cli discover --profile myapp --quiet; then
    echo "Token is valid"
fi

Examples

Basic Usage

  # Check token from profile
entra-auth-cli discover --profile myapp

# Check specific token
entra-auth-cli discover --token "eyJ0eXAiOiJKV1Qi..."

# Check token from file
entra-auth-cli discover --file access_token.txt

# Check token from stdin
entra-auth-cli get-token | entra-auth-cli discover

Output Formats

  # Text output (default)
entra-auth-cli discover --profile myapp

# JSON output
entra-auth-cli discover --profile myapp --output json

# Quiet mode (exit code only)
entra-auth-cli discover --profile myapp --quiet
echo $?  # 0 = valid, 1 = invalid

Script Usage

  # Quick validation check
if entra-auth-cli discover --profile production --quiet; then
    echo "Token valid, proceeding..."
    ./deploy.sh
else
    echo "Token invalid, refreshing..."
    entra-auth-cli refresh --profile production
fi

# Check before API call
validate_token() {
    local profile="$1"
    if ! entra-auth-cli discover --profile "$profile" --quiet 2>/dev/null; then
        echo "Invalid token for $profile" >&2
        return 1
    fi
    return 0
}

# Usage
validate_token production && api_call

Output

Text Format (Default)

  Token Status: Valid
Format: JWT
Type: Bearer
Expires: 2025-12-28 15:30:00 UTC
Remaining: 42 minutes
Profile: production

JSON Format

  {
  "valid": true,
  "format": "JWT",
  "type": "Bearer",
  "expires_at": "2025-12-28T15:30:00Z",
  "expires_in": 2520,
  "expired": false,
  "profile": "production"
}

YAML Format

  valid: true
format: JWT
type: Bearer
expires_at: 2025-12-28T15:30:00Z
expires_in: 2520
expired: false
profile: production

Quiet Mode

No output, only exit code:

0 = Token is valid
1 = Token is invalid or expired

Validation Checks

The discover command validates:

Format: Token is a valid JWT structure (three base64 parts)
Expiration: Token has not expired
Structure: Token can be parsed
Type: Token is a Bearer token

Not validated:

Signature (no cryptographic verification)
Issuer
Audience
Claims content

Use Cases

Pre-Flight Validation

  #!/bin/bash

# Validate before expensive operation
if ! entra-auth-cli discover --profile prod --quiet; then
    echo "Getting fresh token..."
    entra-auth-cli get-token --profile prod --force
fi

# Proceed with validated token
TOKEN=$(entra-auth-cli get-token --profile prod --silent)
./expensive-operation.sh "$TOKEN"

Health Check Script

  #!/bin/bash

profiles=("production" "staging" "development")

echo "Token Health Check"
echo "===================="

for profile in "${profiles[@]}"; do
    if entra-auth-cli discover --profile "$profile" --quiet 2>/dev/null; then
        status="✓ Valid"
        expiry=$(entra-auth-cli discover --profile "$profile" --output json | jq -r .expires_at)
    else
        status="✗ Invalid"
        expiry="N/A"
    fi
    
    printf "%-15s %s (expires: %s)\n" "$profile" "$status" "$expiry"
done

Monitoring Integration

  #!/bin/bash

# Prometheus metrics format
check_token_validity() {
    local profile="$1"
    
    if output=$(entra-auth-cli discover --profile "$profile" --output json 2>/dev/null); then
        local expires_in=$(echo "$output" | jq -r .expires_in)
        local expired=$(echo "$output" | jq -r .expired)
        
        echo "token_valid{profile=\"$profile\"} 1"
        echo "token_expires_in_seconds{profile=\"$profile\"} $expires_in"
        echo "token_expired{profile=\"$profile\"} $([[ "$expired" == "true" ]] && echo 1 || echo 0)"
    else
        echo "token_valid{profile=\"$profile\"} 0"
    fi
}

# Export metrics
for profile in production staging dev; do
    check_token_validity "$profile"
done

CI/CD Pipeline Check

  #!/bin/bash
set -euo pipefail

echo "Validating authentication tokens..."

profiles=("cicd-deploy" "cicd-test" "cicd-prod")
failed=0

for profile in "${profiles[@]}"; do
    if entra-auth-cli discover --profile "$profile" --quiet; then
        echo "✓ $profile: Valid"
    else
        echo "✗ $profile: Invalid or expired"
        failed=1
    fi
done

if [ $failed -eq 1 ]; then
    echo "Some tokens are invalid. Please re-authenticate."
    exit 1
fi

echo "All tokens valid. Proceeding with deployment."

Quick Expiration Check

  # Get time until expiration
get_ttl() {
    local profile="$1"
    local ttl=$(entra-auth-cli discover --profile "$profile" --output json 2>/dev/null | jq -r .expires_in)
    
    if [ "$ttl" != "null" ] && [ -n "$ttl" ]; then
        echo "$ttl"
        return 0
    else
        return 1
    fi
}

# Usage
if ttl=$(get_ttl production); then
    echo "Token expires in $ttl seconds"
    
    if [ $ttl -lt 300 ]; then
        echo "Token expiring soon, refreshing..."
        entra-auth-cli refresh --profile production
    fi
fi

Comparison with inspect

Feature	discover	inspect
Speed	Fast	Slower
Output	Basic info	Full token details
Claims	Not shown	All claims shown
Use Case	Quick validation	Debugging
Exit Code	Validity status	Always 0 (unless error)

Use discover for:

Quick validation checks
Script conditionals
Monitoring/health checks
Fast status reporting

Use inspect for:

Debugging authentication issues
Viewing all token claims
Detailed token analysis

Exit Codes

Code	Description
0	Token is valid
1	Token is invalid or expired
2	Profile not found
3	No token available
4	Invalid token format

Performance

discover is optimized for speed:

  # Benchmark comparison
time entra-auth-cli discover --profile prod --quiet
# ~10ms

time entra-auth-cli inspect --profile prod > /dev/null
# ~50ms

# In tight loops, discover is significantly faster
for i in {1..100}; do
    entra-auth-cli discover --profile prod --quiet
done
# ~1 second

for i in {1..100}; do
    entra-auth-cli inspect --profile prod > /dev/null
done
# ~5 seconds

Error Handling

  #!/bin/bash

discover_token() {
    local profile="$1"
    local max_retries=3
    local attempt=0
    
    while [ $attempt -lt $max_retries ]; do
        if entra-auth-cli discover --profile "$profile" --quiet 2>/dev/null; then
            return 0
        fi
        
        attempt=$((attempt + 1))
        if [ $attempt -lt $max_retries ]; then
            echo "Token invalid, attempt $attempt of $max_retries" >&2
            entra-auth-cli refresh --profile "$profile" 2>/dev/null || entra-auth-cli get-token --profile "$profile" --force
            sleep 2
        fi
    done
    
    return 1
}

# Usage
if discover_token production; then
    echo "Token ready"
else
    echo "Failed to get valid token"
    exit 1
fi

Automation Examples

Cron Job Validation

  #!/bin/bash
# /etc/cron.hourly/check-tokens

PROFILES=("app1" "app2" "app3")
LOG_FILE="/var/log/token-check.log"

{
    echo "=== Token Check: $(date) ==="
    
    for profile in "${PROFILES[@]}"; do
        if entra-auth-cli discover --profile "$profile" --quiet; then
            echo "$profile: OK"
        else
            echo "$profile: INVALID - Attempting refresh"
            if entra-auth-cli refresh --profile "$profile" 2>&1; then
                echo "$profile: Refreshed successfully"
            else
                echo "$profile: FAILED to refresh - Manual intervention needed"
            fi
        fi
    done
    
    echo ""
} >> "$LOG_FILE"

Docker Healthcheck

  FROM ubuntu:22.04

# Install entra-auth-cli
RUN curl -L https://github.com/garrardkitchen/entra-token-cli/releases/latest/download/entra-auth-cli-linux-amd64 \
    -o /usr/local/bin/entra-auth-cli && chmod +x /usr/local/bin/entra-auth-cli

# Healthcheck using discover
HEALTHCHECK --interval=60s --timeout=10s --start-period=30s --retries=3 \
    CMD entra-auth-cli discover --profile app --quiet || exit 1

CMD ["/app/start.sh"]

Kubernetes Liveness Probe

  apiVersion: v1
kind: Pod
metadata:
  name: app-with-token-check
spec:
  containers:
  - name: app
    image: myapp:latest
    livenessProbe:
      exec:
        command:
        - /usr/local/bin/entra-auth-cli
        - discover
        - --profile
        - k8s-app
        - --quiet
      initialDelaySeconds: 30
      periodSeconds: 60
      timeoutSeconds: 10
      failureThreshold: 3

Tips

Combine with Other Commands

  # Discover + get-token (with automatic refresh)
if ! entra-auth-cli discover --profile prod --quiet; then
    entra-auth-cli get-token --profile prod --force
fi

# Discover + inspect (conditional detailed check)
if ! entra-auth-cli discover --profile prod --quiet; then
    echo "Token invalid. Details:"
    entra-auth-cli inspect --profile prod
fi

# Pipeline: discover → refresh → use
entra-auth-cli discover --profile prod --quiet || entra-auth-cli refresh --profile prod
TOKEN=$(entra-auth-cli get-token --profile prod --silent)

Batch Checking

  # Check all profiles
for profile in $(entra-auth-cli config list); do
    if entra-auth-cli discover --profile "$profile" --quiet; then
        echo "✓ $profile"
    else
        echo "✗ $profile"
    fi
done

JSON Processing

  # Extract specific fields
EXPIRES_IN=$(entra-auth-cli discover --profile prod --output json | jq -r .expires_in)
EXPIRED=$(entra-auth-cli discover --profile prod --output json | jq -r .expired)

# Conditional logic based on fields
if [ "$(entra-auth-cli discover --profile prod --output json | jq -r .expired)" == "true" ]; then
    entra-auth-cli refresh --profile prod
fi

discover

discover link

Synopsis link

Description link

Flags link

Input Options link

--profile, -p link

--token, -t link

--file, -f link

Output Options link

--output, -o link

--quiet, -q link

Examples link

Basic Usage link

Output Formats link

Script Usage link

Output link

Text Format (Default) link

JSON Format link

YAML Format link

Quiet Mode link

Validation Checks link

Use Cases link

Pre-Flight Validation link

Health Check Script link

Monitoring Integration link

CI/CD Pipeline Check link

Quick Expiration Check link

Comparison with inspect link

Exit Codes link

Performance link

Error Handling link

Automation Examples link

Cron Job Validation link

Docker Healthcheck link

Kubernetes Liveness Probe link

Tips link

Combine with Other Commands link

Batch Checking link

JSON Processing link

See Also link

discover

Synopsis

Description

Flags

Input Options

`--profile`, `-p`

`--token`, `-t`

`--file`, `-f`

Output Options

`--output`, `-o`

`--quiet`, `-q`

Examples

Basic Usage

Output Formats

Script Usage

Output

Text Format (Default)

JSON Format

YAML Format

Quiet Mode

Validation Checks

Use Cases

Pre-Flight Validation

Health Check Script

Monitoring Integration

CI/CD Pipeline Check

Quick Expiration Check

Comparison with inspect

Exit Codes

Performance

Error Handling

Automation Examples

Cron Job Validation

Docker Healthcheck

Kubernetes Liveness Probe

Tips

Combine with Other Commands

Batch Checking

JSON Processing

See Also