Skip to content

Latest commit

 

History

History
233 lines (170 loc) · 15.4 KB

README.md

File metadata and controls

233 lines (170 loc) · 15.4 KB
Raw

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