Reinstate a suspended person or agent

Where this runbook applies

This runbook applies to any installation with the Identity Service enabled, which means both identity.enabled and identity.clientIntegration.enabled are true in the istari-platform chart values. The Helm values that enable the Identity Service set both.

Administrators normally reactivate a suspended person or agent in the web app. When nobody who could do that is available, an operator can reactivate them from the command line with reinstate-principal.

For example, a Platform Administrator suspends the only tenant they belong to, which suspends them too, and the other Platform Administrators are unavailable. Reactivating the tenant afterwards does not help, because reactivating a tenant reactivates none of its people.

The Identity Service refuses to suspend a tenant or a person, or to revoke a role, when that would leave no active human Platform Administrator. If none of the remaining Platform Administrators can act anyway, for example because they are unavailable or have left, first make someone who is not suspended a Platform Administrator, as in Create the first Platform Administrator. If the first step below calls for granting a membership, the new Platform Administrator can grant it, or reactivate people in the web app.

Prerequisites

• kubectl access to the cluster.
• The Identity Service image tag you deployed, 2.0.0 or later. Earlier images do not include reinstate-principal.
• The istari-identity secret and the docker-pull-secret image pull secret, in the namespace where the Identity Service runs. The command below uses them; if yours have other names, change them in the command.

Steps

1. Make sure the person or agent holds a membership in an active tenant.

   • A person suspended directly, rather than through their tenant, keeps their memberships.
   • Under the default revocation setting (TENANT_DEACTIVATION_REVOCATION_CASCADE), suspending a tenant revokes its members' memberships, so expect to grant one in an active tenant.

   A Tenant Administrator of that tenant or a Platform Administrator grants a membership in the web app or through POST /api/v2/tenants/{id}/members. The image's grant-tenant-role command cannot grant it, because it refuses a suspended person. Without a membership, reinstate-principal refuses with holds no granted membership; grant one first via POST /api/v2/tenants/{id}/members.

2. Run reinstate-principal as a one-off pod in the namespace where the Identity Service runs. Add -n <namespace> if that is not your current namespace. In the command, replace:

   • <tag> with the Identity Service image tag;
   • -email and <email> with one flag from the table below and its value.

   kubectl run reinstate-principal --rm -i --restart=Never \
     --image=istaridigital.jfrog.io/customer-docker/identity-service:<tag> \
     --overrides='{
       "spec":{
         "imagePullSecrets":[{"name":"docker-pull-secret"}],
         "containers":[{
           "name":"reinstate-principal",
           "image":"istaridigital.jfrog.io/customer-docker/identity-service:<tag>",
           "command":["/reinstate-principal"],
           "args":["-database-url-env","ISTARI_DIGITAL_IDENTITY_SERVICE_DATABASE_URL",
                   "-email","<email>"],
           "envFrom":[{"secretRef":{"name":"istari-identity"}}]
         }]}
     }'

   Flag	Identifies
   -email	A person, by email address. The command prints the identity it resolved; use -principal if it is not the right one.
   -principal	A person, by identity principal UUID. The -email form prints it.
   -agent	An agent, by client ID: the clientId field of its credentials file.

   The pod loads the istari-identity secret. It supplies the database connection string for -database-url-env, and any AUDIT_* settings there decide where the command's audit events go. The command prints one of:

   • reinstated human <id> or reinstated agent <client id>: the person or agent is back in service;
   • already in service: there was nothing to do.

   Running the command again changes nothing that is already in place.

3. Restore roles. Reinstating does not restore roles the suspension revoked. If it revoked any, an administrator grants them again in the web app:

   • Tenant Administrator, in the Platform Admin Console or the tenant's Admin Panel;
   • Platform Administrator, in the Platform Admin Console. If no Platform Administrator is left, restore the role as in Create the first Platform Administrator.

4. Verify. The person signs in, or the agent's next start registers it, and the web app shows them as active.