Authentication

FoxNose CMS provides multiple authentication methods to securely access both the Manage API and the Delivery API. Understanding these methods and choosing the appropriate one for your use case is crucial for maintaining security and efficient access control.

Overview

In FoxNose CMS, authentication is secured through JWT tokens and asymmetric encryption with API keys, each serving distinct purposes.

JWT tokens are primarily for user-based authentication within the Manage API. Users authenticate directly using their credentials, receiving short-lived access tokens for routine interactions and refresh tokens for extended access. This method grants user-specific permissions, making it ideal for administrative tasks requiring comprehensive control.

API Key Authentication uses asymmetric encryption and allows external services to interact with both the Manage API and Delivery API. With each API key, a unique public-private key pair is generated. The private key, used only for signing requests, remains secure and is never shared, ensuring data integrity and authenticity. API keys are linked to specific roles with precise permissions, providing flexible, limited access suitable for service-based interactions.

Together, JWT tokens and API keys deliver a flexible, secure way to control access, adapting easily to both user-managed tasks and application-based interactions.

Key Points

• Manage API: Supports both User Authentication (Bearer) and API Key Authentication (Secure/Test).
• Delivery API: Supports only API Key Authentication (Secure/Test) method.

User Authentication (JWT)

Authenticates on behalf of a user using JSON Web Tokens. Suitable for administrative tasks requiring broader permissions. To authenticate as a user, you need to obtain an access token and a refresh token by providing your user credentials.

Properties

Obtaining JWT Tokens

curl https://api.foxnose.net/account/auth/ \
-H "Content-Type: application/json" \
-d '{
"email": "your-email@example.com",
"password": "your-password"
}'

{
    "refresh": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "access": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Refreshing JWT Tokens

curl https://api.foxnose.net/account/refresh-token/ \
-H "Content-Type: application/json" \
-d '{
"refresh": "your-refresh-token"
}'

{
    "access": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refresh": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Token Rotation

For security purposes, JWT tokens are rotated on each authentication. This means that each time you authenticate, you receive new access and refresh tokens. Ensure that you update stored tokens accordingly.

Code Examples

const axios = require('axios');

// Authenticate and obtain tokens
axios.post('https://api.foxnose.net/account/auth/', {
email: 'your-email@example.com',
password: 'your-password'

})
.then(response => {
const accessToken = response.data.access;
const refreshToken = response.data.refresh;

// Use the access token in your requests
const headers = {
Authorization: `Bearer ${accessToken}`,
'Content-Type': 'application/json',

};
// Make an authenticated request
axios.get('https://api.foxnose.net/account/', {headers})
.then(res => {
console.log(res.status);
console.log(res.data);
})
.catch(err => {
console.error(err.response.status);
console.error(err.response.data);
});

})
.catch(error => {
console.error (error.response.status);
console.error(error.response.data);
});

API Key Authentication

FoxNose CMS uses a secure system for accessing both the Manage API and the Delivery API through API keys, leveraging asymmetric encryption. This ensures a high level of security by keeping your private keys confidential and not storing them on our servers. API keys are generated either through the Environment interface of your project or via the Manage API if authenticated as a user with Environment Administrator role or higher

When you create a new key, you receive:

• Public Key: Used to identify your API key. Can be shared openly and is used to verify signatures.
• Private Key: Used to sign your requests. Must be kept secret and is used to create digital signatures.

Both keys are provided in Base64 encoding. The private key is displayed only once during creation. Ensure you store it securely, as it cannot be recovered later. You can assign a role to the API key. If you do not assign a role during creation, you can add or change it later.

How API Key Authentication Works

When making a request to the Manage API or Delivery API, you need to:

1. Prepare the Data to Sign:

• URI: The path of the request (e.g., /v1/7c9h4pwu/folders/).
• Body Hash: SHA-256 hash of the request body. If there’s no body, use the SHA-256 hash of an empty string ('').
• Timestamp: Current time in ISO 8601 format (e.g., 2024-10-26T20:58:45Z).

Concatenate these elements using a pipe (|) character:

data_to_sign = "<uri>|<body_hash>|<timestamp>"

2. Create the Signature:

• Use your private key to sign the data_to_sign string using ECDSA with SHA-256.

3. Set the Headers:

• Authorization: Include the authentication method (Secure), your public key, and the signature in Base64, separated by colons.

Authorization: Secure <public_key>:<signature>

• Date: Include the same timestamp used in data_to_sign.

Date: 2024-10-26T20:58:45Z

Code Examples

Important Notes

• Time Synchronization: Ensure that your system clock is accurate. If the timestamp in the Date header differs by more than 10 minutes from the server’s time, the request will be rejected.
• Timestamp Consistency: The timestamp used in the Date header must be the same as the one used in the signature.
• URI: Use the path of the request without the domain.
• Body Hash: Calculate the SHA-256 hash of the request body. If there is no body, use the SHA-256 hash of an empty string.

body_hash = hashlib.sha256(''.encode('utf-8')).hexdigest()

Test Authentication (Simplified)

For non-production environments, you can use a simplified authentication method.

How Test Authentication Works

In the Authorization header, include the authentication method (Test), your public key, and your private key, separated by colons.

Authorization: Test <public_key>:<private_key>

• No signature is required.
• The Date header is not required for test authentication.

const axios = require('axios');

// Your keys (Base64 encoded)
const publicKeyBase64 = 'YourPublicKeyBase64';
const privateKeyBase64 = 'YourPrivateKeyBase64';

// Request details
const uri = '/v1/7c9h4pwu/folders/';
const body = JSON.stringify({name: 'New Resource'});

// Prepare headers
const headers = {
Authorization: `Test ${publicKeyBase64}:${privateKeyBase64}`,
'Content-Type': 'application/json'
};

// Make request
axios
.post(`https://api.foxnose.net${uri}`, body, {headers})
.then((response) => {
console.log (response.status);
console.log(response.data);

})
.catch((error) => {
console.error (error.response.status);
console.error(error.response.data);
});

Warning: Use test authentication only for non-sensitive data in test environments.

Choosing the Right Authentication

Different authentication methods are suited for different purposes:

Security Considerations

When working with authentication methods in FoxNose CMS, consider the following security best practices:

• Private Keys: Store your private keys securely. Do not share them or expose them in code repositories.
• Tokens: Keep access and refresh tokens confidential. Do not log them or expose them to unauthorized parties.
• Always use HTTPS to ensure that your requests and credentials are encrypted during transmission.
• Ensure that your system clock is accurate to prevent authentication failures due to timestamp discrepancies.
• Be aware of token expiration times and refresh tokens as needed.
• Regularly rotate your API keys and tokens to minimize the risk of compromised credentials.
• Assign the minimal necessary permissions to API keys and users, following the principle of least privilege.
• Keep track of API usage and access logs to detect any unusual activity.