JSON Web Tokens

JSON Web Tokens (JWT) allow you to authenticate API requests, automate tasks, and securely access Connectware resources. These tokens can be configured as long-lived tokens that remain valid for extended periods, making them ideal for ongoing automation and continuous system access. Learn how to generate tokens, apply security best practices, and understand the protections built into Connectware's authentication system.

Token Security

Token Redirection Rules

Connectware enforces strict URL redirection rules to prevent phishing attempts and protect against web security vulnerabilities.

1. Protocol binding: Connectware requires HTTPS and ensures that no redirects can downgrade the connection to HTTP.

2. Domain restriction: Redirects are limited to the current domain.

   • Example: When accessing https://demo.cybus.io/, you can only redirect to paths within that domain. Redirects to external domains like https://cybus.io/ are blocked.

JSON web tokens provide access to Connectware with the same permissions as the user who generated it. Tokens should be generated by users with only the required permission levels.

Token Best Practices

Implementing secure token practices is crucial for maintaining the security of your Connectware environment. Below are key practices to follow when working with tokens:

1. Set appropriate expiration

   • Configure token lifetime using the expireTimeInHours parameter based on your specific use case.

   • Avoid unnecessarily long expiration periods.

2. Implement token rotation

   • Replace active tokens regularly with new ones.

   • Revoke old tokens after replacement.

3. Separate token usage

   • Create distinct tokens for different services or tasks.

   • This limits potential security exposure if any single token is compromised.

Generating JSON Web Tokens

1. Send a POST request to obtain your token. The response will contain a token property with your JWT authentication credentials.

curl -X 'POST' \
'https://<CONNECTWARE HOST>/api/login' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-k \
-d '{
"username": "<A USERNAME>",
"password": "<A PASSWORD>",
"expireTimeInHours": 99999,
"label": "test-token"
}'

1. Use this token in subsequent requests by adding it as an apiToken query string parameter in your URLs.

curl -k --location --request GET https://<CONNECTWARE HOST>/api/users?apiToken=<TOKEN OBTAINED IN PREVIOUS STEP HERE>

Browser Authentication via JSON Web Tokens

You can use tokens to authenticate users via an authentication URL or redirect users to a specific location within Connectware after authentication.

• Authentication URL: To authenticate users on the browser using the token, enter the following URL:

https://<CONNECTWARE HOST>/admin?apiToken=<TOKEN>

• Authentication with Redirection: To redirect users to a specific location within Connectware after authentication, enter the following URL. This is particularly useful when working with Cybus::IngressRoute resources) resources.

https://<CONNECTWARE HOST>/admin?redirect=<REDIRECTION URL>&apiToken=<TOKEN>

Example

https://<CONNECTWARE HOST>/admin?redirect=/services/foo/bar&apiToken=barFoo