Custom Token Validation API

This document outlines the requirements for implementing a custom token validation endpoint that integrates with Miri's authentication system.

Overview

The custom token validation endpoint is used to validate authentication tokens and retrieve user information. This endpoint must be implemented by companies wishing to integrate their authentication system with Miri.

Endpoint Requirements

• Protocol: HTTPS (required for security)
• Method: POST
• Timeout: Must respond within 10 seconds

Request Format

Basic Token Validation

{
"token": "string" // The token to be validated
}


Token Validation with Authorization Request

{
"token": "string", // The token to be validated
"authorization_request": {
"entries": [
{
"external_uid": "string" // External user ID only
}
]
}
}


Important: The authorization request only includes external_uid values. The system will set default permissions and expiration times internally. Your endpoint should only validate that the authenticated user has permission to grant access to these external user IDs.

Response Format

Basic Response

{
"sub": "string", // Required: The external user ID
// Additional fields can be included in the response
}


Response with Validated Authorization Request

{
"sub": "string", // Required: The external user ID
"authorization_request": {
"entries": [
{
"external_uid": "string" // Validated external user ID only
}
]
}
// Additional fields can be included in the response
}


Response Requirements

1. Must return HTTP 200 status code for valid tokens
2. Response must be valid JSON
3. The sub field is mandatory and must contain the external user ID
4. If an authorization request was sent, the endpoint should validate and return the validated authorization request with only external_uid values
5. Any other fields in the response will be included in the token data

Authorization Request Validation

What to Validate

When an authorization request is included in the token validation request, your endpoint should:

1. Verify User Permissions: Ensure the authenticated user has permission to grant access to the requested external users
2. Validate External UIDs: Verify that the external user IDs are valid and accessible to the authenticated user
3. Audit the Request: Log all authorization requests for security and compliance purposes

Security Considerations

• Never trust client-provided authorization data without validation
• Implement proper access controls to prevent privilege escalation
• Validate external user IDs against your user database
• Check permission boundaries to ensure users can only grant access to users they have permission to manage

Error Handling

• Return appropriate HTTP status codes for different error scenarios:
• 400: Invalid request format
• 401: Invalid token
• 403: Token expired, insufficient permissions, or authorization validation failed
• 500: Internal server error

Example Valid Response

{
"sub": "user123",
"email": "user@example.com",
"name": "John Doe"
}


Example Response with Authorization Validation

{
"sub": "admin456",
"email": "admin@company.com",
"name": "Admin User",
"authorization_request": {
"entries": [
{
"external_uid": "user123"
}
]
}
}


Example Error Response

{
"error": "Invalid token",
"message": "Token has expired"
}


Example Authorization Validation Error

{
"error": "Authorization validation failed",
"message": "User does not have permission to grant access to external_uid: user789"
}


SDK Integration

When using the miri-react-native-sdk with custom token validation:

• Set provider: "custom" in your MiriAuth configuration
• The SDK will automatically use your custom endpoint for token validation
• Include authorization_request in your config for secure authorization processing

Implementation Example

Python Flask Example

from flask import Flask, request, jsonify
from datetime import datetime, timedelta

app = Flask(__name__)

@app.route('/validate', methods=['POST'])
def validate_token():
data = request.get_json()
token = data.get('token')
authorization_request = data.get('authorization_request')

# Validate the token (your existing logic)
if not is_valid_token(token):
return jsonify({"error": "Invalid token"}), 401

# Extract user info from token
user_info = extract_user_from_token(token)

# Validate authorization request if present
if authorization_request:
try:
validated_auth = validate_authorization_request(user_info, authorization_request)
except ValueError as e:
return jsonify({"error": "Authorization validation failed", "message": str(e)}), 403

return jsonify({
"sub": user_info['user_id'],
"email": user_info['email'],
"name": user_info['name'],
"authorization_request": validated_auth
})

# Basic response without authorization
return jsonify({
"sub": user_info['user_id'],
"email": user_info['email'],
"name": user_info['name']
})

def validate_authorization_request(user_info, auth_request):
"""Validate the authorization request against user permissions."""
# Check if user has permission to grant access
if not has_authorization_permission(user_info):
raise ValueError("User does not have authorization permission")

# Validate each entry
for entry in auth_request['entries']:
external_uid = entry['external_uid']

# Check if user can access this external user
if not can_access_external_user(user_info, external_uid):
raise ValueError(f"User cannot access external_uid: {external_uid}")

# Return validated authorization request with only external_uid values
return {
"entries": [
{"external_uid": entry["external_uid"]}
for entry in auth_request['entries']
]
}


Security Requirements

1. Endpoint must be served over HTTPS
2. Implement appropriate rate limiting
3. Consider implementing request validation
4. Ensure proper authentication/authorization mechanisms are in place
5. Implement authorization request validation to prevent privilege escalation
6. Log all authorization requests for audit purposes
7. Validate that users can only grant access to users they have permission to manage