Skip to content

Authorization

Jump to bottom
Stephen Hurwit edited this page Apr 5, 2022 · 6 revisions

Authorization

The Core Building Block (Core BB) enables authorization by providing authenticated users with tokens that can be validated by other services in the Rokwire ecosystem. These tokens are JSON Web Tokens (JWTs) that encode the relevant information about the user needed to determine what resources they should be able to access.

The public key of the keypair used to sign these tokens is published publicly by the Core BB so that any relying service may easily access this key and use it to validate a token that it received.

Token Types

There are several types of tokens that are provided by the Core BB.

  • Access: Access tokens are JWTs populated with information necessary to authorize access to resources throughout the system.
    • User: A User Access Token can be generated through the user Sign In Flow and Refresh Flow. These tokens provide full access to a user's data and therefore MUST ONLY be sent to other first-party Rokwire Building Blocks/services.
    • Scoped: A Scoped Access Token may be generated to grant limited authorization to a specific third-party service through the user Scoped Token Flow. These tokens MUST ONLY be sent to the specified third-party service and other first-party Rokwire Building Blocks/services.
    • Service: Service Access Tokens can be generated through the Service Token flow to allow services to authorize each other.
  • Refresh: Refresh tokens are opaque tokens that can be generated along with a Login Session to enable applications to retrieve fresh access tokens without user interaction. Upon use, these tokens will be rotated and the new refresh token will be returned. These tokens MUST ONLY be sent to the Core BB.
  • CSRF: CSRF tokens are JWTs populated with the minimum information necessary to verify a match with the Access Token when accessing resources through a web application where CSRF prevention is a concern.

The standard token claims that will be available are as follows:

type Claims struct {
	// Required Standard Claims: sub, aud, exp, iat
	jwt.StandardClaims
	OrgID         string `json:"org_id" validate:"required"`   
	AppID         string `json:"app_id"`                       
	SessionID     string `json:"session_id"`                   
	Purpose       string `json:"purpose" validate:"required"`  
	AuthType      string `json:"auth_type" validate:"required"`
	Permissions   string `json:"permissions"`  
	Scope         string `json:"scope"`        
	Anonymous     bool   `json:"anonymous"`    
	Authenticated bool   `json:"authenticated"`
	Service       bool   `json:"service"`    
	FirstParty    bool   `json:"first_party"`
	Admin         bool   `json:"admin"` 
	System        bool   `json:"system"`

	Name        string            `json:"name,omitempty"`
	Email       string            `json:"email,omitempty"`
	Phone       string            `json:"phone,omitempty"`

	ExternalIDs map[string]string `json:"external_ids,omitempty"`

	UID string `json:"uid,omitempty"`
}

Standard Claims

The following standard JWT claims are used and guaranteed to be populated.

Name Key Type Description
Subject sub string The unique identifier of the entity the token was issued for. This must be used as the entity's primary ID. This will be populated with the entity's Account ID.
Audience aud string (comma-separated) An identifier for the intended recipient of the token. The "rokwire" audience is reserved and indicates that the token should be accepted by all first-party Rokwire services, such as Building Blocks. Otherwise, a specific Service ID may be provided. The audience will be encoded as a comma-separated string in the case that the token is intended for use by multiple services.
Expiration Time exp DateTime The time after which the token is expired and no longer valid. This claim will be a datetime string encoded in the RFC 3339 format.
Issued At iat DateTime The time at which the token was issued. This claim can be used to calculate the age of the token. It will be a datetime string encoded in the RFC 3339 format.

Custom Claims

The following additional custom claims are available in the token. The "Required" field indicates whether or not the claim will always be specified in Access Tokens.

Name Key Type Required Description
Organization ID org_id string false The ID of the Organization that the entity's account belongs to. This is the primary identifier used for multi-tenancy throughout the system. When storing or retrieving user data, this ID must be associated to maintain appropriate data isolation between system tenants. This claim may be empty for Service Accounts if the account spans across all organizations.
Application ID app_id string false The ID of the Application that the entity's account belongs to. This claim may be empty for Service Accounts if the account spans across all applications.
Session ID session_id string false The ID of the Login Session that was used to generate this token. This claim may be empty if the token is not associated with a login session.
Purpose purpose string true The purpose of the token. This may either be "access" for Access Tokens or "csrf" for CSRF tokens.
Auth Type auth_type string true The Authentication Type used to generate this token/login session.
Permissions permissions string (comma-separated) false A comma-separated string that lists the Permissions granted to this entity within the specified application and organization. This claim may be empty if no permissions are granted.
Scope scope string (comma-separated) false A comma-separated string that lists the Scopes that this token can be used to access. This claim may be empty if no scopes are granted.
Anonymous anonymous boolean true A flag indicating that the token was generated for an Anonymous User. In this case, the "sub" claim will contain the user's Anonymous ID
Authenticated authenticated boolean true A flag indicating that this token was generated in response to an authentication request, as opposed to a refresh request.
Service service boolean true A flag indicating that this token was generated for a Service Account.
First-Party first_party boolean true A flag indicating that this token was generated for use by first-party services. If the "service" flag is set, this indicates that the service is a first-party service (eg. Building Block). Otherwise, this indicates that the token is a Scoped Token for use by a third-party service.
Admin admin boolean true A flag indicating that this token was generated for an Admin App user.
System system boolean true A flag indicating that this token was generated for a System Admin.
External IDs external_ids map (string : string) false An object containing user's External IDs. These IDs should only be used for the purpose of communicating with external systems. Internally the "sub" claim should be used to identify the user instead.
UID uid string false The user identifier associated with the specified Auth Type. For example, if the Auth Type is email, this will be the user's email address.

Personal Information Claims

Claims containing personal info on the user for display purposes. These claims MUST NOT be used as an identifier for the user or shared with any third-party entities.

Name Key Type Required Description
Name name string false The user's preferred display name.
Email email string false The user's primary email address.
Phone phone string false The user's primary phone number.

Scopes

Scopes are the fundamental unit used to define what actions and resources an entity is authorized to access on behalf of a user. Scopes are structured in the following format {service_id}:{resource}:{operation} where:

  • service_id - The Service ID of the service that the scope applies to. Eg. the core Service ID indicates that this scope applies for the Core BB.
  • resource - The resource that is covered by the scope. Eg. the email resource may indicate that this scope applies to the user's email address.
  • operation - The operation that is permitted on the specified resource. Eg. the read operation may indicate that the scope authorizes read access.

Scopes are granted by a user to a service for to enable the service to provide them with some functionality in exchange for limited access to their data in the Rokwire ecosystem. They can do this through the Scoped Token Flow

Note: While Permissions are used to define which administrative actions can be taken, scopes indicate what actions may be taken on a user's behalf.

Admin

Admin authorization is managed through the permission, group, and role concepts. Admin accounts may be assigned any combination of these elements to allow for flexible and easy management of privileges across the system.

Permissions

The base unit of admin authorization in the Rokwire ecosystem is the permission. Permissions are defined and used by Rokwire services to authorize administrative actions.

Permissions must be:

  • Unique - Permissions should be globally unique throughout the system. Each permission must be associated with a single implementing service. Two services cannot define a permission with the same name.
  • Static - The meaning of a permission should remain unchanged once it is defined. Removing access to resources or operations from a permission is likely to break existing workflows. Adding new resources or operations to a permission can result in users gaining more access than originally intended.
  • Global - Permissions exist outside of the multi-tenancy model and are globally defined across all organizations and applications. This is because permissions are defined by the services and must be consistent throughout the system.
  • Grantable - Each permission contains a list of approved assigners. Only admins with one of these assigner permissions will be allowed to grant the permission.

Aside from the requirements listed above, the exact definition of a permission is up to the implementing service, however the following guidelines are recommended:

Permissions should be:

  • Specific - Since permissions are the fundamental authorization unit, they should be defined for a very specific purpose. It is easy to manage multiple permissions once they are defined using roles and groups, but it will require code changes to split up a permission that was defined too broadly. Usually this will mean that each permission should be associated with a particular:
    • Resource - Permissions should not be shared between endpoints that handle different components of the system. For example, the /admin/roles endpoint should have a separate permission from the /admin/groups endpoint.
    • Operation - Separate permissions should be defined for read, write, and delete operations. For example, the PUT and POST operations for each endpoint should have a separate permission from the GET operation and the DELETE operation. A separate all_ permission can be created to allow all operations to be performed (in addition to the separate get_, update_, delete_ permissions) if all of the operations are commonly assigned together.
  • Descriptive - Permission names should clearly and concisely describe the actions that they allow the user to take. For example, the permission to grant read access to the "roles" resource should be named get_roles.

Using the guidelines described above, the following permissions should be defined for the /admin/roles and /admin/groups endpoints should use the following permissions:

  • get_roles - GET /admin/roles

  • update_roles - PUT, POST /admin/roles

  • delete_roles- DELETE /admin/roles

  • all_roles- GET, PUT, POST, DELETE /admin/roles

  • get_groups - GET /admin/groups

  • update_groups - PUT, POST /admin/groups

  • delete_groups - DELETE /admin/groups

  • all_groups- GET, PUT, POST, DELETE /admin/groups

Roles

A role is a collection of permissions that can be created to easily assign and manage user access. It can be defined and managed per application, organization pair to enable certain users to perform a specific administrative job within that App/Org. Each role must be given a name and description that clearly conveys its intended purpose and use. Roles may be managed at the system level to prevent organization admins from modifying them.

Groups

A group is a collection of users that share the same roles and permissions. It can be defined and managed per application, organization pair to allow admins to easily view and manage users with similar responsibilities and privileges. Each group must be given a name that clearly conveys its intended purpose and use. Groups may be managed at the system level to prevent organization admins from modifying them.

Auth Flows

There are several different process flows that must be followed to authenticate and authorize entities in the system.

Sign In Flow

The most basic auth flow in the system is the Sign In Flow. This is the flow that users will take when establishing a new Login Session. To do so, the user must authenticate using an Auth Type that has previously been associated with their account through the /auth/login endpoint. The response of a successful authentication will contain the user's Account information, an Access Token, and a Refresh Token if enabled.

The Sign In Flow may complete unsuccessfully in several situations. If the provided credentials do not match with an existing account, the user must Sign Up before they can login. If the user has not yet Verified the auth type they attempted to use, they must do so before continuing. If the provided credentials are not valid, an authentication error will be returned.

Sign Up Flow

When a new user would like to create an Account for the first time, they must perfrom the Sign Up Flow. This will generate a new account record in the system and initiate Verification if necessary. This flow is also initiated through the /auth/login endpoint, however some additional parameters may be required when compared to the Sign In Flow depending on the Auth Type.

Upon comlpeting the sign up request, the user must perform any necessary verification, then they will be able to follow the Sign In Flow to login to the account and receive their access token.

If the provided credentials already match with an existing account, an error will be returned.

Refresh Flow

The Refresh Flow allows a client application to retrieve a new Access Token once the current access token expires without any user interaction. This flow may be disabled for some App Types. If it is enabled, the client will receive a Refresh Token along with the access token. To initiate the refresh flow, this refresh token is sent to the /services/auth/refresh endpoint.

Anonymous Flow

For applications that do not require user authentication to access some features, the Anonymous Flow can be supported. This flow allows users to receive Access Token without creating an account or providing any personal data. For this flow a request can be made to the /auth/login endpoint using the "anonymous" Auth Type.

This request will return an Anonymous ID that can be stored in the client. When making future requests to login, this ID can be provided to maintain consistency.

Warning: This Anonymous ID is not verified or authenticated, so there is no guarantee that a given Anonymous ID will always be associated with the same user. There is also no guarantee that the same user will always have the same Anonymous ID. For example, clearning a device cache, reinstalling a client application, or using a new device could all result in a new Anonymous ID.

Scoped Flow

The Scoped Flow is intended for users to authorize Third-Party Services to access their data. In order to use this flow, the Sign In Flow must be performed first to retrieve a User Access Token. This token can then be sent to the /services/auth/authorize-service endpoint to authorize a specific service with specific Scopes and receive a Scoped Access Token that can be shared with that service.

Upon receiving the Scoped Access Token, the service can then verify the token, then pass it along to other Rokwire Building Blocks to retrieve information about the user that has been approved.

Service Flow

To authorize requests between Services, the Service Flow can be used to generate a Service Access Token for a Service Account.

Login Sessions

Clone this wiki locally