Open SSO API Documentation

aalfiann included in Documentation

2022-12-02 1031 words 5 minutes

Contents

Open SSO basically is a Rest API first system. Here is the fundamental API list to use in your website.

X-Token

1. Login Normal
2. Login via Oauth
3. Login via SSO Login Page

API

A. Verify Token
B. Get My Profile
C. Update My Profile
D. Deactivate My Profile
E. Get Another User Profile
F. API via Postman

Response Format

Learn more

X-Token

X-Token is a header that should be filled with JWT token generated from user login.
Most API request in Open SSO will require X-Token header.
You can get X-Token in three different ways.

Get X-Token via login normal.

Method	Endpoint	Header	Body
POST	http://localhost:3000/api/user/login	Content-Type: application/json	{“username”: “”, “password”: “”}

Example output response

{
    "message": "Login user success!",
    "statusCode": 200,
    "success": true,
    "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1aWQiOiI1ZDM3NDk5Yi0xM2ZjLTQzZmItOWE3Yi1kZGI3Nzc1N2FjOTMiLCJ1bm0iOiJhYWxmaWFubiIsIm5hbWUiOiJhYWxmaWFubiIsIm1haWwiOiJhYWxmaWFubkBnbWFpbC5jb20iLCJyb2xlIjoiYWRtaW4iLCJncmF2YXRhciI6Imh0dHBzOi8vZ3JhdmF0YXIuY29tL2F2YXRhci82ZDdiZDI0MWEyNjc5ZDc1NTc4OTQwMjY4MWQyNWVjMSIsImhhc2giOiJVeHlNVGJqb0cxcHBoWnpNVE1UUSIsImlhdCI6MTY3Mjc3NDg3MCwiZXhwIjoxNjcyODAzNjcwfQ.I1OZASUEtLOBYcaKLHesbsIfywQmB00e1mQO2QTroGmPQtlA84mqwUDYbAiOhS0micIilMlSaIYk0_QdwVABCWNqJlREU0BeQkrKE64tuJ4WHY7lbTvklPOA0k-j6JBZpqp-D0qw8F8-zN6iYq0vyuBHZ6vfRe-0i-B96FiijKZKPkG3KPmXnY0HJtx4GPxhigaUvLb2rRN4eV8Am--2XnbAWpRqecuI5LM6b2oFG-ZoOfNm0LLNe2TJCaKUXBFvoAIZnwAk_l0HZmu-wtiCjkmcjQ5aOO1mrZTONAckvfVFWjK4bx4IFXFeLUVZPOJA3_z9PzH--AoYzjQkYL_q8Q",
    "expire": 1672803670000
}

Back to top ^

User who registered using oauth Google or Apple will require this API.

Note:

This method will auto register new user if an username or email not exists inside OpenSSO.
You should follow the oauth flow Google and Apple or bad person could spamming your application.
If you not sure or can’t follow the oauth Google and Apple, you better use Login via SSO Login Page.

a. Get Access Token

You need to have SSO Key, by create your SSO inside menu My SSO.

See picture below

Method	Endpoint	Header	Body
GET	http://localhost:3000/api/oauth/request_token	Content-Type: application/json, Access-Key: {{YOUR_SSO_KEY}}

Example output response

{
    "message": "Access token successfully generated!",
    "statusCode": 200,
    "success": true,
    "access_token": "=Ng=zY3MzNzOjMmY2YzdmYjODNGRxxhNhN5NjZjQGRiZmMkNDYTNmExQ1OxOTxxx"
}

Note:

SSO Key have no expiring time, but you can’t use it again if its status disabled or removed from My SSO menu.

b. Get X-Token

Once you have the access-token, you can use it to request X-Token.

Google

Method	Endpoint	Header	Body
POST	http://localhost:3000/api/oauth/google	Content-Type: application/json, Access-Token: {{YOUR_ACCESS_TOKEN}}	{“username”:“yourusername”, “email”:“youremail@gmail.com”,“gravatar”:""}

Apple

Method	Endpoint	Header	Body
POST	http://localhost:3000/api/oauth/apple	Content-Type: application/json, Access-Token: {{YOUR_ACCESS_TOKEN}}	{“username”:“yourusername”, “email”:“youremail@gmail.com”}

Example output response

{
    "message": "Oauth google success!",
    "statusCode": 200,
    "success": true,
    "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1aWQiOiJiOGEwMzlmNy1jZjUyLTQ0MDktODU3OS01Yzc0Yjk3MzI2MDMiLCJ1bm0iOiJhYWxmaWFubiIsIm5hbWUiOiIiLCJtYWlsIjoiYWFsZmlhbm5AZ21haWwuY29tIiwiem9uZSI6IiIsInJvbGUiOiJtZW1iZXIiLCJncmF2YXRhciI6Imh0dHBzOi8vZ3JhdmF0YXIuY29tL2F2YXRhci82ZDdiZDI0MWEyNjc5ZDc1NTc4OTQwMjY4MWQyNWVjMSIsImhhc2giOiJBPT1RNE82TlRaWElXMWlwdFoyTUROalEiLCJpYXQiOjE2OTA0MzQ4MTEsImV4cCI6MTY5MDQ2MzYxMX0.XPTmCkJn85e26vgtnMdU5yLi6TGcBu0ct_MpVniJw8dB6yrxn3cNZm9luNJnSh7rWNLZV40jOYS0FbOxMMxfpF-n9uNUhoMnWqwd9pO3VERDuXOlhXVeWhHRHfn87JV2w_mlI6ZFfA3t3WjT5D8cydzs1Hf1Y8l726mVwrXMxJgV0W8TTIz1BiEPEnsFTX4V_fS5IdStz_8rz43q7keeUgBZ0qlGULjQpYGI_6xIKqsY1AP2rrQ9BJ57QL71aoULAJ5Uu7eTCicnO77pRJO-Hi2xFoZpIabsAZfOyd01hTnk3htsolIDY-_dB1_t5Hruullu89oNAWcgK_bChXzLuw",
    "expire": 1690463611000
}

The simpler and safer is just use SSO Login Page to get the X-Token. But there is some tricky because Google Login Button can’t displayed in Android WebView as default.

Back to top ^

API

If you already have the X-Token, then you can access all APIs below here.

A. Verify Token

When you have the new token, you shouldn’t need to verify it all the time. This API is created just for test only.

Method	Endpoint	Header	Body
POST	http://localhost:3000/api/auth/verify	X-Token: {{YOUR_TOKEN}}

Example output response

{
    "message": "Verify authentication success!",
    "statusCode": 200,
    "jwt": {
        "uid": "5d37499b-13fc-43fb-9a7b-ddb77757ac93",
        "unm": "aalfiann",
        "name": "aalfiann",
        "mail": "aalfiann@gmail.com",
        "role": "admin",
        "gravatar": "https://gravatar.com/avatar/6d7bd241a2679d755789402681d25ec1",
        "hash": "UxyMTbjoG1pphZzMTMTQ",
        "iat": 1672774870,
        "exp": 1672803670
    }
}

Explanation

uid is your user id.
unm is your username.
name is your fullname.
mail is your email address.
role is the level of user.
gravatar is the global avatar of user.
hash is the random generated string, only used for internal system.

Below here is the JWT standard which is described in RFC7519:

iat is identifies the time at which the JWT was issued.
exp is expiration time for JWT.

Note:

As alternative, you are able to verify your token through JWT.io.
To make the signature valid on JWT.io, you have to paste your private.key and public.key to its website.

Back to top ^

B. Get My Profile

This API is to show your user information

Method	Endpoint	Header	Body
POST	http://localhost:3000/api/user/my-profile	X-Token: {{YOUR_TOKEN}}

Example output response

{
    "message": "Get my profile successfully!",
    "statusCode": 200,
    "success": true,
    "data": {
        "created_at": 1666643963244,
        "modified_at": 1666643963244,
        "id": "5d37499b-13fc-43fb-9a7b-ddb77757ac93",
        "username": "aalfiann",
        "fullname": null,
        "email": "aalfiann@gmail.com",
        "role": "admin",
        "method": "internal",
        "service": "internal",
        "data": null,
        "status": 1,
        "created_at_month": "October",
        "created_at_year": 2022,
        "gravatar": "https://gravatar.com/avatar/6d7bd241a2679d755789402681d25ec1"
    }
}

Back to top ^

C. Update My Profile

This API is to modify your user information

Method	Endpoint	Header	Body
POST	http://localhost:3000/api/user/my-profile/update	X-Token: {{YOUR_TOKEN}}, Content-Type: application/json	{“fullname”: “M ABD AZIZ ALFIAN”, “email”: “aalfiann@gmail.com”, “data”: {“address”: “Jakarta Timur DKI Jakarta”, “about_me”: “Just ordinary developer”}}

Example output response

{
    "message": "Your profile successfully updated!",
    "statusCode": 200,
    "success": true,
    "data": [
        1
    ]
}

Note:

Field data is an object type, you can set whatever information on your data user.

Back to top ^

D. Deactivate My Profile

This API is to deactivate or delete your account.

Method	Endpoint	Header	Body
POST	http://localhost:3000/api/user/my-profile/suspend	X-Token: {{YOUR_TOKEN}}, Content-Type: application/json	{“username”: “aalfiann”}

Example output response

{
    "message": "Your profile successfully suspended!",
    "statusCode": 200,
    "success": true,
    "data": [
        1
    ]
}

Note:

This action will make your profile deactivated and permanently suspended.
Nobody can’t find you anymore.
Your username will not available anymore (nobody can’t use your username).

Back to top ^

E. Get Another User Profile

This API is to show another user information.

Method	Endpoint	Header	Body
GET	http://localhost:3000/api/user/profile/«username»

Example output response

{
    "message": "Get user profile successfully!",
    "statusCode": 200,
    "success": true,
    "data": {
        "created_at": 1666643963244,
        "modified_at": 1672776525314,
        "id": "5d37499b-13fc-43fb-9a7b-ddb77757ac93",
        "username": "aalfiann",
        "fullname": "M ABD AZIZ ALFIAN",
        "method": "internal",
        "service": "internal",
        "data": {
            "address": "Jakarta Timur DKI Jakarta",
            "about_me": "Just ordinary developer"
        },
        "status": 1,
        "created_at_month": "October",
        "created_at_year": 2022,
        "gravatar": "https://gravatar.com/avatar/6d7bd241a2679d755789402681d25ec1"
    }
}

Note:

Replace <<username>> with the username of other user.
This is public API, so you can request it without X-Token header.

Back to top ^

F. API via Postman

There is 50 API used in Open SSO. Many of them are used for internal system. You can learn it or make an experiment directly using Postman. Just import the file postman_collection.json (located at root directory) to your Postman Application.

Back to top ^

Response Format

Here is the default response format, any request will having message and statusCode key properties. The error key property will shown only at 4xx and 5xx http status code.

Success

{"message": "string", "statusCode": 200}

Created

{"message": "string", "statusCode": 201}

Bad Request

{"message": "string", "statusCode": 400, "error": "Bad Request"}

Unauthorized

{"message": "string", "statusCode": 401, "error": "Unauthorized"}

Forbidden

{"message": "string", "statusCode": 403, "error": "Forbidden"}

Not Found

{"message": "string", "statusCode": 404, "error": "Not Found"}

Internal Server Error

{"message": "string", "statusCode": 500, "error": "Internal Server Error"}

Back to top ^

Open SSO API Documentation

Table Of Contents

Learn more

X-Token

1. Login Normal

2. Login via Oauth

a. Get Access Token

b. Get X-Token

3. Login via SSO Login Page

API

A. Verify Token

B. Get My Profile

C. Update My Profile

D. Deactivate My Profile

E. Get Another User Profile

F. API via Postman

Response Format