Master Key APIs

Owned by Rahul Kumar
Last updated: Jan 31, 2019
2 min read

Background

Currently content update is done by the user who created it which creates problem and is complex in scenarios where an admin want to update content by retired user. There should be an easy way to allow users to update content at the same time it should have authentication.

Problem Statement 1

What is the approach to generate the key?

Solution 1

Create JWT token with data passed upon. A JWT token will be created using secret key and below data 

  1. channel
  2. name
  3. description
  4. organisationId
  5. createdBy
  6. createdOn

Solution 2

Custom generated time based key.

Solution 3

Using keycloak to generate an verify token to be used as masterkey.


Pros and Cons

Key Generation ApproachPros

Cons

JWTno need to store the key in DB
Custommethod is available so negligible time consumingkey needs to be stored in db
Keycloakcomparatively faster to implement

no support for channel or organisation based key

key would expire based on keycloak configuration



Problem Statement 2

What are the APIs required to manage master keys?

API Specifications

Create API

name and channel / organisationId is mandatory.

URL: 

POST /v1/auth/masterkey/create

Headers:

  • Authorization
  • x-authenticated-user-token

Request Params:

param nametypedescription
channelStringchannel for which master key is applicable for, if not provided can be calculated from organisationId
nameStringconsumer name
organisationIdStringorganisationId for which master key is applicable for, if not provided can be calculated from channel

Response Params:

param nametypedescription
keyStringgenerated master key, mapped with the requested channel/organisationId and name

Errors:

status codeerror codeerror message
400INVALID_ORG_DATAGiven Organization Data doesn't exist in our records. Please provide a valid one.
400MANDATORY_PARAMETER_MISSINGMandatory parameter {channel/organisationId, name} is missing.
400PARAMETER_MISMATCHMismatch of given parameters: channel, organisationId.
400KEY_EXISTSKey exists for given channel {} and consumer {}


Sample Request and Response:

Request

{
	request : {
		"channel" : "sunbird",
		"name" : "DikshaImplTeam",
		"orgId" : "01262366359399628812"
	}
}

Response

{
  "id": "api.auth.masterkey.create",
  "result": {
		"key" : "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjaGFubmVsIjoic3VuYmlyZCIsIm5hbWUiOiJEaWtzaGFJ bXBsVGVhbSIsImNyZWF0ZWRCeSI6MTUxNjIzOTAyMiwiY3JlYXRlZE9uIjoxNTE2MjM5MDIyLCJleHBpcmVzT24iOjE1MTYyNDkwMjIsIm9yZ0lkIjoiMjM0NTY1NDU2In0.Cs5-FW7OHip6njkQvMP6zpIVB5Q-xLLgz_jnYW3zPOw"
	}
}


Verify API

URL:

POST /v1/auth/masterkey/verify

Headers:

  • Authorization

Request Params:

param nametypedescription
keyStringmaster key to verify 


Response Params:

param nametypedescription
channelStringchannel name related to master key
nameStringconsumer name
descriptionStringdescribes the purpose for master key
organisationIdStringorganisation Id mapped with key
createdByStringuserId of the person who created the key
createdOntimestamptimestamp when master key was created

Errors:

status codeerror codeerror message
400INVALID_KEYGiven master key is invalid
400MANDATORY_PARAMETER_MISSINGMandatory parameter key is missing.


Sample Request and Response:

Request

{
	request : {
		"key" : "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjaGFubmVsIjoic3VuYmlyZCIsIm5hbWUiOiJEaWtzaGFJ bXBsVGVhbSIsImNyZWF0ZWRCeSI6MTUxNjIzOTAyMiwiY3JlYXRlZE9uIjoxNTE2MjM5MDIyLCJleHBpcmVzT24iOjE1MTYyNDkwMjIsIm9yZ0lkIjoiMjM0NTY1NDU2In0.Cs5-FW7OHip6njkQvMP6zpIVB5Q-xLLgz_jnYW3zPOw"
	}
}

Response 

{
  "id": "api.auth.masterkey.verify",
  "result": {
  		"channel": "sunbird",
  		"name": "DikshaImplTeam",
		"description": "organisation content"
		"organisationId": "01262366359399628812"
  		"createdBy": "00dd6646-be73-4fb0-b676-ccd01bda085e",
  		"createdOn":1548932815386,
  	}
}


Delete API

URL:

POST /v1/auth/masterkey/delete

Headers:

  • Authorization
  • x-authenticated-user-token

Request Params:

param nametypedescription
channelStringchannel for which master key needs to be deleted
nameStringconsumer name
organisationIdStringorganisationId for which master key needs to be deleted

Response Params:

None

Errors:

status codeerror codeerror message
400MANDATORY_PARAMETER_MISSINGMandatory parameter {channel/organisationId, name} is missing.
400KEY_NOT_EXISTSKey does not exists for given channel {} and consumer {}


Sample Request and Response:

Request 

{
	request : {
		"channel" : "sunbird",
		"name" : "DikshaImplTeam",
		"orgId" : "01262366359399628812"
	}
}

Response

{
  "id": "api.auth.masterkey.delete",
  "responseCode": "OK",
  "result": {
	}
}


Problem Statement 3

What is the DB design for storing information about master keys?

approach 1:

JWT token Table Structure 

columntypedescription
channel*textconsist user provide channel name
name*textprovided by user
organisationIdtextprovided by user or root org id mapped with channel
createdBytextuser id who created the master key
createdOntimestampcreated time
approach 2:

custom generated key

columntypedescription
channel*textconsist user provide channel name
name*textprovided by user
organisationIdtextprovided by user or root org id mapped with channel
keytextholds custom generated key
createdBytextuser id who created the master key
createdOntimestampcreated time


Problem Statement 4

How to use generated master key to bypass existing user authentication?

approach 1:
  • master key will be passed in X-authenticated-user-token
  • use an extra header (X-authentication-type) declaring the type of authentication as master( for master key and user for user authentication). 
approach 2:
  • extra header (X-authentication-master-key) to pass master key.
  • If above header is present it supersedes the user authentication 

Pros and Cons

Key Usage ApproachPros

Cons

X-authentication-typeIn future it can support additional authentication types