Add invalidating registration tokens (#3595)

guides/common/assembly_invalidating-registration-tokens.adoc

@@ -0,0 +1,7 @@
+include::modules/con_invalidating-registration-tokens.adoc[]
+
+include::modules/proc_invalidating-your-own-jwts.adoc[leveloffset=+1]
+
+include::modules/proc_invalidating-jwts-of-other-users.adoc[leveloffset=+1]
+
+include::modules/proc_invalidating-jwts-of-all-users.adoc[leveloffset=+1]

guides/common/assembly_registering-hosts.adoc

@@ -19,6 +19,8 @@ include::modules/proc_customizing-host-registration-by-using-snippets.adoc[level
 
 include::modules/proc_customizing-the-registration-templates.adoc[leveloffset=+2]
 
+include::assembly_invalidating-registration-tokens.adoc[leveloffset=+2]
+
 ifdef::satellite,orcharhino[]
 // Bootstrap script
 include::modules/proc_registering-hosts-by-using-the-bootstrap-script.adoc[leveloffset=+1]

guides/common/modules/con_invalidating-registration-tokens.adoc

@@ -0,0 +1,12 @@
+[id="invalidating-registration-tokens"]
+= Invalidating registration tokens
+
+When you generate a registration command in global host registration, {Project} also generates a unique JSON Web Token (JWT) that is used to authorize the registration call from a host to {ProjectServer}.
+This JWT is bound to the user that generated the registration command.
+
+Users can configure a custom validity duration for the JWT.
+If the validity duration is too long or if the JWT has been compromised, the JWT poses a security concern.
+To mitigate this concern, the {Project} administrator or users with adequate permissions can invalidate existing JWTs.
+
+You can also temporarily disable registration tokens by disabling a user.
+When you reenable the user, the user will be able to continue using their registration tokens.

guides/common/modules/proc_invalidating-jwts-of-all-users.adoc

@@ -0,0 +1,15 @@
+[id="invalidating-jwts-of-all-users"]
+= Invalidating JWTs of all users
+
+You can invalidate all registration JSON Web Tokens of all users at once in the {ProjectWebUI}.
+
+.Prerequisites
+* Your {Project} user has a role that grants the `view_users` and `edit_users` permissions.
+
+.Procedure
+. In the {ProjectWebUI}, navigate to *Administer* > *Users*.
+. Click *Invalidate JWTs for all users*.
+. In the confirmation window, click *Confirm*.
+
+.Verification
+* The {ProjectWebUI} displays the following message: `Successfully invalidated registration tokens for all users.`

guides/common/modules/proc_invalidating-jwts-of-other-users.adoc

@@ -0,0 +1,44 @@
+[id="invalidating-jwts-of-other-users"]
+= Invalidating JWTs of other users
+
+You can invalidate all registration JSON Web Tokens of one or more users.
+
+To use the CLI instead of the {ProjectWebUI}, see the xref:cli-invalidating-jwts-of-other-users[].
+To use the API, see the xref:api-invalidating-jwts-of-other-users[].
+
+.Prerequisites
+* Your {Project} user has a role that grants the `edit_users` permissions.
+For {ProjectWebUI}, you also require the `view_users` permission.
+
+.Procedure
+. In the {ProjectWebUI}, navigate to *Administer* > *Users*.
+. In the row of the user whose registration tokens you want to invalidate, from the actions menu, select *Invalidate JWTs*.
+. In the confirmation window, click *Confirm*.
+
+.Verification
+* The {ProjectWebUI} displays the following message: `Successfully invalidated registration tokens for _the user_.`
+
+[id="cli-invalidating-jwts-of-other-users"]
+.CLI procedure
+* Invalidate all registration tokens of a single user by running Hammer:
++
+[options="nowrap" subs="+quotes,attributes,verbatim"]
+----
+$ hammer user registration-token invalidate --user-id _User_ID_
+----
+* Invalidate all registration tokens of multiple users by running Hammer:
++
+[options="nowrap" subs="+quotes,attributes,verbatim"]
+----
+$ hammer user registration-token invalidate-multiple --search "_My_Search_Query_"
+----
+
+[id="api-invalidating-jwts-of-other-users"]
+.API procedure
+* Invalidate all registration tokens of a single user by using the `DELETE /api/users/_:user_id_/registration_tokens` resource.
+* Invalidate all registration tokens of multiple users by using the `DELETE /api/registration_tokens?search=_url-encoded-search-query_` resource.
+
+For more information, see the full API reference at `https://_{foreman-example-com}_/apidoc/v2.html`.
+
+.Additional resources
+* {AdministeringDocURL}Building_Search_Queries_admin[Building search queries] in _{AdministeringDocTitle}_

guides/common/modules/proc_invalidating-your-own-jwts.adoc

@@ -0,0 +1,31 @@
+[id="invalidating-your-own-jwts"]
+= Invalidating your own JWTs
+
+You can invalidate all registration JSON Web Tokens of the current user.
+
+To use the CLI instead of the {ProjectWebUI}, see the xref:cli-invalidating-your-own-jwts[].
+To use the API, see the xref:api-invalidating-your-own-jwts[].
+
+.Procedure
+. In the {ProjectWebUI}, click the user menu in the top bar and select *My Account*.
+. Select the *Registration Tokens* tab.
+. Click *Invalidate JWTs*.
+. In the confirmation window, click *Confirm*.
+
+.Verification
+* The {ProjectWebUI} displays the following message: `Successfully invalidated registration tokens.`
+
+[id="cli-invalidating-your-own-jwts"]
+.CLI procedure
+* Invalidate all your registration tokens by running Hammer:
++
+[options="nowrap" subs="+quotes,attributes,verbatim"]
+----
+$ hammer user registration-token invalidate --user-id _My_User_ID_
+----
+
+[id="api-invalidating-your-own-jwts"]
+.API procedure
+* Use the `DELETE /api/users/_:user_id_/registration_tokens` resource.
+
+For more information, see the full API reference at `https://_{foreman-example-com}_/apidoc/v2.html`.