masstack

Overview

Introduction

MasStack follows OAuth standard practices for authorizing both applications and final users. It is very important to understand the differences between each method to make sure the proper method is used in each case. Our APIs and infrastructure are carefully monitored to make sure we comply with our security and privacy policies.

Authentication flows can be differentiated depending on two scenarios:

  • if the client has a services account.
  • if the client has credentials available.

In this guide we will cover the first situation. Next versions will improve more functionalities and cover the other scenarios. If you have a different use case or wish to use an alternative method, please contact your MasStack representative.

The first step of Authentication is to know how to obtain and what are the parts that compose all the request.

JWT

Definition

JWT stands for JSON Web Token. It is an open standard that allows to securely transmit information between parties. This information is digitally signed using either secrets or public/private keys so it can be verified and trusted as an authorization method. Although JWTs can be used for other use cases as well, we will mainly focus on the authorization side for accessing MasStack . For more detailed information on JWTs, check out jwt.io.

JWT Structure

For certain use cases, you will need to know the structure of a JWT and how to access key information within it. In its compact form, a JWT has three different parts separated by dots:

  • Header = x
  • Payload = y
  • Signature = z

xxxx.yyyy.zzzz

The header normally consists of three parts:

Name Description
alg Represents the signing algorithm being used. In MasStack
we use RS256 as our signing algorithm.
typ The type of token, which in our case is just plainly JWT.
kid Specify your service account’s private key ID. You can find this value in the private_key_id field of your service account JSON file 
1
2
3
4
5

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "5fb929a9-fb19-47cc-8eb8-10f6f39079a2"
}

Payload

Another part of the token is the payload which contains the claims. Claims are statements that define the main entity (this can be either a final user or a machine-to-machine system). These claims are used within MasStack to identify the entities using the product and restrict access to certain information to applications.

Name Description
sub username with the user has done login
spreferred_username username with the user has done login complying with the regular expression: ^([a-z0-9]+[a-z0-9-.]*[a-z0-9]+)$
iss Issuer of the application who created and signed this token
iat Issued at (seconds since Unix epoch)
exp Expiration time (seconds since Unix epoch)
tenant Tenant ID to set customer’s context. DEPRECATED
groups Groups to which the user belongs. OPTIONAL
roles Roles assigned to the users. OPTIONAL
app_metadata_roles Custom data set of the app. For example in login by uuid, in this section will be the custom roles of the app. OPTIONAL
aud Audience. Who or What the token is intended for.
scope NOT USE FOR THE MOMENT
cid internal code. No public
tid internal code. No public
family_name OPTIONAL. Only with active directory provider
given_name OPTIONAL. Only with active directory provider
name OPTIONAL. Only with active directory provider 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

{
  "iss": "https://authn.masstack.com",
  "aud": "application@EzmMbi2j48FaIGl1yyEK.auth.masmovil.com",
  "exp": 1608199225,
  "iat": 1608195625,
  "scope": "api:everything",
  "tenant": "2",
  "sub": "666111333",
  "name": "John Doe",
  "admin": true

}
Overview