User Management¶
Info
User management in Stream Processor has the following features,
-
The concept of single user store, which is either local or external.
-
File based user store as the default embedded store.
-
Ability to connect to an external Identity Provider using SCIM2 and OAuth2 protocols.
-
Ability to extend user authentication as per the scenario
Introduction to user management¶
User management is a mechanism which involves defining and managing users, roles and their access levels in a system. A user management dashboard or console provides system administrators a holistic view of a system's active user sessions, their log-in statuses, the privileges of each user and their activity in the system, enabling the system administrators to make business-critical, real-time security decisions. A typical user management implementation involves a wide range of functionality such as adding/deleting users, controlling user activity through permissions, managing user roles, defining authentication policies, managing external user stores, manual/automatic log-out, resetting user passwords etc.
Any user management system has users, roles, user stores and user permissions as its basic components .
Users¶
Users are consumers who interact with your organizational applications, databases or any other systems. These users can be a person, a device or another application/program within or outside of the organization's network. Since these users interact with internal systems and access data, the need to define which user is allowed to do what is critical to most security-conscious organizations. This is how the concept of user management developed.
Permission¶
A permission is a 'delegation of authority' or a 'right' assigned to a user or a group of users to perform an action on a system. Permissions can be granted to or revoked from a user/user group/user role automatically or by a system administrator. For example, if a user has the permission to log-in to a system , then the permission to log-out is automatically implied without the need of granting it specifically.
User Roles¶
A user role is a consolidation of several permissions. Instead of associating permissions with a user, administrator can associate permissions with a user role and assign the role to users. User roles can be reused throughout the system and prevents the overhead of granting multiple permissions to each and every user individually.
User Store¶
A user store is a persistent storage where information of the users and/or user roles is stored. User information includes log-in name, password, fist name, last name, e-mail etc. It can be either file based or a database maintained within SP or externally to it. User stores used in SP differs based on the interface(IdP Client) used to interact with the user store. By default, a file based user store maintained in the \<SP_HOME>/conf/\<PROFILE>/deployment.yaml file interfaced through 'Local' IdP Client is enabled.
User Management via the IdP Client Interface¶
In WSO2 Stream Processor, user management is carried out through the Identity Provider Client (IdP Client) interface that can be switched as required for the user scenario. Furthermore, a custom IdP Client can be written to encompass the required user store connection and authentication.
IdP clients can be switched by specifying te required IdP client in the
auth.configs:
section in the
<SP_HOME>/conf/<PROFILE>/deployment.yaml
file.
auth.configs:
# Type of the IdP Client used for the user authentication
type: local
The active IdP client is local
by default.
Following are the IdP Clients available for WSO2 SP:
Local IdP Client¶
The local IdP Client interacts with the file-based user store that is
defined in the
<SP_HOME>/conf/<PROFILE>/deployment.yaml
file under
auth.configs
namespace as follows:
auth.configs:
type: 'local'
userManager:
adminRole: admin
userStore:
users:
-
user:
username: admin
password: YWRtaW4=
roles: 1
roles:
-
role:
id: 1
displayName: admin
The above user and role is added by default.
Parameters¶
The parameters used in the above configurations are as follows:
Note
If new users/roles are added and the above default user and role are also needed, the following parameters must be added to the user store along with the added user/role.
Parameter | Default Value | Description |
---|---|---|
|
|
The name of the role that has administration privileges. |
|
|
The username of the user. |
|
|
The Base64(UTF-8) encrypted password of the user. |
|
|
A comma separated list of the IDs of the roles assigned to the user. |
|
1 |
The unique ID for the role. |
userManager > userStore > roles > role > admin |
admin |
The name of the role. |
Furthermore, Local IdP Client functionality can be controlled via the
properties defined in the
<SP_HOME>/conf/<PROFILE>/deployment.yam
l file under
the auth.configs
namespace as shown below.
auth.configs:
type: local
properties:
sessionTimeout: 3600
refreshSessionTimeout: 86400
The following are the properties that can be configured for the local IdP provider:
Property | Default Value | Description |
---|---|---|
properties > sessiontimeout |
3600 |
The number of seconds for which the session is valid once the user logs in. !!! infoThe value specified here needs to be greater than 60 seconds because the system checks the user credentials and keeps extending the session every minute until the session timeout is reached. |
|
86400 |
The number of seconds for which the refresh token used to extend the session is valid. |
The complete default configuration of the local
IdP
Client is as follows:
auth.configs:
type: 'local'
properties:
sessionTimeout: 3600
refreshSessionTimeout: 86400
userManager:
adminRole: admin
userStore:
users:
-
user:
username: admin
password: YWRtaW4=
roles: 1
roles:
-
role:
id: 1
displayName: admin
External IdP Client¶
External IdP Client authenticates users by interacting with an external identity provider via OAuth2 and SCIM2 protocols. The user store is maintained by the external identity provider. WSO2 SP authenticates by requesting an access token from the identity provider using the password grant type.
Note
The identity provider with which WSO2 SP interacts with to authenticate users must be started before the SP server.
The auth manager must be configured under the
auth.configs
namespace as shown below:
auth.configs:
type: external
authManager:
adminRole: admin
The parameters used in the above configurations areas follows:
Parameter | Default Value | Description |
---|---|---|
userManager > adminRole |
admin |
The name of the role that has administration privilages. |
Furthermore, external IdP client functionality can be controlled via the
properties defined in the
<SP_HOME>/conf/<PROFILE>/deployment.yaml
file under
the auth.configs
namespace as shown below.
auth.configs:
type: external
properties:
kmDcrUrl: https://localhost:9443/identity/connect/register
kmTokenUrl: https://localhost:9443/oauth2
kmUsername: admin
kmPassword: admin
idpBaseUrl: https://localhost:9443/scim2
idpUsername: admin
idpPassword: admin
portalAppContext: portal
statusDashboardAppContext: monitoring
businessRulesAppContext : business-rules
databaseName: WSO2_OAUTH_APP_DB
cacheTimeout: 900
baseUrl: https://localhost:9643
grantType: password
The following are the properties that can be configured for the external IdP provider:
Property
|
Default Value
|
Description
|
---|---|---|
kmDcrUrl |
|
The Dynamic Client Registration (DCR) endpoint of the key manager in the IdP. |
dcrAppOwner |
kmUsername |
|
kmTokenUrl |
|
The token endpoint of the key manager in the IdP. |
|
admin |
The username for the key manager in the IdP. |
|
admin |
The password for the key manager in the IdP. |
|
|
The SCIM2 endpoint of the IdP. |
|
admin |
The username for the IdP. |
|
admin |
The password for the IdP. |
|
portal |
The application context of the Dashboard Portal application in WSO2 SP. |
statusDashboardAppContext |
monitoring |
The application context of the Status Dashboard application in WSO2 SP. |
|
business-rules |
The application context of the Business Rules application in WSO2 SP. |
databaseName |
|
The name of the wso2.datasource used to store the OAuth application credentials |
cacheTimeout |
900 |
The cache timeout for the validity period of the token in seconds. |
|
|
The base URL to which the token should be redirected after the code returned from the Authorization Code grant type is used to get the token. |
|
password |
The grant type used in the OAuth application token request. |
|
N/A | The client ID of the OAuth App. If no value is specified for this property, the DCR is called to register the application and persist the client ID in the data store. |
|
N/A | The client secret of the OAuth application. If no value is specified for this property, the DCR is called to register the application and persist the client secret in the data store.
|
Writing custom IdP Client¶
When writing a custom IdP client, the following two interfaces must be implemented:
- IdPClientFactory
: This is a factory OSGi service that initialtes the custom IdP
client using the properties from
IdPClientConfiguration.
- IdPClient : An interface with functions to provide user authentication and retrieval by the other services.