JSON Web Tokens

If you are unfamiliar with JSON Web Tokens (JWTs), consider reviewing Wikipedia JSON article or visiting JWT.io for further information.

JWT administration is conducted via APIs. Refer to our API page for the Swagger file and specifications.

Step 1: Login with Curl Method

Use curl to log into Provider Connectivity Assurance (formerly Skylight Analytics), capturing the authentication token with the -v parameter for subsequent use:

curl --location --request POST 'https://<ANALYTICS URL>/api/v1/auth/login' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'username=you@yourdomain.com' \
--data-urlencode 'password=yourpassword' -v

The result will be verbose due to the -v parameter, but look for the authorization header:

...
< HTTP/2 200
...
< authorization: Bearer MTYyNDU4NzY<yada yada yada>gG17D3sci8L
...
<payload with your dets confirming it worked>

Locate the authentication token in the response, following the 'Bearer' keyword.

For information on how to log in via the API see, Intro to REST APIs and Using APIs to Retrieve Session PM data)

Step 2: Create the JWT

1. Create a JWT using the appropriate API endpoint.

https://api.analytics.accedian.io/session.html#operation/CreateToken

Example request:

curl --location --request POST 'https://**<analytics URL>**/api/v1/auth/tokens' \
--header 'Content-Type: application/vnd.api+json' \
--header 'Cookie: NSREDIRECT=https://<ANALYTICS URL>/api/v1/auth/tokens; skylight-aaa=<AUTHTOKEN>' \
--data-raw '{
    "data": {
        "type": "tokens",
        "attributes": {
            "iss": "you@yourdomain.com",
            "sub": "ronald@acme.inc",
            "aud": "<tenant name>",
            "exp": <epoch integer, set for however long in the future you want this JWT valid for>
        }
    }
}'

2. Save the JWT securely; it will not be displayed again.

3. Verify the JWT using JWT.io and use their debugger.

Step 3: Use the JWT

Embed the JWT in scripts to authenticate sessions before executing tasks:

curl --location --request POST 'https://<ANALYTICS URL>/api/v1/auth/login' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'token=<JWT>' -v

Use the AUTH TOKEN to retrieve PM data, such as calculating average packet loss percentage:

curl --location --request POST 'https://demo.labs.analytics.accedian.io/api/v3/metrics/groupBy' \
--header 'Content-Type: application/vnd.api+json' \
--header 'Cookie: skylight-aaa=<AUTH TOKEN>' \
--data-raw '{
    "data": {
        "type": "groupByMetrics",
        "attributes": {
            "aggregation": "avg",
            "interval": "2021-06-24T02:45:42.945Z/2021-06-25T02:45:42.945Z",
            "groupingContext": {
                "strictGroupings": true,
                "groupings": [
                    {
                        "groupName": "customer",
                        "groupType": "meta"
                    }
                ]
            },
            "globalMetricFilterContext": {
                "objectType": [
                    "twamp-sl",
                    "twamp-pe",
                    "twamp-sf"
                ]
            },
            "metrics": [
                {
                    "direction": [
                        "0"
                    ],
                    "objectType": [
                        "twamp-sl",
                        "twamp-pe",
                        "twamp-sf"
                    ],
                    "metric": "packetsLostPct"
                }
            ],
            "queryContext": {
                "ignoreCleaning": false,
                "focusBusyHour": false,
                "ignoreMaintenance": false,
                "numResults": 5,
                "sorted": "desc"
            }
        }
    }
}'

Understanding JWT and AuthToken Integration

In our platform, JSON Web Tokens (JWTs) are designed for stateless authentication, providing efficient and secure access to APIs.

Here’s how they are integrated into our authentication process:

JWT Usage

JWTs are used to authenticate directly with APIs. This means you can access and retrieve data without needing to generate an additional AuthToken, ensuring a streamlined and high-performance interaction.
Efficiency and Security: Utilizing JWTs directly minimizes server load and enhances security, as they are inherently stateless and designed for RESTful communication.

AuthToken Usage

While JWTs are preferred for stateless access, AuthTokens may be used in certain scenarios for additional authentication layers. However, the primary goal is to leverage JWTs for direct API access wherever possible.

Important Considerations: We recognize that excessive use of stateful tokens like AuthTokens can impact performance. Our aim is to minimize their use and rely on JWTs for optimal integration.

Best Practices

Whenever feasible, use JWTs directly to authenticate and access APIs, reducing reliance on AuthTokens. By ensuring that JWTs are securely stored and managed, you maintain the integrity and confidentiality of your data.