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 :')