Authentication

Introduction

Authentication is handled via JSON Web Tokens (JWT). There are two methods for retrieving a JWT:
  • Submit credentials as described below and receive a JWT that is capable of interacting with Ghostwriter as the authenticated user
  • Login via the web interface and generate a JWT with your preferred expiration date to use as an API token for automation
The JWT secret key is defined in the environment variables, GRAPHQL_JWT_SECRET_KEY. If you plug a Ghostwriter JWT into a debugger like the one at https://jwt.io/, you will see something similar to the following:
Header
1
{
2
"alg": "HS256",
3
"typ": "JWT"
4
}
Copied!
PAYLOAD
1
{
2
"username": "benny",
3
"sub": "1",
4
"sub_name": "benny",
5
"sub_email": "[email protected]",
6
"aud": "Ghostwriter",
7
"iat": 1646088460,
8
"exp": 1646117260,
9
}
Copied!
SIGNATURE
1
SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
Copied!
The tokens follow the JWT open standard (RFC7519).

User Tokens

User JWTs are generated with a login mutation, a type of GraphQL query that performs a server-side action. The resulting JWT holds the same privileges as the authenticated user.
1
mutation Login {
2
login(password: "password", username: "username") {
3
token
4
expires
5
}
6
}
Copied!
The response includes the token that can be used with the Authorization header of future requests.
By default, the user JWTs are valid for 15 minutes. This configuration is changeable in Ghostwriter's base.py configuration file. Update JWT_EXPIRATION_DELTA to a new time delta (e.g., timedelta(hours=8)).

API Tokens

You can also generate tokens by visiting their profile page and scrolling down to the "API Tokens" section. In this section, you can create new tokens, see all existing tokens, and revoke tokens you no longer need.
A key difference between API tokens and tokens generated by the login mutation is they have user-defined expiration dates. They are intended to be used for long-running automation tasks, like operational logging. If an expiration date is not set they do not expire until revoked.

Token Authentication

Requests authenticate with the Authorization header: Authorization: Bearer TOKEN
Hasura will connect to an authentication webhook before a request. The webhook takes several steps to thoroughly examine the JWT before allowing a request to proceed:
  1. 1.
    Check the JWT is present
  2. 2.
    Attempt to decode the JWT and verify the signature, audience, and expiration
  3. 3.
    Verify the JWT contains the proper claims
  4. 4.
    Finally, verify the user details are correct and the account is still active
If the token passes the above checks and your user's role is authorized (see Authorization)to perform the query or mutation you will receive a 200 OK response with your requested data.
If the token is not accepted the authorization webhook will return a 401 Unauthorized response with an error like this:
1
{
2
"errors": [
3
{
4
"extensions": {
5
"path": "quot;,
6
"code": "access-denied"
7
},
8
"message": "Authentication hook unauthorized this request"
9
}
10
]
11
}
Copied!
Any unauthorized request will be treated as having the public role with the username anonymous. This is not a real user or role and is only used to manage access to resources designed to be accessed without authentication.
At this time the only action available for this anonymous user is the Login mutation.