From 190ce1a48e95e70b8ebfe76589b214e4b05cc2b5 Mon Sep 17 00:00:00 2001 From: Les Williams Date: Fri, 15 Dec 2017 10:07:01 -0500 Subject: [PATCH] Finished editing revisions for Admin CLI I went through all of the recommendations and implemented them. Please let me know if I did not interpret the recommendations correctly. --- server_admin/topics/admin-cli.adoc | 223 ++++++++++++++--------------- 1 file changed, 111 insertions(+), 112 deletions(-) diff --git a/server_admin/topics/admin-cli.adoc b/server_admin/topics/admin-cli.adoc index 5ced543f16..26b0ce7818 100644 --- a/server_admin/topics/admin-cli.adoc +++ b/server_admin/topics/admin-cli.adoc @@ -55,7 +55,7 @@ For example, on ---- $ kcadm.sh config credentials --server http://localhost:8080/auth --realm demo --user admin --client admin $ kcadm.sh create realms -s realm=demorealm -s enabled=true -o -$ CID=$(kcadm.sh create clients -r demorealm -s clientId=my_client -s 'redirectUris=["http://localhost:8980/myapp/*"]' -i) +$ C=$(kcadm.sh create clients -r demorealm -s clientId=my_client -s 'redirectUris=["http://localhost:8980/myapp/*"]' -i) $ kcadm.sh get clients/$CID/installation/providers/keycloak-oidc-keycloak-json ---- + @@ -206,6 +206,7 @@ By default, the [commamd]`update` command first performs a [command]`get` and th === Realm operations +[discrete] ==== Creating a new realm Use the [command]`create` command on the `realms` endpoint to create a new enabled realm, and set the attributes to `realm` and `enabled`. @@ -240,7 +241,7 @@ EOF c:\> echo { "realm": "demorealm", "enabled": true } | kcadm create realms -f - ---- - +[discrete] ==== Listing existing realms The following command returns a list of all realms. @@ -266,6 +267,7 @@ You can also display the result as comma separated values. $ kcadm.sh get realms --fields realm --format csv --noquotes ---- +[discrete] ==== Getting a specific realm You append a realm name to a collection URI to get an individual realm. @@ -274,7 +276,7 @@ You append a realm name to a collection URI to get an individual realm. $ kcadm.sh get realms/master ---- - +[discrete] ==== Updating a realm . Use the [command]`-s` option to set new values for the attributes when you want to change only some of the realm's attributes. @@ -285,7 +287,7 @@ For example: ---- $ kcadm.sh update realms/demorealm -s enabled=false ---- -. If you want to set all writable attributes with new values, perform a [command]`get`, edit the current values in the JSON file, and resubmit. +. If you want to set all writable attributes with new values, run a [command]`get` command, edit the current values in the JSON file, and resubmit. + For example: + @@ -296,7 +298,7 @@ $ vi demorealm.json $ kcadm.sh update realms/demorealm -f demorealm.json ---- - +[discrete] ==== Deleting a realm Run the following command to delete a realm. @@ -305,7 +307,7 @@ Run the following command to delete a realm. $ kcadm.sh delete realms/demorealm ---- - +[discrete] ==== Turning on all login page options for the realm Set the attributes controlling specific capabilities to `true`. @@ -316,7 +318,7 @@ For example: $ kcadm.sh update realms/demorealm -s registrationAllowed=true -s registrationEmailAsUsername=true -s rememberMe=true -s verifyEmail=true -s resetPasswordAllowed=true -s editUsernameAllowed=true ---- - +[discrete] ==== Listing the realm keys Use the [command]`get` operation on the [filename]`keys` endpoint of the target realm. @@ -325,7 +327,7 @@ Use the [command]`get` operation on the [filename]`keys` endpoint of the target $ kcadm.sh get keys -r demorealm ---- - +[discrete] ==== Generating new realm keys . Get the ID of the target realm before adding a new RSA-generated key pair. @@ -352,11 +354,11 @@ $ kcadm.sh create components -r demorealm -s name=rsa-generated -s providerId=rs ---- c:\> kcadm create components -r demorealm -s name=rsa-generated -s providerId=rsa-generated -s providerType=org.keycloak.keys.KeyProvider -s parentId=959844c1-d149-41d7-8359-6aa527fca0b0 -s "config.priority=[\"101\"]" -s "config.enabled=[\"true\"]" -s "config.active=[\"true\"]" -s "config.keySize=[\"2048\"]" ---- -. Set the `parentId` attribute to the value of target realm's ID. +. Set the `parentId` attribute to the value of the target realm's ID. + The newly added key should now become the active key as revealed by [command]`kcadm.sh get keys -r demorealm`. - +[discrete] ==== Adding new realm keys from a Java Key Store file . Add a new key provider to add a new key pair already prepared as a JKS file on the server. @@ -376,9 +378,9 @@ $ kcadm.sh create components -r demorealm -s name=java-keystore -s providerId=ja c:\> kcadm create components -r demorealm -s name=java-keystore -s providerId=java-keystore -s providerType=org.keycloak.keys.KeyProvider -s parentId=959844c1-d149-41d7-8359-6aa527fca0b0 -s "config.priority=[\"101\"]" -s "config.enabled=[\"true\"]" -s "config.active=[\"true\"]" -s "config.keystore=[\"/opt/keycloak/keystore.jks\"]" -s "config.keystorePassword=[\"secret\"]" -s "config.keyPassword=[\"secret\"]" -s "config.alias=[\"localhost\"]" ---- . Make sure to change the attribute values for `keystore`, `keystorePassword`, `keyPassword`, and `alias` to match your specific keystore. -. Set the `parentId` attribute to the value of target realm's ID. - +. Set the `parentId` attribute to the value of the target realm's ID. +[discrete] ==== Making the key passive or disabling the key . Identify the key you want to make passive @@ -409,7 +411,7 @@ You can update other key attributes. . Set a new `enabled` value to disable the key, for example, `config.enabled=["false"]`. . Set a new `priority` value to change the key's priority, for example, `config.priority=["110"]`. - +[discrete] ==== Deleting an old key . Make sure the key you are deleting has been passive and disabled to prevent any existing tokens held by applications and users from abruptly failing to work. @@ -426,7 +428,7 @@ $ kcadm.sh get keys -r demorealm $ kcadm.sh delete components/PROVIDER_ID -r demorealm ---- - +[discrete] ==== Configuring event logging for a realm Use the [command]`update` command on the [filename]`events/config` endpoint. @@ -487,7 +489,7 @@ Here is an example of how to delete all saved events. $ kcadm delete events ---- - +[discrete] ==== Flushing the caches . Use the [command]`create` command and one of the following endpoints: [filename]`clear-realm-cache`, [filename]`clear-user-cache`, or [filename]`clear-keys-cache`. @@ -505,6 +507,7 @@ $ kcadm.sh create clear-keys-cache -r demorealm -s realm=demorealm === Role operations +[discrete] ==== Creating a realm role Use the [filename]`roles` endpoint to create a realm role. @@ -513,6 +516,7 @@ Use the [filename]`roles` endpoint to create a realm role. $ kcadm.sh create roles -r demorealm -s name=user -s 'description=Regular user with limited set of permissions' ---- +[discrete] ==== Creating a client role . Identify the client first and then use the [command]`get` command to list available clients when creating a client role. @@ -521,7 +525,7 @@ $ kcadm.sh create roles -r demorealm -s name=user -s 'description=Regular user w ---- $ kcadm.sh get clients -r demorealm --fields id,clientId ---- -. Create a new role by using the client's ID attribute to construct an endpoint URI, such as [filename]`clients/ID/roles`. +. Create a new role by using the [command]`clientId` attribute to construct an endpoint URI, such as [filename]`clients/ID/roles`. + For example: + @@ -530,7 +534,7 @@ For example: $ kcadm.sh create clients/a95b6af3-0bdc-4878-ae2e-6d61a4eca9a0/roles -r demorealm -s name=editor -s 'description=Editor can edit, and publish any article' ---- - +[discrete] ==== Listing realm roles Use the [command]`get` command on the [filename]`roles` endpoint to list existing realm roles. @@ -544,12 +548,12 @@ You can also use the [command]`get-roles` command. $ kcadm.sh get-roles -r demorealm ---- - +[discrete] ==== Listing client roles There is a dedicated [command]`get-roles` command to simplify listing realm and client roles. It is an extension of the [command]`get` command and behaves the same with additional semantics for listing roles. -Use the [command]`get-roles` command, passing it either [command]`clientId` (via the [command]`--cclientid` option) or [command]`id` (via the [command]`--cid` option) to identify the client to list client roles. +Use the [command]`get-roles` command, passing it either the clientId attribute (via the [command]`--cclientid` option) or [command]`id` (via the [command]`--cid` option) to identify the client to list client roles. For example: [options="nowrap"] @@ -557,10 +561,10 @@ For example: $ kcadm.sh get-roles -r demorealm --cclientid realm-management ---- - +[discrete] ==== Getting a specific realm role -Use the [command]`get` command and the role [filename]`name` to construct an endpoint UIR for a specific realm role: [filename]`roles/ROLE_NAME`, where [filename]`user` is the name of the existing role. +Use the [command]`get` command and the role [filename]`name` to construct an endpoint URI for a specific realm role: [filename]`roles/ROLE_NAME`, where [filename]`user` is the name of the existing role. For example: [options="nowrap"] @@ -576,10 +580,10 @@ For example: $ kcadm.sh get-roles -r demorealm --rolename user ---- - +[discrete] ==== Getting a specific client role -Use a dedicated [command]`get-roles` command, passing it either client ID (via the [command]`--cclientid` option) or ID (via the [command]`--cid` option) to identify the client, and passing it either the role name (via the [command]`--rolename` option) or ID (via the [command]`--roleid`) to identify a specific client role. +Use a dedicated [command]`get-roles` command, passing it either the clientId attribute (via the [command]`--cclientid` option) or ID (via the [command]`--cid` option) to identify the client, and passing it either the role name (via the [command]`--rolename` option) or ID (via the [command]`--roleid`) to identify a specific client role. For example: [options="nowrap"] @@ -587,7 +591,7 @@ For example: $ kcadm.sh get-roles -r demorealm --cclientid realm-management --rolename manage-clients ---- - +[discrete] ==== Updating a realm role Use the [command]`update` command with the same endpoint URI that you used to get a specific realm role. @@ -598,7 +602,7 @@ For example: $ kcadm.sh update roles/user -r demorealm -s 'description=Role representing a regular user' ---- - +[discrete] ==== Updating a client role Use the [command]`update` command with the same endpoint URI that you used to get a specific client role. @@ -609,7 +613,7 @@ For example: $ kcadm.sh update clients/a95b6af3-0bdc-4878-ae2e-6d61a4eca9a0/roles/editor -r demorealm -s 'description=User that can edit, and publish articles' ---- - +[discrete] ==== Deleting a realm role Use the [command]`delete` command with the same endpoint URI that you used to get a specific realm role. @@ -620,7 +624,7 @@ For example: $ kcadm.sh delete roles/user -r demorealm ---- - +[discrete] ==== Deleting a client role Use the [command]`delete` command with the same endpoint URI that you used to get a specific client role. @@ -631,7 +635,7 @@ For example: $ kcadm.sh delete clients/a95b6af3-0bdc-4878-ae2e-6d61a4eca9a0/roles/editor -r demorealm ---- - +[discrete] ==== Listing assigned, available, and effective realm roles for a composite role Use a dedicated [command]`get-roles` command to list assigned, available, and effective realm roles for a composite role. @@ -661,12 +665,12 @@ For example: $ kcadm.sh get-roles -r demorealm --rname testrole --available ---- - +[discrete] ==== Listing assigned, available, and effective client roles for a composite role Use a dedicated [command]`get-roles` command to list assigned, available, and effective client roles for a composite role. -. To list *assigned* client roles for the composite role, you can specify the target composite role by either name (via the [command]`--rname` option) or ID (via the [command]`--rid` option) and client by either client ID (via the [command]`--cclientid` option) or ID (via the [command]`--cid` option). +. To list *assigned* client roles for the composite role, you can specify the target composite role by either name (via the [command]`--rname` option) or ID (via the [command]`--rid` option) and client by either the clientId attribute (via the [command]`--cclientid` option) or ID (via the [command]`--cid` option). + For example: + @@ -691,7 +695,7 @@ For example: $ kcadm.sh get-roles -r demorealm --rname testrole --cclientid realm-management --available ---- - +[discrete] ==== Adding realm roles to a composite role There is a dedicated [command]`add-roles` command that can be used for adding realm roles and client roles. @@ -702,7 +706,7 @@ The following example adds the [command]`user` role to the composite role [comma $ kcadm.sh add-roles --rname testrole --rolename user -r demorealm ---- - +[discrete] ==== Removing realm roles from a composite role There is a dedicated [command]`remove-roles` command that can be used to remove realm roles and client roles. @@ -713,11 +717,9 @@ The following example removes the [command]`user` role from the target composite $ kcadm.sh remove-roles --rname testrole --rolename user -r demorealm ---- - +[discrete] ==== Adding client roles to a realm role -You can create or modify a composite realm role. - Use a dedicated [command]`add-roles` command that can be used for adding realm roles and client roles. The following example adds the roles defined on the client [command]`realm-management` - `create-client` role and the [command]`view-users` role to the [command]`testrole` composite role. @@ -726,11 +728,9 @@ The following example adds the roles defined on the client [command]`realm-manag $ kcadm.sh add-roles -r demorealm --rname testrole --cclientid realm-management --rolename create-client --rolename view-users ---- - +[discrete] ==== Adding client roles to a client role -You can create or modify a composite client role. - . Determine the ID of the composite client role by using the [command]`get-roles` command. + For example: @@ -739,9 +739,7 @@ For example: ---- $ kcadm.sh get-roles -r demorealm --cclientid test-client --rolename operations ---- -. Assume that there is a client with client ID of [filename]`test-client`, a client role called [filename]`support`, and another client role, which becomes a composite role, that has an ID of `"fc400897-ef6a-4e8c-872b-1581b7fa8a71", "name":"operations"`. -+ -In this example, [filename]`operations` is the target composite role, and the role's ID precedes [filename]`operations`. +. Assume that there is a client with a clientId attribute of [filename]`test-client`, a client role called [filename]`support`, and another client role called [filename]`operations`, which becomes a composite role, that has an ID of "fc400897-ef6a-4e8c-872b-1581b7fa8a71". . Use the following example to add another role to the composite role. + [options="nowrap"] @@ -757,7 +755,7 @@ For example: $ kcadm.sh get-roles --rid fc400897-ef6a-4e8c-872b-1581b7fa8a71 --all ---- - +[discrete] ==== Removing client roles from a composite role Use a dedicated [command]`remove-roles` command to remove client roles from a composite role. @@ -771,6 +769,7 @@ $ kcadm.sh remove-roles -r demorealm --rname testrole --cclientid realm-manageme === Client operations +[discrete] ==== Creating a client . Run the [command]`create` command on a [filename]`clients` endpoint to create a new client. @@ -790,7 +789,7 @@ For example: $ kcadm.sh create clients -r demorealm -s clientId=myapp -s enabled=true -s clientAuthenticatorType=client-secret -s secret=d0b8122f-8dfb-46b7-b68a-f5cc4e25d000 ---- - +[discrete] ==== Listing clients Use the [command]`get` command on the [filename]`clients` endpoint to list clients. @@ -802,7 +801,7 @@ $ kcadm.sh get clients -r demorealm --fields id,clientId ---- This example filters the output to list only the [filename]`id` and [filename]`clientId` attributes. - +[discrete] ==== Getting a specific client Use a client's ID to construct an endpoint URI that targets a specific client, such as [filename]`clients/ID`. @@ -813,7 +812,7 @@ For example: $ kcadm.sh get clients/c7b8547f-e748-4333-95d0-410b76b3f4a3 -r demorealm ---- - +[discrete] ==== Getting the current secret for a specific client Use a client's ID to construct an endpoint URI, such as [filename]`clients/ID/client-secret`. @@ -824,7 +823,7 @@ For example: $ kcadm.sh get clients/$CID/client-secret ---- - +[discrete] ==== Getting an adapter configuration file (keycloak.json) for a specific client Use a client's ID to construct an endpoint URI that targets a specific client, such as [filename]`clients/ID/installation/providers/keycloak-oidc-keycloak-json`. @@ -835,7 +834,7 @@ For example: $ kcadm.sh get clients/c7b8547f-e748-4333-95d0-410b76b3f4a3/installation/providers/keycloak-oidc-keycloak-json -r demorealm ---- - +[discrete] ==== Getting a Wildfly subsystem adapter configuration for a specific client Use a client's ID to construct an endpoint URI that targets a specific client, such as [filename]`clients/ID/installation/providers/keycloak-oidc-jboss-subsystem`. @@ -846,7 +845,7 @@ For example: $ kcadm.sh get clients/c7b8547f-e748-4333-95d0-410b76b3f4a3/installation/providers/keycloak-oidc-jboss-subsystem -r demorealm ---- - +[discrete] ==== Updating a client Use the [command]`update` command with the same endpoint URI that you used to get a specific client. @@ -864,7 +863,7 @@ $ kcadm.sh update clients/c7b8547f-e748-4333-95d0-410b76b3f4a3 -r demorealm -s e c:\> kcadm update clients/c7b8547f-e748-4333-95d0-410b76b3f4a3 -r demorealm -s enabled=false -s publicClient=true -s "redirectUris=[\"http://localhost:8080/myapp/*\"]" -s baseUrl=http://localhost:8080/myapp -s adminUrl=http://localhost:8080/myapp ---- - +[discrete] ==== Deleting a client Use the [command]`delete` command with the same endpoint URI that you used to get a specific client. @@ -878,7 +877,7 @@ $ kcadm.sh delete clients/c7b8547f-e748-4333-95d0-410b76b3f4a3 -r demorealm === User operations - +[discrete] ==== Creating a user Run the [command]`create` command on the [filename]`users` endpoint to create a new user. @@ -889,10 +888,10 @@ For example: $ kcadm.sh create users -r demorealm -s username=testuser -s enabled=true ---- - +[discrete] ==== Listing users -Use the [filename]`users` endpoint to list users. The number of users might be large; consider limiting how many users are returned. +Use the [filename]`users` endpoint to list users. The target user will have to change the password the next time they log in. For example: [options="nowrap"] @@ -913,7 +912,7 @@ Filtering does not use exact matching. For example, the above example would matc ==== You can also filter across multiple attributes by specifying multiple [command]`-q` options, which return only users that match the condition for all the attributes. - +[discrete] ==== Getting a specific user Use a user's ID to compose an endpoint URI, such as [filename]`users/USER_ID`. @@ -924,7 +923,7 @@ For example: $ kcadm.sh get users/0ba7a3fd-6fd8-48cd-a60b-2e8fd82d56e2 -r demorealm ---- - +[discrete] ==== Updating a user Use the [command]`update` command with the same endpoint URI that you used to get a specific user. @@ -942,7 +941,7 @@ $ kcadm.sh update users/0ba7a3fd-6fd8-48cd-a60b-2e8fd82d56e2 -r demorealm -s 're c:\> kcadm update users/0ba7a3fd-6fd8-48cd-a60b-2e8fd82d56e2 -r demorealm -s "requiredActions=[\"VERIFY_EMAIL\",\"UPDATE_PROFILE\",\"CONFIGURE_TOTP\",\"UPDATE_PASSWORD\"]" ---- - +[discrete] ==== Deleting a user Use the [command]`delete` command with the same endpoint URI that you used to get a specific user. @@ -953,7 +952,7 @@ For example: $ kcadm.sh delete users/0ba7a3fd-6fd8-48cd-a60b-2e8fd82d56e2 -r demorealm ---- - +[discrete] ==== Resetting a user's password Use the dedicated [command]`set-password` command to reset a user's password. @@ -963,9 +962,9 @@ For example: ---- $ kcadm.sh set-password -r demorealm --username testuser --new-password NEWPASSWORD --temporary ---- -That command sets a temporary password for the user. Change the temporary password the next time you log in. +That command sets a temporary password for the user. The target user will have to change the password the next time they log in. -You can use the [command]`--userid` to specify the user by using the [command]`id` attribute. +You can use [command]`--userid` if you want to specify the user by using the [filename]`id` attribute. You can achieve the same result using the [command]`update` command on an endpoint constructed from the one you used to get a specific user, such as [filename]`users/USER_ID/reset-password`. @@ -976,7 +975,7 @@ $ kcadm.sh update users/0ba7a3fd-6fd8-48cd-a60b-2e8fd82d56e2/reset-password -r d ---- The last parameter ([command]`-n`) ensures that only the [command]`PUT` command is performed without a prior [command]`GET` command. It is necessary in this instance because the [command]`reset-password` endpoint does not support [command]`GET`. - +[discrete] ==== Listing assigned, available, and effective realm roles for a user You can use a dedicated [command]`get-roles` command to list assigned, available, and effective realm roles for a user. @@ -1005,12 +1004,12 @@ For example: $ kcadm.sh get-roles -r demorealm --uusername testuser --available ---- - +[discrete] ==== Listing assigned, available, and effective client roles for a user Use a dedicated [command]`get-roles` command to list assigned, available, and effective client roles for a user. -. Specify the target user by either a user name (via the [command]`--uusername` option) or an ID (via the [command]`--uid` option) and client by either a client ID (via the [command]`--cclientid` option) or an ID (via the [command]`--cid` option) to list *assigned* client roles for the user. +. Specify the target user by either a user name (via the [command]`--uusername` option) or an ID (via the [command]`--uid` option) and client by either a clientId attribute (via the [command]`--cclientid` option) or an ID (via the [command]`--cid` option) to list *assigned* client roles for the user. + For example: + @@ -1035,7 +1034,7 @@ For example: $ kcadm.sh get-roles -r demorealm --uusername testuser --cclientid realm-management --available ---- - +[discrete] ==== Adding realm roles to a user Use a dedicated [command]`add-roles` command to add realm roles to a user. @@ -1046,7 +1045,7 @@ Use the following example to add the [command]`user` role to user [command]`test $ kcadm.sh add-roles --username testuser --rolename user -r demorealm ---- - +[discrete] ==== Removing realm roles from a user Use a dedicated [command]`remove-roles` command to remove realm roles from a user. @@ -1057,7 +1056,7 @@ Use the following example to remove the [command]`user` role from the user [comm $ kcadm.sh remove-roles --username testuser --rolename user -r demorealm ---- - +[discrete] ==== Adding client roles to a user Use a dedicated [command]`add-roles` command to add client roles to a user. @@ -1068,18 +1067,18 @@ Use the following example to add two roles defined on the client [command]`realm $ kcadm.sh add-roles -r demorealm --uusername testuser --cclientid realm-management --rolename create-client --rolename view-users ---- - +[discrete] ==== Removing client roles from a user Use a dedicated [command]`remove-roles` command to remove client roles from a user. -Use the following example to remove two roles defined on the client [command]`realm management` - `create-client` role and the [command]`view-users` role from the user `testuser`. +Use the following example to remove two roles defined on the realm management client. [options="nowrap"] ---- $ kcadm.sh remove-roles -r demorealm --uusername testuser --cclientid realm-management --rolename create-client --rolename view-users ---- - +[discrete] ==== Listing a user's sessions . Identify the user's ID, and then use it to compose an endpoint URI, such as [filename]`users/ID/sessions`. @@ -1092,7 +1091,7 @@ For example: $kcadm get users/6da5ab89-3397-4205-afaa-e201ff638f9e/sessions ---- - +[discrete] ==== Logging out a user from a specific session . Determine the session's ID as described above. @@ -1106,7 +1105,7 @@ For example: $ kcadm.sh delete sessions/d0eaa7cc-8c5d-489d-811a-69d3c4ec84d1 ---- - +[discrete] ==== Logging out a user from all sessions You need a user's ID to construct an endpoint URI, such as [filename]`users/ID/logout`. @@ -1122,7 +1121,7 @@ $ kcadm.sh create users/6da5ab89-3397-4205-afaa-e201ff638f9e/logout -r demorealm === Group operations - +[discrete] ==== Creating a group Use the [command]`create` command on the [filename]`groups` endpoint to create a new group. @@ -1133,7 +1132,7 @@ For example: $ kcadm.sh create groups -r demorealm -s name=Group ---- - +[discrete] ==== Listing groups Use the [command]`get` command on the [filename]`groups` endpoint to list groups. @@ -1144,7 +1143,7 @@ For example: $ kcadm.sh get groups -r demorealm ---- - +[discrete] ==== Getting a specific group Use the group's ID to construct an endpoint URI, such as `groups/GROUP_ID`. @@ -1155,7 +1154,7 @@ For example: $ kcadm.sh get groups/51204821-0580-46db-8f2d-27106c6b5ded -r demorealm ---- - +[discrete] ==== Updating a group Use the [command]`update` command with the same endpoint URI that you used to get a specific group. @@ -1166,7 +1165,7 @@ For example: $ kcadm.sh update groups/51204821-0580-46db-8f2d-27106c6b5ded -s 'attributes.email=["group@example.com"]' -r demorealm ---- - +[discrete] ==== Deleting a group Use the [command]`delete` command with the same endpoint URI that you used to get a specific group. @@ -1177,7 +1176,7 @@ For example: $ kcadm.sh delete groups/51204821-0580-46db-8f2d-27106c6b5ded -r demorealm ---- - +[discrete] ==== Creating a subgroup Find the ID of the parent group by listing groups, and then use that ID to construct an endpoint URI, such as [filename]`groups/GROUP_ID/children`. @@ -1188,7 +1187,7 @@ For example: $ kcadm.sh create groups/51204821-0580-46db-8f2d-27106c6b5ded/children -r demorealm -s name=SubGroup ---- - +[discrete] ==== Moving a group under another group . Find the ID of an existing parent group and of an existing child group. @@ -1201,7 +1200,7 @@ For example: $ kcadm.sh create groups/51204821-0580-46db-8f2d-27106c6b5ded/children -r demorealm -s id=08d410c6-d585-4059-bb07-54dcb92c5094 ---- - +[discrete] ==== Get groups for a specific user Use a user's ID to determine a user's membership in groups to compose an endpoint URI, such as [filename]`users/USER_ID/groups`. @@ -1212,7 +1211,7 @@ For example: $ kcadm.sh get users/b544f379-5fc4-49e5-8a8d-5cfb71f46f53/groups -r demorealm ---- - +[discrete] ==== Adding a user to a group Use the [command]`update` command with an endpoint URI composed from user's ID and a group's ID, such as [filename]`users/USER_ID/groups/GROUP_ID`, to add a user to a group. @@ -1223,7 +1222,7 @@ For example: $ kcadm.sh update users/b544f379-5fc4-49e5-8a8d-5cfb71f46f53/groups/ce01117a-7426-4670-a29a-5c118056fe20 -r demorealm -s realm=demorealm -s userId=b544f379-5fc4-49e5-8a8d-5cfb71f46f53 -s groupId=ce01117a-7426-4670-a29a-5c118056fe20 -n ---- - +[discrete] ==== Removing a user from a group Use the [command]`delete` command on the same endpoint URI as used for adding a user to a group, such as [filename]`users/USER_ID/groups/GROUP_ID`, to remove a user from a group. @@ -1234,7 +1233,7 @@ For example: $ kcadm.sh delete users/b544f379-5fc4-49e5-8a8d-5cfb71f46f53/groups/ce01117a-7426-4670-a29a-5c118056fe20 -r demorealm ---- - +[discrete] ==== Listing assigned, available, and effective realm roles for a group Use a dedicated [command]`get-roles` command to list assigned, available, and effective realm roles for a group. @@ -1264,12 +1263,12 @@ For example: $ kcadm.sh get-roles -r demorealm --gname Group --available ---- - +[discrete] ==== Listing assigned, available, and effective client roles for a group Use a dedicated [command]`get-roles` command to list assigned, available, and effective client roles for a group. -. Specify the target group by either name (via the [command]`--gname` option) or ID (via the [command]`--gid` option), and client by either client ID (via the [command] `--cclientid` option) or ID (via the [command]`--id` option) to list *assigned* client roles for the user. +. Specify the target group by either name (via the [command]`--gname` option) or ID (via the [command]`--gid` option), and client by either the clientId attribute (via the [command] `--cclientid` option) or ID (via the [command]`--id` option) to list *assigned* client roles for the user. + For example: + @@ -1297,7 +1296,7 @@ $ kcadm.sh get-roles -r demorealm --gname Group --cclientid realm-management --a === Identity provider operations - +[discrete] ==== Listing available identity providers Use the [filename]`serverinfo` endpoint to list available identity providers. @@ -1312,7 +1311,7 @@ $ kcadm.sh get serverinfo -r demorealm --fields 'identityProviders(*)' The [filename]`serverinfo` endpoint is handled similarly to the [filename]`realms` endpoint in that it is not resolved relative to a target realm because it exists outside any specific realm. ==== - +[discrete] ==== Listing configured identity providers Use the [filename]`identity-provider/instances` endpoint. @@ -1323,7 +1322,7 @@ For example: $ kcadm.sh get identity-provider/instances -r demorealm --fields alias,providerId,enabled ---- - +[discrete] ==== Getting a specific configured identity provider Use the [command]`alias` attribute of the identity provider to construct an endpoint URI, such as [filename]`identity-provider/instances/ALIAS`, to get a specific identity provider. @@ -1334,7 +1333,7 @@ For example: $ kcadm.sh get identity-provider/instances/facebook -r demorealm ---- - +[discrete] ==== Removing a specific configured identity provider Use the [command]`delete` command with the same endpoint URI that you used to get a specific configured identity provider to remove a specific configured identity provider. @@ -1345,7 +1344,7 @@ For example: $ kcadm.sh delete identity-provider/instances/facebook -r demorealm ---- - +[discrete] ==== Configuring a Keycloak OpenID Connect identity provider . Use [command]`keycloak-oidc` as the [command]`providerId` when creating a new identity provider instance. @@ -1358,12 +1357,12 @@ For example: $ kcadm.sh create identity-provider/instances -r demorealm -s alias=keycloak-oidc -s providerId=keycloak-oidc -s enabled=true -s 'config.useJwksUrl="true"' -s config.authorizationUrl=http://localhost:8180/auth/realms/demorealm/protocol/openid-connect/auth -s config.tokenUrl=http://localhost:8180/auth/realms/demorealm/protocol/openid-connect/token -s config.clientId=demo-oidc-provider -s config.clientSecret=secret ---- - +[discrete] ==== Configuring an OpenID Connect identity provider Configure the generic OpenID Connect provider the same way you configure the Keycloak OpenID Connect provider, except that you set the [command]`providerId` attribute value to [command]`oidc`. - +[discrete] ==== Configuring a SAML 2 identity provider . Use [command]`saml` as the [command]`providerId`. @@ -1375,7 +1374,7 @@ For example: $ kcadm.sh create identity-provider/instances -r demorealm -s alias=saml -s providerId=saml -s enabled=true -s 'config.useJwksUrl="true"' -s config.singleSignOnServiceUrl=http://localhost:8180/auth/realms/saml-broker-realm/protocol/saml -s config.nameIDPolicyFormat=urn:oasis:names:tc:SAML:2.0:nameid-format:persistent -s config.signatureAlgorithm=RSA_SHA256 ---- - +[discrete] ==== Configuring a Facebook identity provider . Use [command]`facebook` as the [command]`providerId`. @@ -1388,7 +1387,7 @@ For example: $ kcadm.sh create identity-provider/instances -r demorealm -s alias=facebook -s providerId=facebook -s enabled=true -s 'config.useJwksUrl="true"' -s config.clientId=FACEBOOK_CLIENT_ID -s config.clientSecret=FACEBOOK_CLIENT_SECRET ---- - +[discrete] ==== Configuring a Google identity provider . Use [command]`google` as the [command]`providerId`. @@ -1401,7 +1400,7 @@ For example: $ kcadm.sh create identity-provider/instances -r demorealm -s alias=google -s providerId=google -s enabled=true -s 'config.useJwksUrl="true"' -s config.clientId=GOOGLE_CLIENT_ID -s config.clientSecret=GOOGLE_CLIENT_SECRET ---- - +[discrete] ==== Configuring a Twitter identity provider . Use [command]`twitter` as the [command]`providerId`. @@ -1414,7 +1413,7 @@ For example: $ kcadm.sh create identity-provider/instances -r demorealm -s alias=google -s providerId=google -s enabled=true -s 'config.useJwksUrl="true"' -s config.clientId=TWITTER_API_KEY -s config.clientSecret=TWITTER_API_SECRET ---- - +[discrete] ==== Configuring a GitHub identity provider . Use [command]`github` as the [command]`providerId`. @@ -1427,7 +1426,7 @@ For example: $ kcadm.sh create identity-provider/instances -r demorealm -s alias=github -s providerId=github -s enabled=true -s 'config.useJwksUrl="true"' -s config.clientId=GITHUB_CLIENT_ID -s config.clientSecret=GITHUB_CLIENT_SECRET ---- - +[discrete] ==== Configuring a LinkedIn identity provider . Use [command]`linkedin` as the [command]`providerId`. @@ -1440,7 +1439,7 @@ For example: $ kcadm.sh create identity-provider/instances -r demorealm -s alias=linkedin -s providerId=linkedin -s enabled=true -s 'config.useJwksUrl="true"' -s config.clientId=LINKEDIN_CLIENT_ID -s config.clientSecret=LINKEDIN_CLIENT_SECRET ---- - +[discrete] ==== Configuring a Microsoft Live identity provider . Use [command]`microsoft` as the [command]`providerId`. @@ -1453,7 +1452,7 @@ For example: $ kcadm.sh create identity-provider/instances -r demorealm -s alias=microsoft -s providerId=microsoft -s enabled=true -s 'config.useJwksUrl="true"' -s config.clientId=MICROSOFT_APP_ID -s config.clientSecret=MICROSOFT_PASSWORD ---- - +[discrete] ==== Configuring a StackOverflow identity provider . Use `stackoverflow` command as the [command]`providerId`. @@ -1469,7 +1468,7 @@ $ kcadm.sh create identity-provider/instances -r demorealm -s alias=stackoverflo === Storage provider operations - +[discrete] ==== Configuring a Kerberos storage provider . Use the [command]`create` command against the [filename]`user-federation/instances` endpoint. @@ -1482,7 +1481,7 @@ For example: $ kcadm.sh create user-federation/instances -r demorealm -s providerName=kerberos -s priority=0 -s config.debug=false -s config.allowPasswordAuthentication=true -s 'config.editMode="UNSYNCED"' -s config.updateProfileFirstLogin=true -s config.allowKerberosAuthentication=true -s 'config.kerberosRealm="KEYCLOAK.ORG"' -s 'config.keyTab="http.keytab"' -s 'config.serverPrincipal="HTTP/localhost@KEYCLOAK.ORG"' ---- - +[discrete] ==== Configuring an LDAP user storage provider . Use the [command]`create` command against the [filename]`components` endpoint. @@ -1495,7 +1494,7 @@ $ kcadm.sh create user-federation/instances -r demorealm -s providerName=kerbero $ kcadm.sh create components -r demorealm -s name=kerberos-ldap-provider -s providerId=ldap -s providerType=org.keycloak.storage.UserStorageProvider -s parentId=3d9c572b-8f33-483f-98a6-8bb421667867 -s 'config.priority=["1"]' -s 'config.fullSyncPeriod=["-1"]' -s 'config.changedSyncPeriod=["-1"]' -s 'config.cachePolicy=["DEFAULT"]' -s config.evictionDay=[] -s config.evictionHour=[] -s config.evictionMinute=[] -s config.maxLifespan=[] -s 'config.batchSizeForSync=["1000"]' -s 'config.editMode=["WRITABLE"]' -s 'config.syncRegistrations=["false"]' -s 'config.vendor=["other"]' -s 'config.usernameLDAPAttribute=["uid"]' -s 'config.rdnLDAPAttribute=["uid"]' -s 'config.uuidLDAPAttribute=["entryUUID"]' -s 'config.userObjectClasses=["inetOrgPerson, organizationalPerson"]' -s 'config.connectionUrl=["ldap://localhost:10389"]' -s 'config.usersDn=["ou=People,dc=keycloak,dc=org"]' -s 'config.authType=["simple"]' -s 'config.bindDn=["uid=admin,ou=system"]' -s 'config.bindCredential=["secret"]' -s 'config.searchScope=["1"]' -s 'config.useTruststoreSpi=["ldapsOnly"]' -s 'config.connectionPooling=["true"]' -s 'config.pagination=["true"]' -s 'config.allowKerberosAuthentication=["true"]' -s 'config.serverPrincipal=["HTTP/localhost@KEYCLOAK.ORG"]' -s 'config.keyTab=["http.keytab"]' -s 'config.kerberosRealm=["KEYCLOAK.ORG"]' -s 'config.debug=["true"]' -s 'config.useKerberosForPasswordAuthentication=["true"]' ---- - +[discrete] ==== Removing a user storage provider instance . Use the storage provider instance's [command]`id` attribute to compose an endpoint URI, such as [filename]`components/ID`. @@ -1508,7 +1507,7 @@ For example: $ kcadm.sh delete components/3d9c572b-8f33-483f-98a6-8bb421667867 -r demorealm ---- - +[discrete] ==== Triggering synchronization of all users for a specific user storage provider . Use the storage provider's [command]`id` attribute to compose an endpoint URI, such as [filename]`user-storage/ID_OF_USER_STORAGE_INSTANCE/sync`. @@ -1521,7 +1520,7 @@ For example: $ kcadm.sh create user-storage/b7c63d02-b62a-4fc1-977c-947d6a09e1ea/sync?action=triggerFullSync ---- - +[discrete] ==== Triggering synchronization of changed users for a specific user storage provider . Use the storage provider's [command]`id` attribute to compose an endpoint URI, such as [filename]`user-storage/ID_OF_USER_STORAGE_INSTANCE/sync`. @@ -1534,7 +1533,7 @@ For example: $ kcadm.sh create user-storage/b7c63d02-b62a-4fc1-977c-947d6a09e1ea/sync?action=triggerChangedUsersSync ---- - +[discrete] ==== Test LDAP user storage connectivity . Run the [command]`get` command on the [filename]`testLDAPConnection` endpoint. @@ -1547,7 +1546,7 @@ For example: $ kcadm.sh get testLDAPConnection -q action=testConnection -q bindCredential=secret -q bindDn=uid=admin,ou=system -q connectionUrl=ldap://localhost:10389 -q useTruststoreSpi=ldapsOnly ---- - +[discrete] ==== Test LDAP user storage authentication . Run the [command]`get` command on the [filename]`testLDAPConnection` endpoint. @@ -1563,7 +1562,7 @@ $ kcadm.sh get testLDAPConnection -q action=testAuthentication -q bindCredential === Adding mappers - +[discrete] ==== Adding a hardcoded role LDAP mapper . Run the [command]`create` command on the [filename]`components` endpoint. @@ -1578,7 +1577,7 @@ For example: $ kcadm.sh create components -r demorealm -s name=hardcoded-ldap-role-mapper -s providerId=hardcoded-ldap-role-mapper -s providerType=org.keycloak.storage.ldap.mappers.LDAPStorageMapper -s parentId=b7c63d02-b62a-4fc1-977c-947d6a09e1ea -s 'config.role=["realm-management.create-client"]' ---- - +[discrete] ==== Adding an MS Active Directory mapper . Run the [command]`create` command on the [filename]`components` endpoint. @@ -1593,7 +1592,7 @@ For example: $ kcadm.sh create components -r demorealm -s name=msad-user-account-control-mapper -s providerId=msad-user-account-control-mapper -s providerType=org.keycloak.storage.ldap.mappers.LDAPStorageMapper -s parentId=b7c63d02-b62a-4fc1-977c-947d6a09e1ea ---- - +[discrete] ==== Adding an user attribute LDAP mapper . Run the [command]`create` command on the [filename]`components` endpoint. @@ -1608,7 +1607,7 @@ For example: $ kcadm.sh create components -r demorealm -s name=user-attribute-ldap-mapper -s providerId=user-attribute-ldap-mapper -s providerType=org.keycloak.storage.ldap.mappers.LDAPStorageMapper -s parentId=b7c63d02-b62a-4fc1-977c-947d6a09e1ea -s 'config."user.model.attribute"=["email"]' -s 'config."ldap.attribute"=["mail"]' -s 'config."read.only"=["false"]' -s 'config."always.read.value.from.ldap"=["false"]' -s 'config."is.mandatory.in.ldap"=["false"]' ---- - +[discrete] ==== Adding a group LDAP mapper . Run the [command]`create` command on the [filename]`components` endpoint. @@ -1623,7 +1622,7 @@ For example: $ kcadm.sh create components -r demorealm -s name=group-ldap-mapper -s providerId=group-ldap-mapper -s providerType=org.keycloak.storage.ldap.mappers.LDAPStorageMapper -s parentId=b7c63d02-b62a-4fc1-977c-947d6a09e1ea -s 'config."groups.dn"=[]' -s 'config."group.name.ldap.attribute"=["cn"]' -s 'config."group.object.classes"=["groupOfNames"]' -s 'config."preserve.group.inheritance"=["true"]' -s 'config."membership.ldap.attribute"=["member"]' -s 'config."membership.attribute.type"=["DN"]' -s 'config."groups.ldap.filter"=[]' -s 'config.mode=["LDAP_ONLY"]' -s 'config."user.roles.retrieve.strategy"=["LOAD_GROUPS_BY_MEMBER_ATTRIBUTE"]' -s 'config."mapped.group.attributes"=["admins-group"]' -s 'config."drop.non.existing.groups.during.sync"=["false"]' -s 'config.roles=["admins"]' -s 'config.groups=["admins-group"]' -s 'config.group=[]' -s 'config.preserve=["true"]' -s 'config.membership=["member"]' ---- - +[discrete] ==== Adding a full name LDAP mapper . Run the [command]`create` command on the [filename]`components` endpoint. @@ -1641,7 +1640,7 @@ $ kcadm.sh create components -r demorealm -s name=full-name-ldap-mapper -s provi === Authentication operations - +[discrete] ==== Setting a password policy . Set the realm's [command]`passwordPolicy` attribute to an enumeration expression that includes the specific policy provider ID and optional configuration. @@ -1658,7 +1657,7 @@ $ kcadm.sh create components -r demorealm -s name=full-name-ldap-mapper -s provi ---- $ kcadm.sh update realms/demorealm -s 'passwordPolicy="hashIterations and specialChars and upperCase and digits and notUsername and length"' ---- -. If you want want to use values different from defaults, pass the configuration in brackets. +. If you want to use values different from defaults, pass the configuration in brackets. . Use the following example to set a password policy to: * 25,000 hash iterations @@ -1675,7 +1674,7 @@ $ kcadm.sh update realms/demorealm -s 'passwordPolicy="hashIterations and specia $ kcadm.sh update realms/demorealm -s 'passwordPolicy="hashIterations(25000) and specialChars(2) and upperCase(2) and lowerCase(2) and digits(2) and length(9) and notUsername and passwordHistory(4)"' ---- - +[discrete] ==== Getting the current password policy Get the current realm configuration and filter everything but the [command]`passwordPolicy` attribute. @@ -1686,7 +1685,7 @@ Use the following example to display [command]`passwordPolicy` for [filename]`de $ kcadm.sh get realms/demorealm --fields passwordPolicy ---- - +[discrete] ==== Listing authentication flows Run the [command]`get` command on the [filename]`authentication/flows` endpoint.