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.

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

Managing Users

Users can be created and managed via 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

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
        }
    }

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.

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

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 root domain and is marked to belong to the respective LDAP connection. You can also create user accounts for LDAP users in the root domain prior to authentication. Only users created in the root domain can use LDAP authentication. Users that belong to additional domains can login to the root domain and switch into a non-root domain in a single step as described below.

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.

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:

• 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-password - 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-base-dn - Starting point to use when searching for groups.

• 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 fields for LDAP connection

• guid-field - The LDAP field name of a globally unique identifier for the group. If this is not specified, the value the LDAP server uses uid-field instead. However, on uid_field update, guid_field does not update automatically.

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

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

Logging in a User with LDAP Authentication

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.

  Note

  The user must be created in the root domain and assigned to additional domains to successfully login with this syntax.

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

Configuring OpenID Connect (OIDC) Authentication

CipherTrust Manager supports Open ID Connect as an external identity provider for CipherTrust Manager 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:

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 in the root domain. Alternatively, logging in to CipherTrust Manager as a user of the application automatically creates a user account visible on CipherTrust Manager root domain.

   Note

   OIDC-authenticated users must be created in the root domain. They can later be assigned to additional non-root domains.

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

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 to the root domain.

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

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