Whenever any user logs an authorization token, a refresh token is generated for the user. Using the auth token the client can make rest API calls to the server to fetch data. The auth token has an expiry period. Once the authorization token expires, it cannot be used to make API calls. The client has to generate a new authorization token. This is done by authenticating the refresh token with the server which then generates and sends a new authorization token to the client. The refresh token avoids the need for the client to log in again whenever the authorization token expires.
Refresh token also has an expiry period and once it gets expired it cannot be used to generate new authorization tokens. The user has to log in again to get a new pair of authorization tokens and refresh tokens. Generally, the duration before the expiry of the refresh token is more as compared to that of authorization tokens. If the user logs out of the account both authorization tokens and refresh tokens become invalid.
Variables to configure expiry time:
Param | Description |
---|---|
API | Description |
---|---|
access.token.validity.in.minutes
Duration in minutes for which the authorization token is valid
refresh.token.validity.in.minutes
Duration in minutes for which the refresh token is valid
/user/oauth/token
Used to start the session by generating Auth token and refresh token from username and password using grant_type as password. The same API can be used to generate new auth token from refresh token by using grant_type as refresh_token and sending the refresh token with key refresh_token
/user/_logout
This API is used to end the session. The access token and refresh token will become invalid once this API is called. Auth token is sent as param in the API call
Configure user data management services
User service is responsible for user data management and providing functionality to login and logout into the DIGIT system
Before you proceed with the configuration, make sure the following pre-requisites are met
Java 17
Encryption and MDMS services are running
PostgreSQL server is running
Redis is running
Store, update and search user data
Provide Authentication
Provide login and logout functionality into the DIGIT platform
Store user data PIIs in encrypted form
Setup the latest version of egov-enc-service and egov-mdms- service
Deploy the latest version of egov-user service
Note: This video will give you an idea of how to deploy any Digit-service. Further you can find the latest builds for each service in out latest release document here.
Add role-action mapping for APIs
Note : This is a sample JSON file containing role-action mapping , If you don't have any of the master data setup yet you can you this to create on for you and then add all these files and start making changed in your repo.
The following application properties file in user service are configurable.
User data management and functionality to log in and log out into the DIGIT system using OTP and password.
Providing the following functionalities to citizen and employee-type users
Employee:
User registration
Search user
Update user details
Forgot password
Change password
User role mapping(Single ULB to multiple roles)
Enable employees to login into the DIGIT system based on a password.
Citizen:
Create user
Update user
Search user
User registration using OTP
OTP based login
To integrate, the host of egov-user should be overwritten in the helm chart.
Use /citizen/_create
endpoint for creating users into the system. This endpoint requires the user to validate his mobile number using OTP. First, the OTP is sent to the user's mobile number and then the OTP is sent as otpReference
in the request body.
Use /v1/_search
and /_search
endpoints to search users in the system depending on various search parameters.
Use /profile/_update
for updating the user profile. The user is validated (either through OTP-based validation or password validation) when this API is called.
/users/_createnovalidate
and /users/_updatenovalidate
are endpoints to create user data into the system without any validations (no OTP or password required). They should be strictly used only for creating/updating users internally and should not be exposed outside.
Forgot password: In case the user forgets the password it can be reset by first calling /user-otp/v1/_send
which generates and sends OTP to the employee’s mobile number. The password is then updated using this OTP by calling the API /password/nologin/_update
in which a new password along with the OTP is sent.
Use /password/_update
to update the existing password by logging in. Both old and new passwords are sent to the request body. Details of the API can be found in the attached swagger documentation.
Use /user/oauth/token
for generating tokens, /_logout
for logout and /_details
for getting user information from the token.
Multi-Tenant User: The multi-tenant user functionality allows users to perform actions across multiple ULBs. For example, employees belonging to Amritsar can perform the role of say Trade License Approver for Jalandhar by assigning them the tenant-level role of tenantId pb.jalandhar.
Following is an example of the user:
If an employee has a role with statelevel tenantId
they can perform actions corresponding to that role across all tenants.
Refresh Token: Whenever the /user/oauth/token
is called to generate the access_token
along with access_token,
one more token is generated called refresh_token
. The refresh token is used to generate a new access_token
whenever the existing one expires. Till the time the refresh token is valid, users will not have to log in even if their access_token
expires since this is generated using refresh_token
. The validity time of the refresh token is configurable and can be configured using the property: refresh.token.validity.in.minutes
Since User service handles PII (Personal Identifiable information) encrypting the data before saving in DB becomes crucial.
DIGIT manages these as security policy in Master Data which is then referred by encryption service to encrypt the data before persisting it to DB.
There are two security policy models for user data - User and UserSelf.
User model
attributes
contains a list of fields from the user object that needs to be secured and the field
roleBasedDecryptionPolicy
is an attribute-level role-based policy. It defines visibility for each attribute.
User security model is used for Search API response
UserSelf
It contains the same structure of security policy but the UserSelf is used for Create/Update API response.
The visibility of the PII data is based on the above MDMS configuration. There are three types of visibility mentioned in the config.
PLAIN - Show text in plain form.
MASKED - The returned text contains masked data. The masking pattern is applied as defined in the Masking Patterns master data.
NONE - The returned text does not contain any data. It contains strings like “Confidential Information”.
Any user can get plain access to the secured data (citizen’s PII) by requesting through the plainAccessRequest
parameter. It takes the following parameters:
recordId
- It is the unique identifier of the record that is requested for plain access.
fields
- It defines a list of attributes that are requested for plain access.
To know more about the encryption policy, refer to the document Encryption Service docs.
Property | Value | Remarks |
---|---|---|
APIs |
---|
egov.user.search.default.size
10
default search record number limit
citizen.login.password.otp.enabled
true
whether citizen login otp based
employee.login.password.otp.enabled
false
whether employee login otp based
citizen.login.password.otp.fixed.value
123456
fixed otp for citizen
citizen.login.password.otp.fixed.enabled
false
allow fixed otp for citizen
otp.validation.register.mandatory
true
whether otp compulsory for registration
access.token.validity.in.minutes
10080
validity time of access token
refresh.token.validity.in.minutes
20160
validity time of refresh token
default.password.expiry.in.days
90
expiry date of a password
account.unlock.cool.down.period.minutes
60
unlock time
max.invalid.login.attempts.period.minutes
30
window size for counting attempts for lock
max.invalid.login.attempts
5
max failed login attempts before account is locked
egov.state.level.tenant.id
pb