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": "2018-04-27T21:10:53.191577Z",
            "email": "",
            "last_login": null,
            "logins_count": 0,
            "name": "bob",
            "nickname": "bob",
            "updated_at": "2018-04-27T21:10:53.191577Z",
            "user_id": "local|c7560d06-3628-4fb0-81e3-5881d2f8d7b3",
            "username": "bob",
            "failed_logins_count": 0,
            "account_lockout_at": null,
            "failed_logins_initial_attempt_at": null,
            "last_failed_login_at": null,
            "password_changed_at": "2018-04-27T21:10:53.192083Z",
            "password_change_required": 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.
For login/token creation, the domain users need to pass auth_domain with username and password. The auth_domain is a domain where user is created.

To create a user within a non-root domain, set the is_domain_user property to true.

You can also assign users from root domain to any non-root domain.

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

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

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:

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. Login to CipherTrust Manager as a user of the application. This 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.

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.

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

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.

   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.

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.