JSON Web Token Authentication

What is a JSON Web Token (JWT)?

A JSON Web Token is used to send information that can be verified and trusted by means of a digital signature. It comprises a compact and URL-safe JSON object, which is cryptographically signed to verify its authenticity, and which can also be encrypted if the payload contains sensitive information.

Because of its compact structure, JWT is usually used in HTTP Authorization headers or URL query parameters.

Structure of a JSON Web Token

A JWT is represented as a sequence of base64url encoded values that are separated by period characters.

header.payload.signature

Header

The header contains the metadata for the token and it minimally contains the type of signature and the encryption algorithm.

Payload (Claims)

In the context of JWT, a claim can be defined as a statement about an entity (typically, the user), as well as additional metadata about the token itself. The claim contains the information we want to transmit, and that the server can use to properly handle JSON Web Token authentication. There are multiple claims we can provide; these include registered claim names, public claim names and private claim names.

Signature

The JWT standard follows the JSON Web Signature (JWS) specification to generate the final signed token. It is generated by combining the encoded JWT Header and the encoded JWT Payload and signing it using a strong encryption algorithm, such as HMAC SHA-256. The signature’s secret key is held by the server so it will be able to verify existing tokens and sign new ones.

How JSON Web Tokens Work

A browser or mobile client makes a request to the authentication server containing user App Key and App SID. The authentication server generates a new JWT access token and returns it to the client. On every request to a restricted resource, the client sends the access token in the Authorization header. The server then validates the token and, if it’s valid, returns the secure resource to the client.

Applications

To access Aspose REST APIs, you need to create an application. To register new applications, login into the Dashboard Developer site using your Aspose Account, and go to the My Apps view. Once you create a new application, we will issue a client_id (App SID) and client_secret (App Key) that you can use to authenticate your REST API calls using the JWT authentication.

Get Access Token

After you have created a new application you can obtain an access token by sending a POST request to /connect/token endpoint. Still, you must authenticate your access token request using Client Credentials authorization grant type flow:

POST request to: https://api.aspose.cloud/connect/token Headers: Accept: application/json Content-Type: application/x-www-form-urlencoded Body: grant_type: client_credentials client_id: APP_SID client_secret: APP_KEY

The endpoint acts as an authorization server and it verifies your credentials, if they are correct it returns a JSON ticket containing several items, through each, you can find the access_token, expire time of a token etc. The provided access_token is a Bearer Token that you can further use in the Authorization header of your request.

cURL Example

Call REST API

Now that you have the Bearer Token (access_token) generated using the application credentials, you can make API calls and authorize by adding the access token in the ‘Authorization’ header.

Headers: Authorization: Bearer JWT_TOKEN

You authorize with one application, but you can access files from all storages in your account, or all Application’s default storage by specifying query parameters (storage or AppSid).

cURL Example

Tokens Lifetime

The time of the tokens is finite. By default, the access_token lifetime is 1 day. To detect when an access token expires, you must write a specific code that will check for any of these:

• expires_in value in the ticket generated by connect endpoint.
• will handle the 401 Unauthorized error responses from the API endpoint and issue a request for a new token.