--- title: Synchronize Kerberos user principals description: This sample demonstrates how to manage Kerberos user principals and how to reconcile user principals with IDM managed user objects. component: pingidm version: 8.1 page_id: pingidm:samples-guide:sync-with-kerberos canonical_url: https://docs.pingidentity.com/pingidm/8.1/samples-guide/sync-with-kerberos.html keywords: ["Samples", "Synchronization", "Kerberos"] section_ids: edit-kerberos-connector: Configure the Kerberos connector kerberos-sample-run: Run the sample --- # Synchronize Kerberos user principals This sample demonstrates how to manage Kerberos user principals and how to reconcile user principals with IDM managed user objects. The connector configuration (`/path/to/openidm/samples/sync-with-kerberos/conf/provisioner.openicf-kerberos.json)`) assumes that IDM is running on a host that is separate from the Kerberos host. This sample assumes that the default realm is `EXAMPLE.COM` and that there is an existing user principal `openidm/admin`. Adjust the sample to match your Kerberos realm and principals. ## Configure the Kerberos connector Before you run this sample, edit the connector configuration file to match your Kerberos environment. Specifically, set the correct values for the following properties: * `host` The host name or IP address of the machine on which Kerberos is running. * `port` The SSH port on that machine. Default: `22` (the default SSH port) * `user` The username of the account that is used to connect to the SSH server. * `password` The password of the account that is used to connect to the SSH server. * `prompt` A string that represents the remote SSH session prompt. This must be the exact prompt string, in the format `username@target:`, for example `root@localhost:~$ `. The easiest way to obtain this string is to `ssh` into the machine and copy paste the prompt. * `customConfiguration` The details of the admin user principal and the default realm. This example assumes an admin user principal of `openidm/admin`. For more information on setting this property, refer to [`customConfiguration`](https://docs.pingidentity.com/openicf/connector-reference/kerberos.html#customConfiguration). - `customSensitiveConfiguration` The password for the user principal. For more information on setting this property, refer to [`customSensitiveConfiguration`](https://docs.pingidentity.com/openicf/connector-reference/kerberos.html#customSensitiveConfiguration). Your connector configuration should look something like the following: ```json ... "configurationProperties" : { "host" : "192.0.2.0", "port" : 22, "user" : "admin", "password" : "Passw0rd", "prompt" : "admin@myhost:~$", "sudoCommand" : "/usr/bin/sudo", "echoOff" : true, "terminalType" : "vt102", "setLocale" : false, "locale" : "en_US.utf8", "connectionTimeout" : 5000, "expectTimeout" : 5000, "authenticationType" : "PASSWORD", "throwOperationTimeoutException" : true, "customConfiguration" : "kadmin { cmd = '/usr/sbin/kadmin.local'; user='openidm/admin'; default_realm='EXAMPLE.COM' }", "customSensitiveConfiguration" : "kadmin { password = 'Passw0rd'}", ... ``` IDM encrypts passwords in the configuration when it starts up, or whenever it reloads the configuration file. For information about the complete Kerberos connector configuration, refer to [Configure the Kerberos connector](https://docs.pingidentity.com/openicf/connector-reference/kerberos.html#ssh-kerberos-config). | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Do not modify the value of the `scriptRoots` or `classpath` properties unless you have extracted the scripts from the connector bundle and placed them on the filesystem. | ## Run the sample | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | Starting with IDM 8.1, the [legacy admin UI is deprecated](../release-notes/deprecated-functionality.html#legacy-admin-ui-deprecated) and is no longer bundled with IDM. New deployments should use the [Platform admin UI](../setup-guide/platform-admin-ui.html), which is the replacement for the legacy admin UI.Both UIs are available as separate downloads from the [Backstage download site](https://backstage.forgerock.com/downloads):- To install the Platform admin UI, follow the steps in [Install the Platform admin UI for standalone IDM](../setup-guide/platform-admin-ui.html). - To continue using the legacy admin UI, follow the steps in [Install the legacy admin UI](../setup-guide/legacy-admin-ui.html). | This sample demonstrates IDM communicating with the Kerberos server, creating/deleting users, and reconciling the IDM repository with Kerberos. 1. [Set up DS](start-here.html#ldap-server-config) without importing any LDIF file or [select another repository](../install-guide/chap-repository.html) for the sample. 2. Start IDM with the configuration for the Kerberos sample: ``` cd /path/to/openidm/ ./startup.sh -p samples/sync-with-kerberos ``` 3. Test that your connector configuration is correct and that IDM can reach your Kerberos server: ``` curl \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Accept-API-Version: resource=1.0" \ --request POST \ "http://localhost:8080/openidm/system?_action=test" [ { "name": "kerberos", "enabled": true, "config": "config/provisioner.openicf/kerberos", "objectTypes": [ "__ALL__", "account" ], "connectorRef": { "bundleName": "org.forgerock.openicf.connectors.kerberos-connector", "connectorName": "org.forgerock.openicf.connectors.kerberos.KerberosConnector", "bundleVersion": "[1.4.0.0,1.6.0.0)" }, "displayName": "Kerberos Connector", "ok": true } ] ``` If the command returns `"ok": true`, your configuration is correct. Continue with the sample. 4. Retrieve a list of the existing user principals in the Kerberos database: ``` curl \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Accept-API-Version: resource=1.0" \ --request GET \ "http://localhost:8080/openidm/system/kerberos/account?_queryId=query-all-ids" { "result": [ { "_id": "K/M@EXAMPLE.COM", }, { "_id": "kadmin/admin@EXAMPLE.COM", }, { "_id": "kadmin/changepw@EXAMPLE.COM", }, { "_id": "kadmin/krb1.example.com@EXAMPLE.COM", }, { "_id": "kiprop/krb1.example.com@EXAMPLE.COM", }, { "_id": "krbtgt/EXAMPLE.COM@EXAMPLE.COM", }, { "_id": "openidm/admin@EXAMPLE.COM", } ], ... } ``` 5. Create two new managed users, using REST or the admin UI. * REST * admin UI The following commands create users `bjensen` and `scarter` over REST: ``` curl \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Accept-API-Version: resource=1.0" \ --header "Content-type: application/json" \ --request POST \ --data '{ "userName": "bjensen", "givenName": "Barbara", "sn" : "Jensen", "password" : "Passw0rd", "displayName" : "Barbara Jensen", "mail" : "bjensen@example.com" }' \ "http://localhost:8080/openidm/managed/user?_action=create" { "_id": "ce3d9b8f-1d15-4950-82c1-f87596aadcb6", "_rev": "00000000792afa08", "userName": "bjensen", "givenName": "Barbara", "sn": "Jensen", "displayName": "Barbara Jensen", "mail": "bjensen@example.com", "accountStatus": "active", "effectiveRoles": [], "effectiveAssignments": [] } ``` ``` curl \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Accept-API-Version: resource=1.0" \ --header "Content-type: application/json" \ --request POST \ --data '{ "userName": "scarter", "givenName": "Steven", "sn" : "Carter", "password" : "Passw0rd", "displayName" : "Steven Carter", "mail" : "scarter@example.com" }' \ "http://localhost:8080/openidm/managed/user?_action=create" { "_id": "a204ca60-b0fc-42f8-bf93-65bb30131361", "_rev": "000000004121fb7e", "userName": "scarter", "givenName": "Steven", "sn": "Carter", "displayName": "Steven Carter", "mail": "scarter@example.com", "accountStatus": "active", "effectiveRoles": [], "effectiveAssignments": [] } ``` To create users `bjensen` and `scarter` using the admin UI, select Managed > User, and click New User. 6. Run a reconciliation operation between the managed user repository and the Kerberos database to create the new users `bjensen` and `scarter` in Kerberos. You can run the reconciliation over REST, or using the admin UI. * REST * admin UI The following command creates runs the reconciliation over REST: ``` curl \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Accept-API-Version: resource=1.0" \ --request POST \ "http://localhost:8080/openidm/recon?_action=recon&mapping=managedUser_systemKerberos" { "_id": "862ab9ba-d1d9-4058-b6bc-a23a94b68776-234", "state": "ACTIVE" } ``` To run the reconciliation using the admin UI, select Configure > Mappings, click on the `managedUser_systemKerberos` mapping, and click Reconcile. 7. Retrieve the list of Kerberos user principals again. You should now see `bjensen` and `scarter` in this list: ``` curl \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Accept-API-Version: resource=1.0" \ --request GET \ "http://localhost:8080/openidm/system/kerberos/account?_queryId=query-all-ids" { "result": [ { "_id": "bjensen@EXAMPLE.COM", }, { "_id": "scarter@EXAMPLE.COM", }, ... { "_id": "openidm/admin@EXAMPLE.COM", } ], ... } ``` 8. Retrieve the `bjensen` complete user principal from the Kerberos server over REST, or using the admin UI: * REST * admin UI ``` curl \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Accept-API-Version: resource=1.0" \ --request GET \ "http://localhost:8080/openidm/system/kerberos/account/bjensen@EXAMPLE.COM" { "_id": "bjensen@EXAMPLE.COM", "lastFailedAuthentication": "[never]", "passwordExpiration": "[none]", "lastSuccessfulAuthentication": "[never]", "maximumTicketLife": "0 days 10:00:00", "lastModified": "Tue May 24 04:05:45 EDT 2016 (openidm/admin@EXAMPLE.COM)", "policy": "user [does not exist]", "expirationDate": "[never]", "failedPasswordAttempts": "0", "maximumRenewableLife": "7 days 00:00:00", "principal": "bjensen@EXAMPLE.COM", "lastPasswordChange": "Tue May 24 04:05:45 EDT 2016" } ``` To retrieve the user using the admin UI, select Manage > User, click bjensen, and click the Linked Systems tab to display the corresponding Kerberos server entry. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | The default values for properties such as `maximumRenewableLife` are set in your connector configuration. For more information, refer to [Configure the Kerberos connector](https://docs.pingidentity.com/openicf/connector-reference/kerberos.html#ssh-kerberos-config). | 9. Delete the managed user `bjensen` by specifying the managed object ID in the DELETE request. 1. First, obtain the ID by querying the `userName`: ``` curl \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Accept-API-Version: resource=1.0" \ --request GET \ "http://localhost:8080/openidm/managed/user?_queryFilter=userName+eq+'bjensen'" { "result": [ { "_id": "ce3d9b8f-1d15-4950-82c1-f87596aadcb6", "_rev": "00000000a92657c7", "userName": "bjensen", "givenName": "Barbara", "sn": "Jensen", "displayName": "Barbara Jensen", "mail": "bjensen@example.com", "accountStatus": "active", "effectiveRoles": [], "effectiveAssignments": [] } ], ... } ``` 2. Now delete the user with ID `ce3d9b8f-1d15-4950-82c1-f87596aadcb6` over REST, or using the admin UI. This ID will be different in your example. * REST * admin UI ``` curl \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Accept-API-Version: resource=1.0" \ --request DELETE \ "http://localhost:8080/openidm/managed/user/ce3d9b8f-1d15-4950-82c1-f87596aadcb6" { "_id": "ce3d9b8f-1d15-4950-82c1-f87596aadcb6", "_rev": "00000000a92657c7", "userName": "bjensen", "givenName": "Barbara", "sn": "Jensen", "displayName": "Barbara Jensen", "mail": "bjensen@example.com", "accountStatus": "active", "effectiveRoles": [], "effectiveAssignments": [] } ``` To delete managed user `bjensen` using the admin UI, select Manage > User, select the checkbox adjacent to bjensen, and click Delete Selected. 10. Reconcile the managed user repository and the Kerberos database again: ``` curl \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Accept-API-Version: resource=1.0" \ --request POST \ "http://localhost:8080/openidm/recon?_action=recon&mapping=managedUser_systemKerberos" { "_id": "862ab9ba-d1d9-4058-b6bc-a23a94b68776-584", "state": "ACTIVE" } ``` 11. Retrieve the list of Kerberos user principals again. The Kerberos principal for `bjensen` should not exist: ``` curl \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Accept-API-Version: resource=1.0" \ --request GET \ "http://localhost:8080/openidm/system/kerberos/account?_queryId=query-all-ids" { "result": [ { "_id": "K/M@EXAMPLE.COM", }, { "_id": "kadmin/admin@EXAMPLE.COM", }, { "_id": "kadmin/changepw@EXAMPLE.COM", }, { "_id": "kadmin/krb1.example.com@EXAMPLE.COM", }, { "_id": "kiprop/krb1.example.com@EXAMPLE.COM", }, { "_id": "krbtgt/EXAMPLE.COM@EXAMPLE.COM", }, { "_id": "scarter@EXAMPLE.COM", }, { "_id": "openidm/admin@EXAMPLE.COM", } ], ... } ``` | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Some user IDs in Kerberos include characters such as a forward slash (`/`) and an "at sign" (`@`) that prevent them from being used directly in a REST URL. For example, `openidm/system/kerberos/account/kadmin/admin@EXAMPLE.COM`, where the ID is `kadmin/admin@EXAMPLE.COM`. To retrieve such entries directly over REST, you must URL-encode the Kerberos ID; for example:```none "http://localhost:8080/openidm/system/kerberos/account/kadmin%2Fadmin%40EXAMPLE.COM" ``` |