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
Header
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 |
|
|
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 |
|
|