The authn-service provides set of API tools and workflows to provide secure set of authentication methods from simple credential based authentication to advanced device or adaptive authentication.
Authentication As a Service
Authentication is the process by which clients of Cloudentity (users, applications, etc.) provide credentials to prove their identity.
Cloudentity Authentication Service exposes a variety of authentication schemes which support use-cases for different types of entities.
In most cases, successful authentication results in the creation of a new user session,
represented as a session token or adding some additional Authentication Events to current session resulting in session "upgrade".
For more details about Authentication Events please refer to documentation of Authentication Events Service.
note: user can have session but it does not always mean user is authenticated to call any API
as each Cloudentity API exposed via Cloudentity API Gateway is protected at least by Fully Authenticated Policy.
Fully Authenticated Policy defines a sequence of validations/requirements that a user/session must satisfy for authentication.
More details about default Fully Authenticated Policy config and its features and flexibility can be found
in documentation of Cloudentity TrUST Service.
Each authentication endpoint accepts device print so that user device can be recognize and assigned to user
for future usage in authentication and authorization policies.
For more information about device print recognition please refer to documentation of Cloudentity Device Service.
For building policies based on devices prints or relation between user and device please refer to
documentation of Cloudentity Authorization Service.
For each successful authentication and verification and every unsuccessful verification request an Event is emitted. Services like Cloudentity Risk Service listen to those events and uses them for example for building their session/user/IP/application knowledge base to calculate risk for those entities.
Detailed information about each API can be found in Swagger Documentation. Provided below is an example of authentication/verification mechanisms supported by Cloudentity Authentication Service.
Authentication
Below is the list of basic single factor authentication (1FA) flows that can be used to obtain user session in Cloudentity.
Identifier + Password Authentication
Authentication via a user’s identifier and password is the most basic form of authentication that Cloudentity provides.
Definition of identifier is flexible and by default means any self signed identifier (UID) or any Verified Mail or Verified Mobile.
More about user identifier can be found in documentation of Cloudentity User Service.
When a user is created, a password is specified along with the user identifier. In some flows the user password is not specified until the user is activated.
POST /authn/identifierpassword
{
"identifier": "string",
"password": "string",
"device": { // optional
"name": "string",
"type": "string",
"properties": {
"platform": {
"name": "string",
"version": "string"
},
"details": {}
}
}
}Identifier + Password Verification
This endpoint expose same logic as its authentication version but does not issue a session. It can be used for additional password verification for actions that requires extended authorization. It is mostly used internally by other microservices.
POST /authn/identifierpassword/verify
Identifier + TOTP Authentication
Authentication via a user’s identifier and time-based one-time password (TOTP).
For TOTP Cloudentity uses Google Authenticator. To configure TOTP for user please refer to Cloudentity User Service documentation.
POST /authn/identifiertotp
{
"identifier": "string",
"totpToken": "string",
"device": { // optional
"name": "string",
"type": "string",
"properties": {
"platform": {
"name": "string",
"version": "string"
},
"details": {}
}
}
}Extended Authentication
Once user has session it can pass additional authentication flows exposed by Cloudentity Authentication Service to increase identity assurance.
Most of those extended authentication verifications are requested by Authorization Policy Engine in Cloudentity Authorization Service.
Those flows may act as second factor authentication (2FA) methods if Fully Authentication Policy is configured to require
not only valid session but additionally any of followed verifications.
Below is the list of extended authentication methods:
Password Verification
User can provide its password and session token to prove password knowledge. Session must be valid and password must belong to user for whom session was issued.
TOTP Verification
User can provide valid TOTP code and session token to prove ownership of device with configured TOTP for that user. Session must be valid and TOTP code must be generated for user for whom session was generated.
OTP Verification
User can provide valid OTP code and session token to prove access to either email address or mobile number.
To get OTP code user must first request it using session token and choose one of the unverified or verified mail or mobile.
More about requesting OTP code and configuration of emails and mobiles can be found in documentation of Cloudentity User Service.
Session must be valid and OTP code must be send to user for whom session was generated.
KBA (Knowledge-Based Answers) Verification
User can provide response to previously requested KBA questions and session token to prove KBA knowledge.
Before user must request a challenge and system decides which questions must user answer to pass verification.
Challenge description and KBA setup can be found in documentation of Cloudentity User Service.
Once user gets the challenge and answers the questions system verifies if answers matches (case-insensitive) those used during KBA setup.
Session must be valid and KBA responses must match answers of a user for whom session was generated.