gurant

Gurant is an OAuth 2.0 provider built with Typescript/NodeJS. It is an authorization framework based on the OAuth 2.0 Specification.

Additionally, it also has a built-in authentication using Firebase. Currently, it is opinionated and will only support Firebase.

Lastly, this project uses Hasura's GrahpQL Engine for handling database queries and mutations. That would also mean that Gurant is database agnostic as long as Hasura supports it.

Environment Variables

CRYPTO_SECRET_KEY=
CRYPTO_INIT_VECTOR=
FIREBASE_PROJECT_ID=
FIREBASE_DATABASE_URL=
FIREBASE_CLIENT_EMAIL=
FIREBASE_PRIVATE_KEY=
HASURA_ADMIN_SECRET=
JWT_PUBLIC_KEY=
JWT_PRIVATE_KEY=

Change the GraphQL Endpoint (https://gurant.hasura.app/v1/graphql) in the codegen.config.js to the GraphQL Endpoint of your Hasura Project.

Endpoints

Resource Owner Endpoints

GET /user

Fetches the resource owner's profile details.

Response Payload

property	type	description
id	string	the resource owner's identifier
created_at	timestamp	timestamp when the resource is created
updated_at	timestamp	timestamp when the resource is updated
display_name	string	the resource owner's display name
email	string	the resource owner's email
client_live	object	refer to the table below
client_test	object	refer to the table below

Client Object

property	type	description
id	string	the client identifier
created_at	timestamp	timestamp when the resource is created
updated_at	timestamp	timestamp when the resource is updated
secret	string	the client secret
is_live	boolean	determines whether the credentias is for a live or test enviroment
redirect_uri	string	the client's redirect enpoint

POST /user

Register clients after the user has been registed. Requires the user's Firebase token to their info.

Request Payload

property	type	description
redirect_uri	string	the user specified redirect enpoint

Response Payload

property	type	description
id	string	the resource owner's identifier
created_at	timestamp	timestamp when the resource is created
updated_at	timestamp	timestamp when the resource is updated
display_name	string	the resource owner's display name
email	string	the resource owner's email
client_live_id	string	the resource owner's live client identifier
client_test_id	string	the resource owner's test client identifier

PUT /user/clients/:client_id

Update the specified client's redirect endpoint, requires Firebase token for authorization.

Request Payload

property	type	description
redirect_uri	string *	The new redirect enpoint for the client

Response Payload

property	type	description
id	string	the updated client's client identifier
redirect_uri	string	the new redirect enpoint for the client

OAuth 2.0 Endpoints

GET /oauth2/authorize

Retrieve the authrization code after the authorization grant, requires Firebase token authorization.

Request Parameters

property	type	description
response_type	string *	value MUST be code
client_id	string *	the registered client's client identifier
redirect_url	string *	value MUST be the same with the client's redirect_url
scope	string *	the scope of which the authorization is applicable
state	string	additional state to be passed, could be user info

Response Parameters

The response is the redirect url injected with the parameters below

property	type	description
code	string	the authorization code that'll be exchanged to the access token
state	string	value MUST be the same with state parameter passed in the request

POST /oauth2/token?grant_type=authorization_code

This endpoint is responsible for generating tokens using the previously generated authorization code. This also requires client authentication (HTTP Basic Auth).

The generated access and refresh tokens comply with the JSON Web Token (JWT) Specification.

Request Parameter

property	type	description
grant_type	string *	the type of request in how the access token should be generated, value MUST be authorization_code
code	string *	the authorization code that'll be exchanged to the access token
redirect_uri	string *	the redirect enpoint used in the previous authorization grant
client_id	string *	the registered client's client identifier

Response Payload

property	type	description
access_token	string	the access token used to access protected resources
refresh_token	string	the refresh token used to refresh an access token
scope	string	the scope of which access is applicable
expires_in	number	the lifetime in seconds of the access token
token_type	string	the type of the access token, value is always bearer

POST /oauth2/token?grant_type=refresh_token

This endpoint is responsible for generating tokens using a refresh_token. This also requires client authentication (HTTP Basic Auth).

Request Parameter

property	type	description
grant_type	string *	the type of request in how the access token should be generated, value MUST be refresh_token
refresh_token	string *	the refresh token used to refresh an access token

Response Payload

property	type	description
access_token	string	the access token used to access protected resources
refresh_token	string	the refresh token used to refresh an access token
scope	string	the scope of which access is applicable
expires_in	number	the lifetime in seconds of the access token
token_type	string	the type of the access token, value is always bearer

POST /oauth2/revoke

Revoke an access token, requires client authentication (HTTP Basic Auth). This follows the OAuth 2.0 Token Revocation Specification

Request Parameter

property	type	description
token	string *	The token the client wants to revoke
token_type_hint	string *	A hint about the type of the token submitted for revocation. For now, the value MUST be access_token only

Response Payload

property	type	description
status	string	the HTTP status
statusCode	number	the HTTP status code

Utility Endpoints

GET /health

This endpoint is used for health checks

Response Payload

property	type	description
status	string	the HTTP status
statusCode	number	the HTTP status code

GET /generate-crypto-keys

This endpoint SHOULD NOT be exposed in production as it SHOULD only be used for debugging purposes. Generates a secret_key and an initialization vector.

Response Payload

property	type	description
secret_key	string	the raw key used by the algorithm and the initialization vector
initialization_vector	string	a cryptographically random 16 byte string

GET /generate-jwt-keys

This endpoint SHOULD NOT be exposed in production as it SHOULD only be used for debugging purposes. Generates a public and private signed with the secp256r1 elliptic curve.

Response Payload

property	type	description
public_key	string	the public key in a PEM format
private_key	string	the private key in a PEM format

GET /verify-token

This endpoint SHOULD NOT be exposed in production as it SHOULD only be used for debugging purposes. Verifies and decodes a given JSON Web Token (JWT).

Request Parameters

property	type	description
token	string *	the token to be verified and decoded
token_type_hint	string *	the token's type, value could eiher be access_token or refresh_token

Response Payload

property	type	description
decoded	object	the value of the decoded token

TODO

• Add tests :')