README
¶
Terrapukka1
A Go OAuth provider for TerraLing. Currently in development.
Table of Contents
Dependencies
Installation
-
Download and install MySQL
-
Make sure Git is installed
-
Clone the repo
$ git clone https://github.com/svasandani/terrapukka -
That's literally it
Testing
-
Use Go's inbuilt
testingpackage$ go test ./...
Endpoints
The service currently has endpoints for registering Clients and Users, authorizing Users, and granting User data access (in this case, their names and emails) to Clients.
Endpoints will only accept POST requests, and must contain JSON payloads. The header must explicitly declare the Content-Type to be application/json. The endpoints are divided into two categories:
Registration
api/register
Register a new user. Takes in the following structure, with fields required as marked:
{
"response_type": type of authorization request, usually "code", required,
"client_id": client's ID, returned at registration, required,
"redirect_uri": URI to redirect the user to after successful registration, must match registered URI, required,
"user": user model containing name, email and password, required {
"name": user's name, required
"email": user's email, required,
"password": user's password, required
}
"state": random token generated by client, expect to match response state, optional
}
Returns the following:
{
"redirect_uri": URI to redirect the user to,
"auth_code": temporary authorization code,
"state": state given by client at redirect time
}
api/client/register
Register a new client. Takes in the following structure, with fields required as marked:
{
"name": client's name (e.g. Terraling), required,
"redirect_uri": URI to redirect the user to after successful authentication, required
}
Returns the following:
{
"name": client's registered name,
"id": client's id, generated by the application,
"secret": client's secret, generated by the application,
"redirect_uri": client's registered redirect_uri
}
Authorization
api/auth
Authorize a user. Takes in the following structure, with fields required as marked:
{
"response_type": type of authorization request, usually "code", required,
"client_id": client's ID, returned at registration, required,
"redirect_uri": URI to redirect the user to after successful authentication, must match registered URI, required,
"user": user model containing email and password, required {
"email": user's email, required,
"password": user's password, required
}
"state": random token generated by client, expect to match response state, optional
}
Returns the following:
{
"redirect_uri": URI to redirect the user to,
"auth_code": temporary authorization code,
"state": state given by client at redirect time
}
api/client/auth
Authenticate a client attempting to access user data. Takes in the following structure, with fields required as marked:
{
"grant_type": type of data request, usually "identity", required,
"auth_code": user's temporary authorization code, returned from user authorization, required,
"client": client model containing id and secret, required {
"id": client's id, required,
"secret": client's secret, required
"redirect_uri": client's redirect_uri, must match registered URI, required
}
}
Returns the following:
{
"user": requested user data {
"name": user's name,
"email": user's email,
"roles": array of user's roles, if any
}
}
Identification
api/client/identify
Identify a client given their name and redirect_uri. Takes in the following structure, with fields required as marked:
{
"client": client model containing id and secret, required {
"id": client's id, required,
"redirect_uri": client's redirect_uri, required
}
}
Returns the following:
{
"client": requested client data {
"name": client's name,
"id": client's id,
"redirect_uri": client's redirect_uri
}
}
Password Management
api/reset_token
Generate a reset password token for a user given their email. Takes in the following structure, with fields required as marked:
{
"client_id": client's ID, returned at registration, required,
"redirect_uri": URI to redirect the user to after successful registration, must match registered URI, required,
"user": user model containing email, required {
"email": user's email, required
}
}
Returns an HTTP OK on success, or an error otherwise.
api/reset
Reset the password of a user given the correct reset_token. Takes in the following structure, with fields required as marked:
{
"reset_token": reset password token, required,
"user": user model containing email, required {
"password": user's new password, required
}
}
Returns an HTTP OK on success, or an error otherwise.
Contributing
Look through the issues and read through the code to see what needs help. Some tags:
@TODO- problems that are attached to issues.@QOL- problems that aren't major and so may not be attached to issues.
Footnotes
1. British English (inf); pukka: genuine.
Directories