Authentication And Authorization

Introduction

The Authentication And Authorization (AAA) Service provides APIs that allow you to create users, authenticate their identity, and validate their access permissions to App and Platform Resources

1920

Functions provided by the AAA Service

The AAA Service facilitates the following actions:

User onboarding

A Platform User is an entity created in AAA Service that represents a person who interacts with Platform Apps and the OS1 Platform. Onboarding a User in another service, for example, the Participant Service, does not automatically onboard the User to the AAA Service. You must specifically onboard the User to the AAA Service to use the AAA service functionality.

Creating a User

To create a new User call the Create a user. endpoint. Note: For creating a User, it's required to provide firstName and any of email or primaryMobile number. If you provide primaryMobile number, countryCode & number are required.

MemberDescriptionValidationData type
emailThe email address of the user.pattern: ^([a-zA-Z0-9_\.\+-]+)@([\da-zA-Z0-9_\.-]+)\.([a-zA-Z\.]{2,6})$
nullable: false
minLength: 1
string
firstNameThe first name of the user. The value can't be null and it must be 1 to 36 characters in length.nullable: false
minLength: 1
maxLength: 36
string
lastNameThe last name of the user. The value can't be null and it must be 1 to 36nullable: false
minLength: 1
maxLength: 36
string
countryCodeCountry code for mobile number. The value can't be null and it must be 2 and 4 characters in length.nullable: false
pattern: ^\+(\d{1}\-)?(\d{1,3})$
maxLength: 4
minLength: 2
string
numberThe mobile number of the use. GET calls return a masked string in which only the last 4 digits of the phone number are in clearn text. The value can't be null and it must be 4 to 10 characters in length. You must specify a value for either email or primaryMobile. You can supply both.nullable: false
pattern: ^[0-9]{4,14}$
maxLength: 10
minLength: 4
string

Request bodies are specified in JSON format. The following shows example request body to create a User and to update a User.

{
    "email":"[email protected]",
    "firstName": "John",
    "lastName": "Doe",
    "primaryMobile": {
    "countryCode": "+91",
    "number": "1234567890"
  }
}
{
   "primaryMobile":{
      "countryCode":"+91",
      "number":"0987654321"
   }
}

After creating a User, uou can edit any attribute except for the tenantId.

User Attributes

Following user attributes can be saved as a part of user onboarding:

AttributeDescriptionRemarks
tenantIdTenant Identifier.
userIdSystem generated user identifier.
participantId
(Optional)
The Participant Identifier of the user as generated by the Participant Service.
usernameThe first, middle and last name of the User.Them middleName and lastName values are optional. If only the full name is available, it should be sent as firstName.
emailThe email address of the User.
Either an email address or primary mobile phone is required.
GET calls return a masked value that reveals the first two characters of the username part of the email and masks the remaining characters with an asterisk. The domain name part is not masked.
primaryMobilethe Primary mobile phone number with country code in JSON format.
Either an email address or primary mobile phone is required.
GET calls return the country code and the last 4 digits of the mobile number. The remaining charaters are masked.
secondaryMobile
(Optional)
The Secondary mobile phone number with country code in JSON format.
The secondary mobile number is only allowed if a primary mobile number is specified.
GET calls return the country code and the last 4 digits of the mobile number. The remaining charaters are masked.
allowSocialAuth
(Optional)
A Boolean value that specifies whether Google Login is allowed.

For example:

"allowSocialAuth": {
"google": true
}
Default value: False
allowSAMLAuth
(Optional)
A Boolean value that specifies whether SAML 2.0 Login is allowed.Default value: False
samlConnector
(Optional)
Named SAML 2.0 Connector.Required if allowSAMLAuth is set as True.
samlUserId
(Optional)
The identifier for the user in the SAML Identity Provider.Required if allowSAMLAuth is set to True.
isActiveA boolean value that indicates whether the user is temporarily deactivated. Users deactivated using this flag can be activated again by a user of the tenant (with the required role).When set to True, User login is allowed. When set to False, User login is not allowed and the User or User Group is archived.
isDeletedA Boolean value that specifies whether the user is permanently deactivated.When set to true, User login is not allowed

Manage User Groups

A Platform User Group is a collection of Users. A User Group allows a tenant to specify Roles that apply to all of the Users in the User Group. A User can be a part of multiple User Groups. User Groups cannot be nested. This means that they can contain only User entities and not other User Group entities.

Request bodies are specified in JSON format. The following shows example request bodies for the management of User Groups:

MemberDescriptionValidationData type
nameName of the group. Group name is unique for application.minLength: 2
maxLength: 50
pattern: ^[a-zA-Z]+(-[a-zA-Z]+)*$
string
descriptionDescription of the group.minLength: 2
maxLength: 50
string
{
  "name": "FMOperation",
  "description": "Group of users responsible for First Mile Operations"
}
{
   "description":"Group description",
   "users":{
      "userIds":[
         "503b235b-1378-4cb7-bc40-976cb7ceea51",
         "9efc9aab-c55f-44e7-a01c-790e5d022945"
      ],
      "membership":true
   },
   "isActive":true,
   "isDeleted":true
}
{
   "roles":[
      "Platform:Role:platform:app:dispatch-api:admin"
   ],
   "users":[
      "503b235b-1378-4cb7-bc40-976cb7ceea51",
      "9efc9aab-c55f-44e7-a01c-790e5d022945"
   ],
   "groupId":"platform:group:DispachAdmin",
   "name":"DispachAdmin",
   "description":"Dispatch Admin Group",
   "isActive":true
}

You can rename a user group without changing the Roles attached to the user group.

The following methods are available for working with User Groups:

User Group Attributes

User Groups are specified by a unique fully qualified name and have the following attributes:

AttributesDescriptionRemarks
tenantIdTenant Identifier.
groupIdSystem generated fully qualified name of the user group.
nameOne word name for the User Group.The name must be unique across user groups of a tenant.
rolesA list of roles mapped to the users belonging to the group.
usersA list of user IDs present in the group.
isDeletedA Boolean value that indicates whether the user group is permanently deactivated.Set to True to indicate that the User Group is deleted and archived.
Default value is False.

User Authentication Methods

The Authentication And Authorization (AAA) Service supports the following four methods for user authentication:

  • Primary Mobile Number and OTP
  • Email Address and OTP
  • Social Login (Google, Github, etc.)
  • SAML 2.0 Authentication (configurable for any SAML 2.0 compatible external identity provider)

The tenant has the option to enable or disable Google Login and SAML 2.0 Authentication at the user level (it is disabled by default). Moreover, OTP-based login can be enabled for all users by default and cannot be disabled.

One Time Password

One Time Password (OTP) is a unique 6-digit value and is unique for each OTP request (combination of user, tenant, and request ID). After the OTP is issued, it will expire after 10 minutes from the issue time, or on a successful login with the OTP, whichever occurs first.

The AAA service supports a maximum of 3 requests to resend the OTP. The minimum time gap between the last OTP sent time and the request to resend OTP is 30 seconds.

The Platform enables OTP and email login authentication methods by default.

Social Login

If enabled, Google Login only works only if an email address is specified in the AAA service for the User.

To establish a Google Login connection, call the Create a social connection. endpoint.

The following request body shows a sample API payload to create a social connection:

MemberDescriptionValidationValidation
connectionNameUnique name of the connection.minLength: 2
maxLength: 50
pattern: ^[a-zA-Z]+(-[a-zA-Z]+)*$
string
connectionClientIdClient ID of the social application.string
connectionClientSecretClient Secret of the social application.string
{
   "connectionName":"google-demo-connection",
   "connectionClientId":"",//mention the connection client ID
   "connectionClientSecret":""//mention the connection client secret
}

SAML 2.0 Authentication

The AAA Service is set up as a Service Provider (SP) only, and not as an Identity Provider (IdP). On successful SAML 2.0 authentication, AAA Service issues an Authentication Token for the user.

Although the AAA Service doesn't act as an IdP, Users have to be pre-onboarded to AAA Service for authorization purposes.

The tenant can configure their own SAML 2.0 connector. Moreover, they can specify which attributes of the User (returned by SAML IdP) are matched with the SAML User Identifier provided in the AAA Service for successful Platform Authentication.

To establish a SAML connection, call Create a SAML connection. endpoint.

The following request body shows a sample API payload to create a connection:

MemberDescriptionValidationData type
connectionNameUnique name of the connection.minLength: 2
maxLength: 50
pattern: ^[a-zA-Z]+(-[a-zA-Z]+)*$
string
signInEndpoint(optional)Sign In endpoint of the SAML connection.string
signOutEndpoint(optional)Sign Out endpoint of the SAML connection.string
publicKeyCertificateThe certificate required for SAML connection should be of x509Cert format.string
{
  "connectionName": "string",
  "signInEndpoint": "string",
  "signOutEndpoint": "string",
  "publicKeyCertificate": "string"
}

Authentication Token

On successful authentication, the AAA Service issues a unique JWT (RFC-7519) as an Authentication Token for the User. The Authentication Token is signed using a public/private key pair using RSA. It is valid for 10 minutes and it is invalidated if the user is deactivated or removed from the AAA Service.

The Authentication Token contains the following claims:

Claim NameDescriptionRemarks
issIssuerAlways fixed for a tenant. Signifies issuer of token
subSubjectIdentifies the User for whom the token is issued.
audAudienceApps for which the access is granted
expExpiryExpiration date time after which this token will be invalid.
iatIssued AtThe date-time at which the token was issued.

Refresh Token

On successful authentication, along with the Authentication Token, AAA Service also issues a unique JWT (RFC-7519) as a Refresh Token for the Authentication Token.

The Refresh Token is signed with a public/private key pair using RSA (the same key that is used for the Authentication Token). The token is valid for 12 hours and and it is invalidated if the user is deactivated or removed from the AAA Service.

If the Authentication Token has expired but the Refresh Token is still valid, a new Authentication Token can be obtained by sending the expired Authentication Token and the Refresh Token to AAA Service. The new Authentication Token is identical to the original Authentication Token except for the values of iat and exp claims.

The Refresh Token contains the following registered claims:

Resources, Permissions, and Roles

Resources

A Platform Resource is a generic name representation of any entity in a Platform Registered App on which action(s) can be performed by users or other services and apps.

For Platform Registered Apps, the resources are created in the AAA Services when the app is mapped to a tenant. They are created as per the definition in a YAML file named access-control.yaml provided by each app. These cannot be edited manually by any user of the tenant.

Read APIs are provided for reading a resource by resource ID and reading all resources corresponding to a service or app (appId).

Permissions

A Platform Permission is a generic name representation of authorization to perform a specific action on a defined Platform Resource. The authorized action is specified in the list of allowed actions of the Platform Resource.

For Platform Registered Apps, the permissions are created in the AAA Service when the app is mapped to a tenant. They are created as per the definition in a YAML file named access-control.yaml that is provided by each app. These cannot be edited manually by any user of the tenant.

Permissions are created in AAA Service automatically when resources for a service or app are defined in the AAA Service. Only one Permission is created for each combination of Resource and HTTP Methods.

Read APIs are provided to get:

  • The permission as specified by the value of permissionId
  • To read all of the resources identified the value that corresponds to a resourceId
  • To read all resources corresponding to a service/app as specified by the value of appId
  • To read the list of roles to which this permission is granted

Roles

A Platform Role is a generic named representation of a set of permissions to access resources of a specific app or service. A Role is specific to an application.

Roles are mapped to a User Group or app. One or more Roles can be mapped to a User Group or app. They cannot be granted directly to a User. Granting a Role to a User Group grants the role to all Users in the group.

Creating Roles

To create a Role, call the Create app role endpoint and then pass the following parameters in the request body:

MemberDescriptionValidationData type
roleNameName of the role (each role should be assigned with a name).maxLength: 50
pattern: ^[a-zA-Z]+(-[a-zA-Z]+)*$
string
descriptionDescription of the role.nullable: false
minLength: 2
maxLength: 50
pattern: ^([a-zA-Z])([a-zA-Z0-9,\s]*)$
string
securityLevel Security level of the the role. Default is OPEN. Used to restrict the access level for the role.default: OPEN
Valid values: SENSITIVE, RESTRICTED, OPEN
string
permissionsIDs of permission that are attached to this role.pattern: ^([a-zA-Z])([-:a-zA-Z0-9]*)$string
canGrantToApps Boolean value indicates if the role can be granted to other apps/services.default: falseboolean
canGrantToUsers Boolean value indicates if the Role can be granted to user groups.default: trueboolean

The following shows sample request bodies for creating and updating a Role:

{
   "roleName":"admin",
   "description":"Admin role of the App",
   "securityLevel": "OPEN",
   "permissions":[
      "platform:app:app1:createAPI:post",
      "platform:app:app1:deleteAPI:delete",
      "platform:app:app1:getAPI:get",
      "platform:app:app1:updateAPI:put"
   ],
  "canGrantToApps": false,
  "canGrantToUsers": true
}
{
   "description":"Admin role of the user read permission",
   "assignPermissions":true,
   "permissions":[
      "user:read"
   ],
  "canGrantToApps": false,
  "canGrantToUsers": true
}

Type of Roles

The platform has two kinds of Roles:

  • Platform Managed Roles
    These are roles created/managed by CoreOS Services and Apps. These roles cannot be edited by any user of the tenant. These roles and their mapping to user groups, apps, or services, get automatically removed when the app/service that created the role is removed for the tenant.

    When a service or app is deployed, the installation process reads the access-control.yaml file, included in the App/Service repository, and correspondingly creates the following:

    • Resources & Permissions offered by the Service/App.
    • Roles offered by the Service/App.
    • Roles required by the installed App to access resources of other Services or Apps.
  • Tenant Managed Roles
    These are Roles created by the Tenant. These roles provide more granularity compared to Platform Managed Roles.

Role Attributes

Roles are specified by a unique fully qualified name and their definition includes the following attributes:

AttributeDescriptionRemarks
tenantIdUnique identifier of the tenant.
appIdThe App to which permissions in the Role belong.A role can contain only permissions for resources that belong to given App.
roleIdA unique, system-generated fully qualified name for the Role.Format: Platform:Role:<appId>:<roleName>.
For example:
Platform:Role:FMS:FleetManager
OR
Platform:Role:FaaS:FaaSAdmin
roleNameA unique name for the Role in the the App specified by appId.Max: 50 characters.
Names can contain only alphabetic characters and hyphines. Names should not start with a hyphen.
permissionsList of Permission Names attached to this Role.
managedByThis field contains the appId of the App/service that created the Role or tenantId if the role was created by a tenant.Users of a tenant cannot edit or remove Roles managed by Apps or services.
canGrantToUsersA boolean value that indicates whether this Role can be granted to User Groups.True if the Role can be granted to User Groups; Otherwise False.
Default value: True
canGrantToAppsA boolean value that indicates whether this Role can be granted to Apss.True if the Role can be granted to Apps; Otherwise False.
Default value: False
isActiveA Boolean value that indicates whether the Role is active. Deactivated Roles can be activated again by a user of the Tenant.True if the Role is active; Otherwise False.
isDeletedA Boolean value that indicates whether the Role is permanently deactivated and will be archived.True if the Role is permenatly deactivated; Otherwise False.

Role-Based Access Control (RBAC)

Role-based access control (RBAC) is a method of restricting access based on the roles of individual users or apps within a tenant.

User Access:
Access can be provided to users by assigning roles to a user group. Roles offered by an App can be mapped to one or more User Groups.

App Access:
Roles are assigned to an app for authenticating apps when they call another web service. Roles can be mapped to one or more Apps or Services. More than one Role can be mapped to an App or Service.

Access Token and Authorization Process

User Access Token

On successful user authentication, a browser/mobile app requests Authorization API of AAA Service with appDomain, appId, and Authentication Token in HTTP Headers.

After verifying the authentication token, AAA Service issues a unique JWT (RFC-7519) as an Access Token that is valid for the unique combination of browser/mobile app, the tenant associated with the appDomain, and the Authentication Token.

📘

Access Token Validity

The Access Token has a validity of 24 hours.

User Authentication & Authorization (UI to Service)

Once the user is successfully logged in, all REST API requests to backend services include the following HTTP Headers:

  • X-COREOS-ACCESS: Authorization Token
  • X-COREOS-TID: Tenant ID
  • X-COREOS-REQUEST-ID: Request ID
  • X-COREOS-USERINFO: Userinfo

Service to Service Authentication & Authorization

For Service-to-Service communication, a client credentials grant is implemented for authentication. AAA service exposes an API to obtain a token for service communication, and this token is required to be sent as the header in all API communications to other services. The authorization is determined by the roles-required section in the access-control.yaml file.

All Service-to-Service REST API Requests include the following headers:

  • X-COREOS-REQUEST-ID: Request ID
  • X-COREOS-TID: Tenant ID
MemberDescriptionValidationData type
clientIdYour application's Client ID.nullable: falsestring
clientSecretYour application's Client Secret.nullable: falsestring
audienceApp ID for which you need token. Not required in keycloak API calls.nullable: falsestring
{
  "clientId": "string",
  "clientSecret": "string",
  "audience": "string"
}