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 functions provided by the aaa service the aaa service facilitates the following actions authentication and authorization /#user onboarding authentication and authorization /#manage user groups authentication and authorization /#user authentication methods authentication and authorization /#resources permissions and roles authentication and authorization /#permissions authentication and authorization /#roles authentication and authorization /#access token and authorization process limits limits please note that aaa api requests that exceed the 375kb size limit will be rejected avoid passing large payloads to prevent exceeding this limit 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 the user must be specifically onboarded to the aaa service for using its service functionality creating a user to create a new user call the create user docid\ sgvk7ps00ptaervkvqn1u endpoint note for creating a user, firstname with any one of the email or a primarymobile number are required if providing a primarymobile number then countrycode & number are mandatory fields true false 0,192false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type request bodies are specified in json format the following shows an example request body to create a user and to update a user update user { "primarymobile" { "countrycode" "+1", "number" "5551234567" } } create user { "email" "johndoe\@gmail com", "firstname" "john", "lastname" "doe", "primarymobile" { "countrycode" "+91", "number" "1234567890" } } after creating a user, you can edit any attribute except for the tenantid user attributes the following user attributes can be saved as a part of user onboarding true falsefalse left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type 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 example shows request bodies for the management of user groups true falsefalse left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type create groups { "name" "fmoperation", "description" "group of users responsible for first mile operations" } update groups { "description" "group description", "users" { "userids" \[ "503b235b 1378 4cb7 bc40 976cb7ceea51", "9efc9aab c55f 44e7 a01c 790e5d022945" ], "membership"\ true }, "isactive"\ true, "isdeleted"\ true } get group details "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 get all group docid\ gjy8c twifydnu8gm86gt get groups docid r3wlddtxobdle iig9ir get all group docid\ gjy8c twifydnu8gm86gt user group attributes user groups are specified by a unique fully qualified name and have the following attributes true falsefalse left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type 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 a 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 within 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 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 true falsefalse left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type { "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 saml connection endpoint the following request body shows a sample api payload to create a connection true falsefalse left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type { "connectionname" "string", "signinendpoint" "string", "signoutendpoint" "string", "publickeycertificate" "string" } authentication token on successful authentication, the aaa service issues a unique jwt ( rfc 7519 https //datatracker ietf org/doc/html/rfc7519 ) 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 invalid in case the user is deactivated or removed from the aaa service the authentication token contains the following claims true falsefalse left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type on successful authentication, along with the authentication token, aaa service also issues a unique jwt ( rfc 7519 https //datatracker ietf org/doc/html/rfc7519 ) as a refresh token for the authentication token 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 is specified by the value of permissionid to read all of the resources identified to 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 https //app archbee com/public/preview 9m3sxlb43kjczevknejvn/preview wjq9ofmlij3 emss5s7w4 endpoint and then pass the following parameters in the request body true falsefalse left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type the following shows sample request bodies for creating and updating a role update user { "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 } create user { "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 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 true falsefalse left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type 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 the 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 https //datatracker ietf org/doc/html/rfc7519 ) 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 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 should 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 true falsefalse left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type { "clientid" "string", "clientsecret" "string", "audience" "string" }