Users
Users are the authenticated entities that make KMIP, REST or NAE-XML calls. To authenticate to the NAE-XML interface, you send an AuthRequest with the user credentials. To authenticate to the REST API, you POST the user credentials to an authentication endpoint, and receive an API token, which you can use in subsequent API calls.
Managing Users
Users can be created and managed via the REST API and the CLI tool. The legacy NAE-XML requests for user management are also supported, through the NAE-XML interface.
On launch, a single user exists, named "admin". This user can create, modify and delete other users. The user that is created in the ksctl
setup is this admin user; see CLI Installation.
The following options are available for managing users:
Create
Delete
Get a single record
List records
Modify
Note that when you create a new user there is a 'username' that is set. It is used as the login of that user and cannot be changed. Another field is ‘user’ that is the full name of the use; this is an optional field and can be modified. Finally, there is also a 'User ID' field created by the platform that is used for all updates to the user. This field is of the form: local|<UUID>
To create a user named "bob":
$ ksctl users create --name bob --pword bob
The response looks like
{
"created_at": "2022-01-24T06:53:27.245528Z",
"email": "bob@local",
"last_login": null,
"logins_count": 0,
"name": "bob",
"nickname": "bob",
"updated_at": "2022-01-24T06:53:27.245528Z",
"user_id": "local|c6537abe-a266-4833-9d60-b9713812136e",
"username": "bob",
"failed_logins_count": 0,
"account_lockout_at": null,
"failed_logins_initial_attempt_at": null,
"last_failed_login_at": null,
"password_changed_at": "2022-01-24T06:53:27.240767Z",
"password_change_required": false,
"certificate_subject_dn": "",
"enable_cert_auth": false,
"auth_domain": "00000000-0000-0000-0000-000000000000",
"login_flags": {
"prevent_ui_login": false
}
}
Managing Users in Domain
The CipherTrust Manager allows you to create users in a non-root domain if you set the allow-user-mgmt
property to true
while creating the domain.
Before proceeding to the next steps, we recommend you to get familiar with the following terms:
auth_domain - The
auth_domain
is a domain where the user is created and authenticated during login. Theauth_domain
is represented by the Home Domain field on the CipherTrust Manager GUI.
If a user is created in a domain named 'Dom1', theauth_domain
for that user will be 'Dom1'. However, if a user is created in a root domain and assigned to 'Dom1', the defaultauth_domain
for that user will always remain asroot
.Target domain - The target domain is represented by the
domain
field on CLI and API.Assigned users - Users assigned from the root domain to any non-root domain. For assigned users, the
auth_domain
is alwaysroot
. By default, if theauth_domain
is not provided, it is assumed to beroot
.Non-root domain - Domains other than the root domain.
Login/Token Creation
For login/token creation, the domain users need to pass auth_domain
with username and password.
To log on to the GUI as a domain user:
Select the I am a domain user check box.
Specify your native domain in the Home Domain field.
Click Log In.
The domain users are always redirected to their home domain. However, when assigned users log on to the CipherTrust Manager GUI for the first time, they are redirected to the root domain. Next time onward, after login, these users are redirected to their last logged-in domain on the GUI.
To switch between the domains, refer to GUI.
To create a user within a non-root domain, set the is_domain_user
property to true
.
Note
• While creating a domain, users created in the non-root domain cannot be added to the domains admin's list.
• Users created in the non-root domain cannot be assigned to any other domain.
• Certificate-based login does not work for the users created in the non-root domain.
Preventing Users from UI Login
The CipherTrust Manager allows you to prevent the UI login for users if you set the prevent_ui_login
property to true
while creating the user. By default, this property is set to false
.
You can change the value of prevent_ui_login
property while updating the user.
Configuring LDAP Authentication
Note
You need a valid Virtual CipherTrust Manager license to use this feature. To activate your instance with a trial evaluation, or a term or perpetual license, see Licensing.
The CipherTrust Manager authenticates users against its internal database and also provides an option to authenticate with an external authentication provider (LDAP). It is possible to have a mix of both local and LDAP users.
Overview
When LDAP is configured the users and credentials are located in an external LDAP server and CipherTrust Manager acts as a forwarder to the LDAP server. The first time a new LDAP user is successfully authenticated, a corresponding user record is stored in the CipherTrust Manager and is marked to belong to the respective LDAP connection. All CipherTrust Manager user records associated with a LDAP connection are deleted when the LDAP connection is deleted from the CipherTrust Manager.
To authenticate users against LDAP, it is required to configure an LDAP connection in the CipherTrust Manager. Only CipherTrust Manager users with administrator privilege are authorized to configure LDAP connections. It is possible to configure LDAP connections through either the REST API, the CLI or the GUI.
You can also configure the LDAPS protocol, which uses certificate authentication to secure the connection. With LDAPS connections, CipherTrust Manager verifies presented LDAP server certificates, by default using the operating system trust store. You cannot edit the trust store, but it contains wide coverage of major well-known certificate authorities (CAs). Alternatively, you can directly provide root certificate authorities to trust, which is recommended if the LDAPS connection is secured by a lesser-known root CA or a self-signed certificate. You can also disable server certificate verification entirely, for troubleshooting purposes. A minimum version of TLS 1.1 is required to support LDAPS. TLS versions are configurable at the interface level.
Each LDAP connection is given a name that needs to be known by the end user and be provided during authentication; this is often referred to as the domain. For example, if a user joe exists in the LDAP directory ldap://192.168.0.1:389 and this LDAP server is created in CipherTrust Manager with the name myco, the end user would have to authenticate with either myco\joe, myco/joe or myco|joe in the GUI. On the CLI, you would instead specify the name of the connection as a separate parameter.
LDAP authentication also works through NAE-XML. The connection and/or username can be specified in following formats:
ldap-connection|username
- An LDAP user in the root domain. For example, ldap-connection|joe.domain-id|ldap-connection|username
- An LDAP user in a specific domain. For example, domain-id|ldap-connection|joe.
When browsing the GUI, LDAP users can be identified from the source property. The user is displayed in either of the formats listed above. A local user is displayed as local|<username>.
Setting Up a New Connection
Using either the CLI or the GUI it is possible to test a connection, create (bind) a new connection, get a list of connections, modify a connection and delete a connection.
Required fields for LDAP connection
name
- Unique identifier for the connection and commonly referred to as the domain, for example myco.server_url
- Hostname and port of the LDAP server, for example ldap://192.168.0.1:389. You can enable LDAPS protocol withldaps
. There are options to specify how the LDAP server certificate is verified.root_dn
- The base DN as the starting point for the search, for example DC=myco,DC=local.strategy
- Type of connection to create, must be "ldap" in the case of an LDAP connection.uid_field
- The field containing the user's login name, for example uid.
Optional fields for LDAP connection
search_filter
- Optional LDAP search filter which can further restrict the set of users who will be allowed to log in, for example memberOf="CN=example,OU=Users,DC=myco,DC=local".guid_field
- The LDAP field name of a globally unique identifier for the user, for example objectGUID. If this field is specified, the user record in the CipherTrust Manager would have the value of this field as identifier of the user instead of the provided username. If for example the user joe, on the LDAP connection myco, has the objectGUID value 3450be9a6ee76540956e7c6b10d98831, then his user record would be myco|3450be9a6ee76540956e7c6b10d98831 instead of myco|joe. The friendly name joe would still be in the user record and be search-able.bind_dn
- If authentication is required to perform search this is the name of the entity to bind to, for example CN=poweruser,CN=Users,DC=myco,DC=local.bind_pass
- Password of the user provided inbind_dn
.If
bind_dn
andbind_pass
fields are not provided, the LDAP search will be performed using the 'end user provided' user id and password.group_id_field
- The field that contains the group name, for example 'cn'. Ifgroup_id_field
is not provided, it will default to whatever is inuid_field
.group_filter
- Search filter for listing groups. Ifgroup_filter
is not provided, it will default to "(objectclass=Group)".group_member_field
- The field which contains a user's group membership information, for example 'member'. Ifgroup_member_field
is not provided, it will default to 'member'.
Optional fields for LDAPS connections
The following options are ignored for LDAP connections, which have the ldap
protocol in the server_url
and send traffic in cleartext.
insecure_skip_verify
- When set totrue
, this option disables CipherTrust Manager's verification of the LDAP server certificate.Caution
Setting to
true
lowers the security of the connection and can disrupt LDAPS connection availability, and so is only recommended for troubleshooting purposes.root_cas
- This field can contain a list of root CAs for CipherTrust Manager to verify the LDAP server certificate. The provided root CAs are used instead of the operating system trust store to verify the LDAP server certificate. Root CAs must be in PEM encoded format.
Once a connection is created, it is not possible to modify these fields: name
, strategy
or bind_pass
.
CLI command example
Test the connection configuration to verify it can authenticate one of the LDAP users.
$ ksctl connections test --test-username=jdoe --test-password=ji32k7au4a83 --name=myco --strategy=ldap --bind-password=admin --bind-dn="CN=poweruser,CN=Users,DC=myco,DC=local" --server-url="ldap://192.168.0.1:389" --user-id-field=uid --root-dn="DC=myco,DC=local" --search-filter="(memberOf=CN=example,OU=Users,DC=myco,DC=local")
Bind the connection configuration.
$ ksctl connections bind --name=myco --strategy=ldap --bind-password=admin --bind-dn="CN=poweruser,CN=Users,DC=myco,DC=local" --server-url="ldap://192.168.0.1:389" --user-id-field=uid --root-dn="DC=myco,DC=local" --search-filter="(memberOf=CN=example,OU=Users,DC=myco,DC=local")
Configuring Open ID Connect (OIDC) Authentication
Caution
This feature is a technical preview for evaluation in non-production environments. A technical preview introduces new, incomplete functionality for customer feedback as we work on the feature. Details and functionality are subject to change. This includes API endpoints, UI elements, and CLI commands. We cannot guarantee that data created as part of a technical preview will be retained after the feature is finalized.
Note
You need a valid Virtual CipherTrust Manager license to use this feature. To activate your instance with a trial evaluation, or a term or perpetual license, see Licensing.
CipherTrust Manager supports Open ID Connect as an external identity provider for user login, using implicit flow with form post.
The following sequence diagram demonstrates how browser login through the CipherTrust Manager GUI returns an access token from an external identity provider.
Users are created on the external identity provider. To set up authentication for these users and allow them to access CipherTrust Manager and perform operations, there are three stages:
Configure the connection between CipherTrust Manager and the identity provider.
You need access rights on the identity provider to create an application and assign users to it, and Admin level access to the CipherTrust Manager to configure the connection details.
Login to CipherTrust Manager as a user of the application. This creates a user account visible on CipherTrust Manager.
As a CipherTrust Manager assign the user account to groups and domains to allow the desired operations.
To configure an identity provider connection
Create a client application on the identity provider to service user logins with the implicit flow.
Ensure the application is set to the implicit flow and provide the redirect URI in the format
https://<ciphertrust-hostname>/api/v1/auth/oidc-callback
.Assign users to your application that correspond to desired CipherTrust Manager users.
After creating the application, you need to collect the following values from the identity provider:
Client ID: The client identifier of CipherTrust Manager on the identity provider.
Discovery URI: This location contains detailed settings for CipherTrust Manager to construct a login request to the identity provider, such as authorization URI and public signing keys. This is also called "well known configuration URL" in some identity providers.
On CipherTrust Manager as an Admin with permission to edit connections, provide the client ID, redirect URI, discovery URI. Give the connection a name to display during user login.
ksctl connections create oidc --name '<desired-name>' --client-id <client-id-from-identity-provider> --redirect-uri <ciphertrust-hostname>/api/v1/auth/oidc-callback --discovery-uri <discovery-uri-from identity-provider>
If discovery URI is not provided, the following values must be provided instead. These settings are recommended for testing scenarios only. Discovery URI is strongly recommended for production usage of OIDC.
authorization-uri
: Authorization endpoint for the identity provider.jwks
: Public signing keys to validate the ID token.
Network Time Protocol (NTP) configuration is very important for successful OIDC authentication. Ensure that an NTP server is configured for CipherTrust Manager.
To login a user with OIDC authentication
The OIDC implicit flow is only available for browsers. Therefore, a user can login to the identity provider through the CipherTrust Manager web console.
On the login page, select a registered identity provider from the Identity Providers dropdown.
Note
Any username or password entered from the CipherTrust Manager login page is ignored. CipherTrust Manager-level username/password authentication and OIDC authentication are mutually exclusive.
You are redirected to the identity provider's login page. At this point, enter your credentials.
Note
Sometimes your browser caches the previously logged in OIDC-authenticated user. Clear your browser cache if you want to login a different user through the OIDC flow.
After authentication with the identity provider succeeds, you are redirected back to the CipherTrust Manager web console.
To view, edit, and assign permissions to an OIDC-authenticated user
Once the user logs into CipherTrust Manager at least once, a user account is created in CipherTrust Manager with the OIDC connection name displayed as the source.
CipherTrust Manager administrators can control the allowed operations for the user with group and domain assignment in the same way as with local users.
Deleting an OIDC user on CipherTrust Manager removes those CipherTrust Manager permissions associated with the user. However, the user can still login to CipherTrust Manager as long as that user is still assigned to the application on the identity provider. The user must be deleted or unassigned at the identity provider application to completely remove any access to CipherTrust Manager.