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.

Users can be managed locally, or through an LDAP connection, or through an OIDC connection.

The operations which users are allowed to perform are controlled through group membership.

Managing Users

Users can be created and managed through the web console, ksctl CLI, or REST API. 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

Creating a User through GUI

Perform the following steps to create a user through the GUI:

1. Navigate to Access Management > Users.

2. Click Add User available on the top right corner of the screen. The Add User screen appears.

3. Select the Connection Type to create a user:

   • Local User - Select this option and specify the following:

     • Full Name

     • Username

     • Email

     • Password

     • Password Match

   Note

   • You must adhere to the password policy while setting a password.

   • You can select the required checkbox to allow the user to log in using the web app, password, and/or certificate.

   • If you select the checkbox Allow user to login using certificate only, it enables the certificate based authentication for logging in to the CipherTrust Manager. Consequently, the user will be restricted to login using browser-based web certificates.

   The Password and Password Match fields are optional, if user selects only Allow user to login using certificate option and enter **Certificate Subject Distinguished Name

   

   • OIDC - Select this option and specify the following:

     • OIDC Connection

     • Name

     • Email

   • LDAP - Select this option and specify the following:

     • LDAP Connection

     • Name

     • Email

4. Click Create. A user is created and will appear in the list of users available on the Users page.

Creating a User through ksctl CLI

Use the below ksctl CLI 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
        },
        "allowed_auth_methods": [
            "password"
        ]
    }

Managing Allowed Client Types for Users

The allowed_client_types flag is added to manage the list of client types that are allowed to authenticate the users through their credentials. This field is optional.

By default, the CipherTrust Manager allows all clients types:

• unregistered clients - are not registered with the CipherTrust Manager.

• public clients - are ksctl, NAE, Web-UI, and API playground. These clients are pre-registered with the CipherTrust Manager.

• confidential clients - are able to securely authenticate with the CipherTrust Manager. For example, NAE, KMIP, and CTE clients.

If you set the allowed_client_types flag to empty, no client can authenticate the user to log on to the CipherTrust Manager.

You can set any combination of client types based on your requirements.

Example Request

ksctl users create --username chanakya --pword KeySecure_1 --allowed-client-types confidential,public

Example Response

{
    "created_at": "2022-12-05T13:29:29.325474Z",
    "email": "chanakya@local",
    "last_login": null,
    "logins_count": 0,
    "name": "chanakya",
    "nickname": "chanakya",
    "updated_at": "2022-12-05T13:29:29.325474Z",
    "user_id": "local|726720ee-c597-4582-92c0-31f2c2f53947",
    "username": "chanakya",
    "failed_logins_count": 0,
    "account_lockout_at": null,
    "failed_logins_initial_attempt_at": null,
    "last_failed_login_at": null,
    "password_changed_at": "2022-12-05T13:29:29.321738Z",
    "password_change_required": false,
    "certificate_subject_dn": "",
    "enable_cert_auth": false,
    "auth_domain": "00000000-0000-0000-0000-000000000000",
    "login_flags": {
        "prevent_ui_login": false
    },
    "allowed_auth_methods": [
        "password"
    ],
    "allowed_client_types": [
        "confidential",
        "public"
    ]
}

Managing Login Authentication Methods for Local Users

The CipherTrust Manager allows you to manage login authentication methods for local users using the allowed_auth_methods parameter. By default, this property is set to password that is, password-based authentication.

The allowed login authentication methods are:

• "password" : Only password-based authentication. This is the default authentication method.

• "" : Setting it to empty means no authentication method is allowed to the user.

• "user_certificate" : Only user-certificate based authentication.

• "password", "user_certificate" : Either of the authentication method is allowed.

• Password is optional when certificate-based authentication is enabled and certificate subject dn is provided while creating the user.
• The allowed authentication methods are not enforced on admin users.

If both enable_cert_auth and allowed_auth_methods parameters are provided in the request, the enable_cert_auth parameter is ignored.

Example Request 1

ksctl users create --username chandragupta --pword KeySecure_1 --allowed-auth-methods password,user_certificate

Example Response

{
    "created_at": "2022-12-05T13:27:47.317746Z",
    "email": "chandragupta@local",
    "last_login": null,
    "logins_count": 0,
    "name": "chandragupta",
    "nickname": "chandragupta",
    "updated_at": "2022-12-05T13:27:47.317746Z",
    "user_id": "local|d099eb70-e6fe-4a87-8e6e-49ff4ac93fb4",
    "username": "chandragupta",
    "failed_logins_count": 0,
    "account_lockout_at": null,
    "failed_logins_initial_attempt_at": null,
    "last_failed_login_at": null,
    "password_changed_at": "2022-12-05T13:27:47.314971Z",
    "password_change_required": false,
    "certificate_subject_dn": "",
    "enable_cert_auth": true,
    "auth_domain": "00000000-0000-0000-0000-000000000000",
    "login_flags": {
        "prevent_ui_login": false
    },
    "allowed_auth_methods": [
        "password",
        "user_certificate"
    ],
    "allowed_client_types": [
        "unregistered",
        "public",
        "confidential"
    ]
}

Example Request 2 (setting empty)

ksctl users create --username yum --pword KeySecure_1 --allowed-auth-methods ""

Example Response

{
    "created_at": "2023-02-03T07:08:37.308092Z",
    "email": "yum@local",
    "last_login": null,
    "logins_count": 0,
    "name": "yum",
    "nickname": "yum",
    "updated_at": "2023-02-03T07:08:37.308092Z",
    "user_id": "local|10244efe-afdc-4759-b9e0-ea6144f7e843",
    "username": "yum",
    "failed_logins_count": 0,
    "account_lockout_at": null,
    "failed_logins_initial_attempt_at": null,
    "last_failed_login_at": null,
    "password_changed_at": "2023-02-03T07:08:37.292784Z",
    "password_change_required": false,
    "certificate_subject_dn": "",
    "enable_cert_auth": false,
    "auth_domain": "00000000-0000-0000-0000-000000000000",
    "login_flags": {
        "prevent_ui_login": false
    },
    "allowed_auth_methods": [],
    "allowed_client_types": [
        "unregistered",
        "public",
        "confidential"
    ]
}

Manually Creating LDAP or OIDC Users

CipherTrust Manager can integrate with external authentication and identity providers using LDAP or OIDC protocols.

After you configure an LDAP or OIDC connection, logging in with the associated users for the first time automatically creates matching CipherTrust Manager user accounts. However, you can also manually create these CipherTrust Manager user accounts prior to first login.

Provide the --userconnection parameter to the ksctl users create to specify an LDAP or OIDC connection.

For example:

ksctl users create --name bob --pword bob --userconnection LDAP-connection

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. The auth_domain is represented by the Home Domain field on the CipherTrust Manager GUI.
  If a user is created in a domain named 'Dom1', the auth_domain for that user will be 'Dom1'. However, if a user is created in a root domain and assigned to 'Dom1', the default auth_domain for that user will always remain as root.

• 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 always root. By default, if the auth_domain is not provided, it is assumed to be root.

• 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:

1. Select the I am a domain user check box.

2. Specify your native domain in the Home Domain field.

3. 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.

• 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

This feature is not included in Community Edition and requires a valid Virtual CipherTrust Manager license. 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 account is stored in the CipherTrust Manager and is marked to belong to the respective LDAP connection. You can also create user accounts for LDAP users prior to authentication. All CipherTrust Manager user accounts 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 LDAP Connection

Using either the CLI or the GUI it is possible to test a connection, create 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 with ldaps. 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.

• uid_field- The field containing the user's login name, for example uid.

Fields for Groupmaps for LDAP Connection

You can optionally set up groupmaps for an LDAP connection. All of the following fields are required for groupmap configuration:

• 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 in bind_dn.

  If bind_dn and bind_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'. If group_id_field is not provided, it will default to whatever is in uid_field.

• group_filter - Search filter for listing groups. If group_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'. If group_member_field is not provided, it will default to 'member'.

Optional field 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".

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 to true, this option disables CipherTrust Manager's verification of the LDAP server certificate.

  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 --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")

Create the connection configuration.

ksctl connections create ldap --name=myco --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 OpenID Connect (OIDC) Authentication

This feature is not included in Community Edition and requires a valid Virtual CipherTrust Manager license. To activate your instance with a trial evaluation, or a term or perpetual license, see Licensing.

CipherTrust Manager supports OpenID Connect as an external identity provider for CipherTrust Manager user login, using implicit flow with form post.

The OIDC connection to authenticate CipherTrust Manager users is separate from the OIDC connection to authenticate CTE agents, which is configured through connection manager.

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:

1. 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.

2. Create a user account on CipherTrust Manager for a user of the application. Alternatively, logging in to CipherTrust Manager as a user of the application automatically creates a user account visible on CipherTrust Manager.

3. As a CipherTrust Manager assign the user account to groups and domains to allow the desired operations.

Supported flows, scopes and claims

Supported flow:

• Implicit flow with form post (response_type=id_token)

Requested scope:

• scope=openid email profile

Requested type:

• response_type=id_token

Requested mode:

• response_mode=form_post

The following standard claims are required to be returned by the external identity provider:

• sub: used as the user ID

The following standard claims are optional and will be used if returned by the external identity provider:

• name: used as the "name" property of a user, if missing it will fall back to user ID (which effectively means sub)
• email: used as the "email" property of a user, if missing it will be empty

To read more about standard scopes: 

https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims

To read more about standard claims: 

https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims

To configure an identity provider connection

1. Create a client application on the identity provider to service user logins with the implicit flow.

   1. 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. If you have a CipherTrust Manager cluster, provide one redirect URI for each node. For example, provide https://<node1-hostname>/api/v1/auth/oidc-callback and https://<node2-hostname>/api/v1/auth/oidc-callback for two CipherTrust Manager nodes.

   2. Assign users to your application that correspond to desired CipherTrust Manager users.

   3. 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.

2. 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-uris <ciphertrust-hostname>/api/v1/auth/oidc-callback --discovery-uri <discovery-uri-from identity-provider>
   

   You can provide multiple redirect URIs by repeating the redirect-uris parameter. For example --redirect-uris https://node1.com/api/v1/auth/oidc-callback --redirect-uris https://node2.com/api/v1/auth/oidc-callback.

   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.

3. 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.

1. On the login page, select a registered identity provider from the Identity Providers dropdown.

   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.

2. You are redirected to the identity provider's login page. At this point, enter your credentials.

   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. You can also create a CipherTrust Manager user account manually prior to first log in.

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.