ForkAuth Client

Install to Project:

npm install forkauth-client-new --save

How To Use:

Import the ForkAuth Client to your project as follows:

const fClient = require('forkauth-client')

const options = {
    server: 'URL for your online ForkAuth server'.
    app: 'The application name in which you are using ForkAuth'
    apiKey: 'The apiKey that is registered for the app in ForkAuth',
    ca: 'Optional. Certificate to sign https requests with.'
}

const fAuth = new fClient(options)

module.exports = fAuth //So you can use it throughout your application.

Standard response format:

Error:

    status: 'error',
    error: {
        name: 'ErrorName',
        message: 'This is a description of the error'
    }

Success:

    status: 'success',
    message?: 'Success Message. Optional.',
    data?: {
        [field]: { // The field differs depending on the method called. Only appears when there is data returned.
            // Returned Data        
        }
    }

Available Methods:

NOTE - All methods except the login method NEEDS to the token passed as an parameter.

login(username, password): fAuth.login('test', 'password') - Login through ForkAuth.

Response:

    status: 'success',
    data: {
        token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbiI6IjMzN2NlYjQ1OTU0YjhhOTFiZmZkODkzNWRlMTE1OTJlNDc1ZjNkIiwiaWF0IjoxNTMxOTg4MjMwLCJleHAiOjE1NDA2MjgyMzB9.gaiEDX2mBBu9kMqRt132-lq8tIN_ea9fuNhgCIRLtGE',
        user: {
            _id: '5ad83f68b4d73906b3603c0b'
            username: 'test',
            name: 'Test',
            surname: 'User',
            locked: false,
            provider: 'local',
            avatar: 'https://forkauth.link.com/media/filename.jpg',
            department: 'HR',
            position: 'clerk',
            createdAt: '2018-04-19T07:04:09.187Z',
            active: '2018-07-19T08:10:51.122Z',
            updatedAt: '2018-07-19T08:17:10.501Z'
        }
    }

getRoles(token): fAuth.getRoles(token) - Get all the roles that the user has.

Response:

{
    status: 'success',
    data: {
        roles: [
            {
                _id: '5a9fb95e3b319f0708fce3d5',
                name: 'Role_Name',
                description: 'Role Description',
                users: ['5a9fb95e3b319f0708fce419'],
                createdAt: '2018-03-07T10:05:18.455Z',
                updatedAt: '2018-05-29T12:36:06.047Z'
            }
        ]
    }
}

checkUserRole(token, role): fAuth.checkUserRole(token, 'ROLE_NAME') - Check if the user has access to a spesific role.

Response:

    status: 'success',
    data: {
        access: true
    }
}

addRole(role): fAuth.addRole(token, 'ROLE_NAME') - Assign the user to the role.

Response:

    status: 'success',
    messge: 'User Added to Role'
}

removeRole(role): fAuth.removeRole(token, 'ROLE_NAME') - Remove the user from the role

Response:

    status: 'success',
    messge: 'User Removed from Role'
}

checkUserAccess(token): fAuth.checkUserAccess(token) - Check if the user has access to the app.

Response:

    status: 'success',
    data: {
            access: true
    }
}

checkUserPermission(token, action, resource?, scope?): fAuth.checkUserPermission(token, 'delete', 'users', {field: 'username', value: 'user1'}) - Check if the user has access to the specified permissions.

Response:

    status: 'success',
    data: {
        access: true
    }
}

getAllUserPermissions(token): fAuth.getAllUserPermissions(token) - Get a list of all the user's permissions.

Response:

    status: 'success',
    data: {
            permissions: [
                {
                    _id: '5a9fb95e3b319f0708fce3f4'
                    type: 'role'
                    type_id: '5a9fb95e3b319f0708fce3d4'
                    app: 'AppName'
                    actions: ['read', 'write', 'delete']
                    createdAt: '2018-03-07T10:05:18.513Z'
                    description: 'Permission Description'
                    resource: 'users'
                    risk: 1
                    scope: {
                        type: '*'
                    }
                } 
            ]
            
    }

getUserAppPermissions(token): fAuth.getUserAppPermissions(token) - Get all the user's permissions for the app.

Response:

    status: 'success',
    data: {
            permissions: [
                {
                    _id: '5a9fb95e3b319f0708fce3f4'
                    type: 'role'
                    type_id: '5a9fb95e3b319f0708fce3d4'
                    app: 'AppName'
                    actions: ['read', 'write', 'delete']
                    createdAt: '2018-03-07T10:05:18.513Z'
                    description: 'Permission Description'
                    resource: 'users'
                    risk: 1
                    scope: {
                        type: '*'
                    }
                } 
            ]
            
    }

grantPermission(token, type, type_id, actions, resource, scope, risk, description): fAuth.grantPermission(token, 'user' || 'role', '5a9fb95e3b319f0708fce3d4', ['read', 'write', 'delete'], 'users', {type: '*'}, 75, 'Permission Description') - Create the permission specified.

Response:

    status: 'success',
    message: 'Permission Created',
    data: {
        permission: {
            _id: '5a9fb95e3b319f0708fce3f4'
            type: 'role'
            type_id: '5a9fb95e3b319f0708fce3d4'
            app: 'AppName'
            actions: ['read', 'write', 'delete']
            createdAt: '2018-03-07T10:05:18.513Z'
            description: 'Permission Description'
            resource: 'users'
            risk: 75
            scope: {
                type: '*'
            }
        }
    }

revokePermission(token, permission_id): fAuth.revokePermission(token, '5a9fb95e3b319f0708fce3f4') - Delete the permission specified.

Response:

    status: 'success',
    message: 'Permission Deleted'

resourcesList(token): fAuth.resourcesList(token) - Get a list of resources the user has access to.

Response:

    status: 'success',
    data: {
            resources: ['users', 'posts', 'tokens']
    }

actionsList(token, resource): fAuth.actionsList(token, 'users') - Get a list of actions that the user has for a specified resource

Response:

    status: 'success',
    data: {
            actions: ['read', 'write', 'delete']
    }

scopesList(token, resource, field?): fAuth.scopesList(token, 'users', 'username') - Get a list of scopes the user has access to for a specified resource. Can further narrow it down by specifying a field name.

Response:

    status: 'success',
    data: {
            scopes: [{
                field: 'username,
                type: 'array',
                value: ['user1', 'user2', 'user43']
            }]
    }

appsList(token): fAuth.appsList(token) - Get a list of apps the user has access to.

Response:

    status: 'success',
    data: {
        apps: ['App1', 'App2', 'App3']
    }

uploadAvatar(token, photo): fAuth.uploadAvatar(token, photo) - Upload a photo to use as an avatar for the user.

NOTE: The 'photo' parameter is the photo in Buffer or the path.

Response:

    status: 'success',
    data: {
        user: {
        _id: '5ad83f68b4d73906b3603c0b'
        username: 'test',
        name: 'Test',
        surname: 'User',
        locked: false,
        provider: 'local',
        avatar: 'https://forkauth.link.com/media/filename.jpg',
        department: 'HR',
        position: 'clerk',
        createdAt: '2018-04-19T07:04:09.187Z',
        active: '2018-07-19T08:10:51.122Z',
        updatedAt: '2018-07-19T08:17:10.501Z'
        }
    }

getAvatarBase64(token): fAuth.getAvatarBase64(token) - Get the Avatar Image as a Base64 Data URI.

NOTE: Only use this function if you cannot directly access the avatar URL that is sent with the user.

Response:

    status: 'success',
    data: {
        image: 'Base64 Data URI String'
    }