User Authorization

Easily get the logged-in user's information, custom data, membership information, and team information.

To authenticate a user, follow the Cofor.io OAuth protocol to receive a secure expire-able authorization token (JWT).

OAuth Login Protocol

To perform a login using the Cofor.io OAuth protocol, send the user to https://cofor.io/oauth/login on the front-end with the following URL query parameters:

• product
• redirect_uri - URL to return the user to after successful login or in case of error
• state - (Optional) any provided value which will be returned to the redirect URI as is.

Upon successful login, the authorization token will be returned to the frontend (provided redirect URI) with the query parameter code. If there is an error, that error is returned to the frontend with the query parameter error.

NOTE: Make sure the URL you specified in the redirect_uri query parameter is on the list of acceptable redirect URIs on the Cofor.io product management portal.

Your product can store the token in local storage, or set cookies to persist the user session. On your product backend, you can get the login information using the function:

JavaScript

const login = await cio.Authorize(AUTH_TOKEN);

The session object includes the corresponding user and membership objects.

JavaScript

const user = login.user;
const membership = login.membership;

If the user is part of a Team, the login object will also include a team property which is an instantiated object of the "Team" class.

JavaScript

const team = login.team;

👍

Full SDK Reference

The team object includes various functions. See the SDK Reference for a detailed list functions within the object.

If a user logs out using Cofor.io, the authorization token is automatically expired.

Authorize User for API Endpoint

User memberships have scopes and access levels which can be checked. Access levels are one of "owner", "admin", and "member".

JavaScript

const access_level = membership.access_level;

By passing a required access_level to the Authorize function call will raise an exception of the user membership doesn't possess the minimum required access level provided. Optionally, you can pass a list of required scopes a team and member must have.

JavaScript

const login = await cio.Authorize(AUTH_TOKEN, access_level='member', team_scopes=[], member_scopes=[]);

A team must possess all of the scopes in the team_scopes array and a member must possess all of the scopes in the member_scopes array for the login to be authorized.

Middleware for ExpressJS Apps

A helper function can also be used as middleware for ExpressJS APIs as follows.

JavaScript

router.route('/path/to/endpoint').get(
    cio.AuthorizeMiddleware('member', [], []),
    (req, res, next) => {
    ...
});

The cio.AuthorizeMiddleware function returns a callable middleware function that accepts req, res, and next.

By default, the token must be passed in as an 'Authorization' header as bearer. For example:

JSON

{
    "Authorization": "Bearer {TOKEN}"
}

To retrieve the authorization token by default from a different location (must be in the request body though!), you can pass a custom function to the Coforio object as follows. This function may be asynchronous.

JavaScript

cio.setTokenFunc((req) => {
    return req.token; // Or wherever the token is placed.
})

If the authorization failed, a 403 Forbidden HTTP status code will be returned with an error message containing information about the missing scopes. If successful, the login object will be attached to the request object (req) and passed to the next function/middleware in the chain.

JavaScript

const login = req.login;

TypeScript Users: Augmenting Express

In order for your login object to be properly populated onto Express requests for use with this middleware, you will need to augment the Express module via TypeScript. Provide the same type parameters as the Coforio constructor to ensure proper type-checking and autocomplete options for req.login.

TypeScript

import { Login } from '@inventives/coforio-sdk';
import { TeamScopes, MembershipScopes, TeamData, MembershipData } from './somewhere';

declare module "express" {
    export interface Request {
        login?: Login<TeamScopes, MembershipScopes, TeamData, MembershipData>;
    }
}