🔐 Authentication & Authorization

Overview

AnkaSecure uses a robust authentication and authorization mechanism to ensure secure access to cryptographic operations and key management. This is achieved through JWT-based authentication, role-based access control (RBAC), and integration with external IAM providers.

The architecture supports integration with:

IBM API Connect
AWS Cognito
Other OAuth2 / OpenID Connect providers

🛡️ Authentication Flow

Authentication in AnkaSecure follows a token-based model, ensuring secure access control for both customer applications and the CLI.

1️⃣ Obtain an Access Token

To authenticate, applications and CLI clients must send a POST request to the authentication server:

cURL Example: Requesting a Token

curl -X 'POST' \
  'https://demo.ankatech.co/api/authenticate/app' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "clientId": "yourClientId",
  "clientSecret": "yourClientSecret"
}'

Example Response

{
  "token": "eyJhbGciOiJIUzI1NiJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiJ9..."
}

💡 Notes: ✔ The access token is a JWT that must be included in API requests.\ ✔ The refresh token allows obtaining a new access token when it expires.

2️⃣ Using the Access Token

Once authenticated, requests to the AnkaSecure API must include the token in the Authorization header:

Example: Encrypting Data with a Token

curl -X 'POST'\
  'https://demo.ankatech.co/api/crypto/encrypt'\
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'\
  -H 'Content-Type: application/json'\
  -d '{ "kid": "myKeyKid", "data": "SGVsbG8gQW5rYQ==" }'`

🔒 Authorization & Role-Based Access Control (RBAC)

AnkaSecure enforces fine-grained access control using scopes and roles. Each token is issued with specific permissions that determine which API endpoints can be accessed.

1️⃣ Role-Based Access

Each client is assigned one or more roles, which define what operations can be performed.

Role	Scope	Description
`key_management.listKeys`	`GET /api/key-management/keys`	List available keys
`key_management.generateKey`	`POST /api/key-management/keys`	Generate a new key
`key_management.importKey`	`POST /api/key-management/keys/import`	Import a key
`secure.encrypt`	`POST /api/crypto/encrypt`	Encrypt data
`secure.decrypt`	`POST /api/crypto/decrypt`	Decrypt data
`secure.sign`	`POST /api/crypto/sign`	Sign data
`secure.verifySignature`	`POST /api/crypto/verify`	Verify a signature

💡 Notes:

✔ Tokens include scopes that determine what actions can be performed.

✔ Requests without the proper scope will be denied.

✔ Roles are assigned dynamically based on IAM configurations.

🔄 Token Validation Process

When an API request is received, the AnkaSecure API validates the JWT token before processing.

Validation Steps

1️⃣ The client sends a request with the token.

2️⃣ The API verifies the token signature (via IBM API Connect, AWS Cognito, etc.).

3️⃣ The API extracts the scopes from the token and checks permissions.

4️⃣ If valid, the request is processed; otherwise, a 401 Unauthorized response is returned.

🔍 Key Interactions in the Architecture

🔹 Customer Applications & CLI → Obtain tokens from the Auth Server.

🔹 AnkaSecure API → Verifies tokens before processing API calls.

🔹 IAM Provider (IBM API Connect, AWS Cognito, etc.) → Manages authentication & RBAC.

🔹 Audit Logs → Track authentication & access attempts for compliance.

📌 Summary

✔ Authentication is based on JWT tokens.

✔ Clients obtain tokens from an external authentication provider.

✔ Role-based access control (RBAC) enforces security.

✔ Each API call requires a valid token with the correct scopes.

✔ Requests without valid authorization are rejected.

For more details, refer to:

API Authentication
Key Management