Pixaera Auth Client

This package enables a service to connect to Pixaera's auth provider, enabling users with account on Pixaera to log in other systems with same user.

Install

npm install pixaera-auth-client

Configuration

This package runs on Node.js Express.js and requires that cookie-parser is configured.

Also, the following environment variables are required:

PIXAERA_AUTH_CLIENT_ID=[ID Issued by Pixaera]
PIXAERA_AUTH_CLIENT_SECRET=[Secret Issued by Pixaera]
PIXAERA_AUTH_CRYPT_SECRET=[A secret of your choice, must be a long string]
PIXAERA_AUTH_REDIRECT_URI=[URL with Authentication Callback]
PIXAERA_AUTH_AFTER_LOGIN_PAGE=[URL to Redirect once credentials are set]
PIXAERA_AUTH_SCOPE=[Scopes to be allowed by user] - Example: 'openid email roles' (Default is 'openid')
PIXAERA_AUTH_CALLBACK_NO_REDIRECT=If this variable is true, the redirect after callback must be made manually (avoids CORS issues)

If you want to test an application, you can use our SANDBOX Mode. To do so, just set the environment variable PIXAERA_AUTH_SANDBOX to true.

Example

In the example below, the first route is being protected by authentication. If the user is not authenticated, or doesn't have the permission "permission_test" inside one of its roles, The authMiddleware will return error "Access is Forbidden".

To authenticate the user, you must call pixaeraAuthClient.getAuthUrl and redirect the user to the resulting URL. The URL will already have the redirect back to the client, on 'https://[YOUR_DOMAIN]/auth_callback' (PIXAERA_AUTH_REDIRECT_URI). Then, after callback was successfull, user will be redirected to 'https://[YOUR_DOMAIN]' (PIXAERA_AUTH_AFTER_LOGIN_PAGE)

const pixaeraAuthClient = require('pixaera-auth-client');

// Retrieves protected content if user is authenticated, else calls next(err)
router.get('/', pixaeraAuthClient.authMiddleware('permission_test'), function (req, res, next) {
  // SOURCE BEING PROTECTED BY AUTHENTICATION
});

// Returns a url to authenticate {url: URL}
router.get('/auth_url', pixaeraAuthClient.getAuthUrl);

// Authenticates user after callback from Auth Server 
// (Will redirect to PIXAERA_AUTH_AFTER_LOGIN_PAGE afterwards)
router.get('/auth_callback', pixaeraAuthClient.authCallback);

Besides these methods, pixara-auth-client also has a "me" function, to return user info (the info depends on the scope authorized by the user during login).

// Returns user info, according to scope
router.get('/me', pixaeraAuthClient.me);

a logout function

// Revokes user's tokens
router.get('/logout', pixaeraAuthClient.logout);

and a function to check user's permissions

// Check permission of user (returns status 204 if user has permission, 
// 403 if user is forbidden)
router.get("/permission/:permission", pixaeraAuthClient.permission);