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 Local 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 Account - Select this option and specify the following:

     • Full Name

     • Username

     • Email

     • Password

     • Password Match

   Note

   • You can optionally assign a custom password policy before or after creation. The global password policy is the default. Available custom password policies are specific to the domain of the new user.

   • 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 Local 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"
        ]
    }

Setting Expiration Date for Users

The expires_at flag is added to set the expiration date for the local users to limit the user account to a certain period. This field is optional. After the expiration date has been reached, the access permissions for that user will be revoked. The user will no longer have access to the CipherTrust Manager. Only members of the admin and User Admins groups can add or modify the expiration date for an existing local user account. If the expiration date is extended or removed for an already expired account, the account will be active again.

Here are the examples of date-time format:

• 2002-10-02T10:00:00-05:00

• 2002-10-02T15:00:00Z

• 2002-10-02T15:00:00.05Z

The CipherTrust Manager throws an error if you set the expiration date before the current time. You can set the expiration date for both new users as well as existing users.

For new users

For new users, run:

Request example 1 (create user with valid date)

ksctl users create --name "john" --expires-at "2023-01-30T10:30:35.421799Z"

Response

{
    "created_at": "2023-01-24T08:14:57.853232Z",
    "email": "john@local",
    "last_login": null,
    "logins_count": 0,
    "name": "john",
    "nickname": "john",
    "updated_at": "2023-01-24T08:14:57.853232Z",
    "user_id": "local|c3209b29-0343-4a10-a9b6-bd5674580518",
    "username": "john",
    "failed_logins_count": 0,
    "account_lockout_at": null,
    "failed_logins_initial_attempt_at": null,
    "last_failed_login_at": null,
    "password_changed_at": "2023-01-24T08:14:57.833508Z",
    "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"
    ],
    "expires_at": "2023-01-30T10:30:35Z",
    "allowed_client_types": [
            "unregistered",
            "public",
            "confidential"
    ]
}

Request example 2 (create user with expiration date before the current time)

ksctl users create --name "james" --expires-at "2021-01-30T10:30:35.421799Z"

Response

{
    "code": 9,
    "codeDesc": "NCERRInvalidParamValue",
    "message": "expires_at cannot be before current time"
}

For existing users

For existing users, run:

Request example 1 (modify user with valid date)

ksctl users modify --id "local|c3209b29-0343-4a10-a9b6-bd5674580518" --expires-at "2023-01-28T10:30:35.421799Z"

Response

{
    "created_at": "2023-01-24T08:18:57.929628Z",
    "email": "john@local",
    "last_login": null,
    "logins_count": 0,
    "name": "john",
    "nickname": "john",
    "updated_at": "2023-01-24T08:18:57.929628Z",
    "user_id": "local|c3209b29-0343-4a10-a9b6-bd5674580518",
    "username": "john",
    "failed_logins_count": 0,
    "account_lockout_at": null,
    "failed_logins_initial_attempt_at": null,
    "last_failed_login_at": null,
    "password_changed_at": "2023-01-24T08:18:57.915523Z",
    "password_change_required": false,
    "certificate_subject_dn": "",
    "enable_cert_auth": false,
    "login_flags": {
        "prevent_ui_login": false
    },
    "allowed_auth_methods": [
        "password"
    ],
    "expires_at": "2023-01-28T10:30:35Z",
    "allowed_client_types": [
        "unregistered",
        "public",
        "confidential"
    ]
}

Request example 2 (modify user with invalid date)

ksctl users modify --id "local|cdb01da2-56d1-4d30-8c8a-4cc73a684b2a" --expires-at "1-01-2023"

Response

Invalid date format for Expiry date: parsing time "1-01-2023" as "2006-01-02T15:04:05Z07:00": cannot parse "-2023" as "2006"

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_with_user_certificate" : Both password and user certificate are required for the two-factor authentication and the value of the certificate_subject_dn flag should be set while creating the user.

Example Request 1 (Using password,user_certificate)

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, by default 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. As well, there a connection setting called Disable Automatic Creation of a User which disables this default behavior and enforces that OIDC or LDAP users are manually created on CipherTrust Manager before 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

For OIDC authentication, the username of a manually created user must match the sub claim returned by the identity provider.

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.

Users in the Systems Admins and Admins group, such as the admin user, can configure an LDAP connection in the root domain. 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. CipherTrust Manager uses simple bind authentication.

By default, 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 prior to authentication in the root domain. There is an LDAP connection setting called Disable Automatic Creation of a User which disables this default behavior and enforces that LDAP users are manually created on CipherTrust Manager before first login. 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.

Viewing, editing, and assigning permissions to an LDAP-Authenticated user

CipherTrust Manager administrators can control the allowed operations for the user account with group and domain assignment in the same way as with local users. If the LDAP connection has fields for groupmaps configured, administrators can configure groupmaps to associate a group on the LDAP directory to a local CipherTrust Manager group, which are applied when the user logs in.

LDAPS Protocol

You can configure the LDAPS protocol, which uses certificate authentication to secure the connection. With LDAPS connections, CipherTrust Manager verifies presented LDAP server certificates, by default checking that the certificates are issued by major well-known certificate authorities (CAs). Alternatively, you can directly provide root certificate authorities to trust for the specific LDAPS connection, 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.

Setting Up a New LDAP Connection Through Web Console UI

1. Login to the root domain as a user in the Systems Admins and Admins group, such as the admin user.

2. Navigate to Access Management > LDAP.

   Note

   Do not navigate to the Connections page. The LDAP connection available through Access Management described here is separate and additional to the LDAP connection available through connection manager.

3. Click + Add LDAP to add a new connection.

4. Provide the required values for any LDAP connection:

   • 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 optionally enable LDAPS protocol by specifying ldaps. Options for LDAPS authentication are described in the step 7.

   • Root DN for users - The base DN as the starting point for the search, for example "DC=myco,DC=local".

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

5. If you wish to enable groupmaps, provide the following values:

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

   • Server Bind Password - Password of the user provided in Bind DN.

   • Root DN for groups - Starting point to use when searching for groups.

   • Search filter for listing groups - For example, "(objectclass=Group)".

   • Group id attribute for group mapping - The field that contains the group name, for example "cn".

   • User's group membership attribute - The field which contains a user's group membership information, for example, "member".

6. (Optional) Set the following values if desired:

   • Disable Automatic Creation of a User - Check the checkbox to disable the default automatic creation of a CipherTrust Manager user when the user logs in via LDAP. Disallows an unknown user from logging in. Enforces that a member of the admin or User Admins group must manually create a CipherTrust Manager user before the user can log in.

   • Search filter for listing users - 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".

   • User's distinguished name - Attribute inside the user object which contains the user distinguished name. If this value is not provided, CipherTrust Manager attempts to determine default value based on User's login name attribute. If User's login name attribute is provided as a sAMAccountName, Active Directory configuration is assumed and "distingushedName" is used as default. Otherwise, User's distinguished name defaults to "dn".

   • Unique Identifier Field - The LDAP field name of a globally unique identifier for the group. If this is not specified, the value the LDAP server uses User's login name attribute instead. However, on User's login name attribute update, Unique Identifier Field does not update automatically.

7. (LDAPS connections only). You can optionally specify some values for LDAPS connections. The options are ignored for LDAP connections, which have the ldap protocol in the Server URL and send traffic in cleartext.

   • Server Certificate - 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. You can upload the root CAs list as a file or provide them as text.

   • Disable verifying the server certificate - Check the checkbox to disable CipherTrust Manager's verification of the LDAP server certificate.

     Caution

     This setting lowers the security of the connection and can disrupt LDAPS connection availability, and so is only recommended for troubleshooting purposes.

8. Provide the following values required to test the connection:

   • Password for test

   • Username for test

9. Click Test Connection to ensure CipherTrust Manager can connect to the LDAP server with the provided settings.

10. Click Add LDAP to confirm the connection creation.

Setting Up a New LDAP Connection Through ksctl CLI

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.

• group-base-dn - Starting point to use when searching for groups.

• group-id-field - The field that contains the group name, for example 'cn'.

• group-filter - Search filter for listing groups.

• group-member-field - The field which contains a user's group membership information, for example 'member'.

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

• disable-auto-create - When set to true, disables the default automatic creation of a CipherTrust Manager user when the user logs in via LDAP. Disallows an unknown user from logging in. Enforces that a member of the admin or User Admins group must manually create a CipherTrust Manager user before the user can log in.

• user_dn_field - Attribute inside the user object which contains the user distinguished name. If this value is not provided, CipherTrust Manager attempts to determine default value based on uid_field. If uid_field is provided as a sAMAccountName, Active Directory configuration is assumed and "distingushedName" is used as default. Otherwise, user_dn_field defaults to "dn".

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 OpenID Connect as an external identity provider for CipherTrust Manager user login through the web console UI, using either implicit flow with form post or authorization code flow.

The following sequence diagram demonstrates how with implicit flow, browser login through the CipherTrust Manager GUI returns an access token from an external identity provider.

The following sequence diagram demonstrates how with authorization code flow, 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, or create a group map to associate the OIDC group membership to CipherTrust Manager groups.

Supported Flows, Scopes, and Claims

Supported flows:

• Implicit flow with form post

• Authorization code flow

Requested scope:

• scope=openid email profile

Requested type:

• response_type=id_token for implicit flow

• response_type=code for authorization code flow

Requested mode:

• response_mode=form_post for implicit flow

• response_mode=query for authorization code flow

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

• sub: used as the username and part of 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 falls back to user ID (which effectively means sub).

• email: used as the "email" property of a user. If missing it is 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 using web console UI

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

   1. Ensure the application is set to either implicit or authorization code 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. If desired, you can set a user identity claim for group membership, so that CipherTrust Manager can map OIDC user group membership in the OIDC application to a local CipherTrust Manager group when the user logs in to CipherTrust Manager. CipherTrust Manager uses groups as the default claim field name.

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

      • Client Secret: Needed for Authorization Code Flow only. The identity provider requires this value in the login request to validate. This is sensitive information, so record it in a secure manner.

      • If you set up a user identity claim for group membership in the last step, and the claim field name is different than groups, collect the claim field name as well.

2. Login to the root domain as a user in the Systems Admins and Admins group, such as the admin user.

3. Navigate to Access Management > OpenID Connect.

   Note

   Do not navigate to the Connections page.

4. Click Add Connection.

5. Provide the following details:

   • Name : A desired connection name.

   • Discovery URI: The location required for CipherTrust Manager to construct login requests, obtained in step 1.

   • Client ID: The client identifier of CipherTrust Manager on the identity provider, obtained in step 1.

6. Provide a Groups Claim, if in step 1 you set up a user identity claim and the claim field name is different than "groups". If you leave this field blank the value defaults to "groups".

7. Configure the desired flow type.

   • For implicit flow, make sure the Implicit Flow radio button is selected for the Flow Type.

   • For authorization code flow, make sure the Authorization Code Flow radio button is selected for the Flow Type. Provide the Client Secret obtained from the identity provider in step 1.

8. Provide the Redirect URI obtained from the identity provider in step 1.

   Click +Add Redirect URI if you have multiple redirect URIs to add.

9. (Optional) If desired, you can Disable Automatic Creation of a User by enabling the checkbox. This setting disables the default automatic creation of a CipherTrust Manager user when the user logs in via OIDC. This means an unknown user cannot log in. The CipherTrust Manager enforces that a member of the admin or User Admins group must manually create a CipherTrust Manager user before the user can log in.

10. Click Add Connection to create the connection.

11. Network Time Protocol (NTP) configuration is very important for successful OIDC authentication. Ensure that an NTP server is configured for CipherTrust Manager.

To configure an identity provider connection using ksctl CLI

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

   1. Ensure the application is set to either implicit or authorization code 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. If desired, you can set a user identity claim for group membership, so that CipherTrust Manager can map OIDC user group membership in the OIDC application to a local CipherTrust Manager group when the user logs in to CipherTrust Manager. CipherTrust Manager uses groups as the default claim field name.

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

      • Client Secret: Needed for Authorization Code Flow only. The identity provider requires this value in the login request to validate. This is sensitive information, so record it in a secure manner.

      • If you set up a user identity claim for group membership in the last step, and the claim field name is different than groups, collect the claim field name as well.

2. On CipherTrust Manager as a user in the Systems Admins and Admins group, such as the admin user, create the OIDC connection. Provide the client ID, redirect URI, and discovery URI. Give the connection a name to display during user login.

   For authentication code flow, set the flow-type to authorization_code and provide the client secret as well.

   Note

   flow-type defaults to implicit and so does not need to be set for implicit flow connections.

   By default, the connection is set up to allow, but not require, group mapping with the user claim field groups in the access token. If the identity provider uses a claim field other than groups, include the option --groups-claim, and provide the claim field name for group membership present in the access token.

   Implicit flow, no custom groups claim field:

   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>
   

   Authorization code flow, no custom groups claim field:

   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> --client-secret <client_secret_value> --flow-type authorization_code
   

   Group mapping to a non-default claim field name, with implicit flow:

   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> --groups-claim <claim_field_name>
   

   Note

   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.

   Note

   If you do not provide a discovery URI, 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.

   There is an additional optional test parameter for authorization code flow:

   • token-endpoint: Token endpoint for the identity provider, for authorization code flow only.

   Note

   There is an option, disable-auto-create. When set to true, disables the default automatic creation of a CipherTrust Manager user when the user logs in via OIDC. Disallows an unknown user from logging in. Enforces that a member of the admin or User Admins group must manually create a CipherTrust Manager user before the user can log in.

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

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

By default, 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 login.

There is an OIDC connection setting called Disable Automatic Creation of a User which disables this default behavior and enforces that OIDC users are manually created on CipherTrust Manager before first login.

CipherTrust Manager administrators can control the allowed operations for the user with group and domain assignment in the same way as with local users. If the OIDC connection has a group claim configured, administrators can configure group maps to associate a group on the OIDC server to a local CipherTrust Manager group, which are applied when the user logs in.

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.