@atlas-engine/iamdeprecated

Contains the AtlasEngine's IAM components.

Usage no npm install needed!

<script type="module">
  import atlasEngineIam from 'https://cdn.skypack.dev/@atlas-engine/iam';
</script>

README

Identity and Access Management - IAM

Contains the implementation of the IAM contracts interfaces.

Purpose

The AtlasEngine uses IAM for performing authorization related requests. The contracts found in @atlas-engine/iam_contracts provide a template for this.

Two services are available:

  1. IamService

    Used for interaction with the authority. ensureHasClaim allows to check if a given identity has a given claim.

  2. IdentityService

    A service that knows how to transform a given token (e.g. JWT) to an identity that the authority can understand.

Usage Example:

The easiest way to get familiar with the idea is to look at an example; this will illustrate the use of and the interaction between the IamService and the IdentityService:

const identityService = new IdentityService();
const iamService = new IAMService();

// Get the identity for a given JWT token.
const token = 'Place JWT Token here';
const identity = identityService.getIdentity(token);

// Will result in:
//
// 1. An UnauthorizedError HTTP Status code, if the identity is not logged in at the authority.
// 2. A ForbiddenError HTTP Status code, if the identity does not have the given claim.
// 3. Nothing, if the identity has the given claim.
iamService.ensureHasClaim(identity, 'allowd_to_read_data');

// Place protected code here.
(...)

Usage

Using IAM is simple. You can use ensureHasClaim to verify any claim for any identity.

You'll get one of the following results:

  1. Get an Unauthorized Error

    A 401 will be thrown, if the identity is not known to the authority or the token is invalid/expired/etc.

  2. Get a Forbidden Error

    A 403 will be thrown, if the given identity does not have the given claim.

  3. Get Nothing, if the identity has the given claim.

    A 204, which indicates that the identity has the given claim.

Configuration

The IamService needs some configurations:

  • baseUrl: The base address at which the authority can be reached
  • claimUrl: The url to use for claim checks
  • allowAnonymousRootAccess: If true: Allow usage of the dummy token. Defaults to false.
  • cache: A set of configurations for the claim check cache
    • enabled: If true, the result of each unique claim check for each token will be cached
    • cacheLifetimeInSeconds: The time that a claim check result should be cached. Set to 0 to store results indefinetly
    • cleanupIntervalInSeconds: The interval in which the cache should clean intself up. Use 0 to disable this behaviour.

Disabling Claim Checks

You can disable claim checks altogether, by starting the Atlas Engine with the DISABLE_CLAIM_CHECKS environment parameter.

Example: DISABLE_CLAIM_CHECKS=true atlas-engine.

Be advised: Disabling claim checks entirely will allow any and all users to do whatever they want! You should only use this for testing- or debugging- purposes!