This document summarise prometheus lifecycle - what it does, how it works and how to query it and modify its behaviour. Some of this information is included elsewhere, but this is an attempt to collect all information relating to prometheus lifecycle in one place.

All historical information on the design of prometheus's lifecycle code can be found in PrometheusLifecycleHistory

Roles and Entitlements

Roles and entitlements (also known as capabilities) are central to prometheus. There are two distinct types:

  • upstream roles - these are allocated directly from the database and provide, among others, the roles which entitle a user to a DICE account.

  • additional roles/entitlements - these are manually allocated to a prometheus entity object, using the modify-user command.

There are a number of "special" entitlements which are used by prometheus (e.g. to create the various parts of an account). The most important one of these, for lifecycle, is "prometheus/localIdentity". This is what entitles a user to a kerberos principal and so is the base entitlement on which all DICE accounts are built. When a user loses this entitlement (typically by disappearing from prometheus's database feed), this signifies that their right to an account has ended.

Although we tend to think in terms of the roles that a user possesses, for prometheus these are only really relevant as containers for entitlements.

Types of entitlements

There are four different types of entitlements:

  • Fixed entitlements - once possessed by a user, these remain until they are explicitly removed. These are indicated by a '*' prefix, e.g. the entitlement granting a user an AFS home directory would be fixed and would be manually removed once the homedir had been archived.

  • No-grace entitlements - these are not protected by a grace period, so are removed as soon as the user loses them. These are indicated by a '!' prefix. These are likely to be entitlements which grant access to something which should not persist beyond the user's end date (e.g. write access to a critical database).

  • Preserved entitlements - these will be protected for the duration of the user's grace period. It is envisaged that most entitlements will be of this type.

  • Negated entitlements - these are used to remove a specific entitlement from a user's object. These are indicated by a '-' prefix. These are likely to be used to revoke access to something, or where a role gives users access to things that they don't need. In practice, these are rarely used.

To summarise the syntax:

preserved/entitlement
*fixed/entitlement
!nograce/entitlement
-negated/entitlement

Where the same entitlement is specified multiple times, with different modifier prefixes, the following precedence is enforced:

negated (-) > nograce (!) > fixed (*) > preserved

In addition to the above, we have the concept of complex entitlements - these are used to provide a value for an entitlement and take the form 'entitlement:X', where X is the value for the entitlement. Where the entitlement is provided more than once and the values are numeric, the largest value will be used. For non-numeric values, the last one processed will be used. Complex entitlements are currently only used for specifying the grace period (see 'prometheus/grace' below).

What happens when an account expires

When an account expires, it disappears from prometheus's database feed (or the upstream roles it has allocated do not entitle it to a DICE account). In the case of disappearance, prometheus explicitly removes any upstream roles from the user's object. It also removes any additional roles and entitlements.

What Lifecycle does

Lifecycle was designed to solve the problem of a user losing all their entitlements as soon as they lose their right to an account, specifically it's designed to implement a "grace", or "expiry" period, as defined by our policy:

http://computing.help.inf.ed.ac.uk/account-closure

What this means is that, once a user loses their right to an account, all the entitlements they possessed prior to this are maintained for the duration of their grace period. Note that no-grace entitlements are configured to expire immediately and so are not maintained.

The grace period for accounts is defined using a complex entitlement of the form:

*prometheus/grace:X

... where X is a number of days.

How lifecycle tracks roles and entitlements

A prometheus entity has the following roles/entitlements attributes:

  • upstreamroles - these are the roles allocated by the database

  • additionalroles - any manually added roles

  • additionalentitlements - any manually added entitlements

  • upstreamentitlements - this is the expanded list of all entitlements possessed by the user - this is what leads a user to be in groups, netgroups and LDAP capabilities maps

Note that all of these attributes are stored at the top level of the user's entity object and their LDAP attribute names are formed by upper-casing the first letter and prefixing with 'prometheus', e.g. 'upstreamroles' is stored in LDAP as 'prometheusUpstreamroles'.

The complete list of entitlements a user possesses at any time is maintained in the 'upstreamentitlements' attribute. This list is generated, by the RoleExpander conduit, from the user's 'upstreamroles', 'additionalroles', 'additionalentitlements' (and, see below, 'protectedentitlements') attributes. For lifecycle to keep track of entitlements to be preserved, the following attributes are used:

  • protectedentitlements - this keeps track of all fixed and preserved entitlements (and, in the latter case, the date on which they should expire)

  • accountend - the date on which the account expired

  • gracend - the date on which the grace period expires/expired (accountend+grace)

The protectedentitlements attribute maintains a list of (a) which entitlements are to be protected and, optionally (b) their expiry date. Fixed entitlements are stored as the name of the entitlement, preserved entitlements are stored as 'entitlement:active' or with a date as 'entitlement:yyyy-mm-dd'.

To see how this works, the following shows a very simplified example of an account's lifecycle:

For an active account, selected attributes from the user's entity object could look like:

upstreamentitlements: prometheus/grace:30
upstreamentitlements: prometheus/localIdentity
upstreamentitlements: preserved/ent1
upstreamentitlements: preserved/ent2
upstreamentitlements: nograce/ent
protectedentitlements: prometheus/grace
protectedentitlements: prometheus/localIdentity
protectedentitlements: preserved/ent1:active
protectedentitlements: preserved/ent2:active

This shows two fixed entitlements (prometheus/localIdentity and prometheus/grace, which has a value of 30), two preserved entitlements and one nograce entitlement (note that this has no corresponding entry in protectedentitlements).

Once the account has expired, they would look something like this

accountend: 2015-04-01
graceend: 2015-05-01
upstreamentitlements: prometheus/grace:30
upstreamentitlements: prometheus/localIdentity
upstreamentitlements: preserved/ent1
upstreamentitlements: preserved/ent2
protectedentitlements: prometheus/grace
protectedentitlements: prometheus/localIdentity
protectedentitlements: preserved/ent1:2015-05-01
protectedentitlements: preserved/ent2:2015-05-01

This tells prometheus that the two preserved entitlements should be removed on 2015-05-01.

Note that the nograce entitlement has disappeared.

In normal use, all preserved entitlements which have expired would have the same expiry date (which would be the same as 'graceend').

The 'accountend' and 'graceend' attributes are used to keep track of the overall status of the account's grace period.

Once the account has passed the end of its grace period, it would look something like:

accountend: 2015-04-01
graceend: 2015-05-01
upstreamentitlements: prometheus/grace:30
upstreamentitlements: prometheus/localIdentity
protectedentitlements: prometheus/grace
protectedentitlements: prometheus/localIdentity

The only entitlements it still possesses are fixed ones.

Actions taken by lifecycle

The RoleExpander conduit is responsible for maintaining the list of entitlements for an entity and the dates on which the account and grace period expire. There is a second conduit, LifecycleProcessing, which acts on this information. It runs once daily (at 10:45) and does the following:

  • When an account has expired and entered its grace period, this conduit will automatically send an email to the address associated with the account to indicate this. It also sets an 'expiryMailSent' flag on the user's identity object to show this has happened. There is a configurable delay period (--emaildelay (default value: 7 days)) to wait a number of days after account expiry before sending the email. The email looks like this.

  • When an account has passed the end of its grace period, this conduit will set the 'disableAccount' flag on the user's identity object. This will lead to the account being disabled on the next run of the SyncToKDC conduit. This also has a configurable delay period (--disabledelay (default value: 0 days)).

  • Active accounts have the 'expiryMailSent' flag removed and have any date-preserved entitlements explicitly set to expire 'today'. These will be any entitlements which are preserved from a previous grace period.

  • Accounts which have not authenticated in X (a configurable integer) number of days will be suspended (disabled) and the user emailed with a notification. This is explained in detail below.

Notifications sent by lifecycle

Prometheus will send email notifications from conduits for certain events, as well as logging them to /var/lcfg/log/prometheus.conduits on the prometheus master server. Lifecycle related ones are:

Prometheus::Conduits::RoleExpander

<username>: account expired

This user has lost their entitlement to an account.

<username>: clearing additional roles: <list-of-roles>

The named additional roles have been removed from the user.

<username>:: clearing additional entitlements: <list-of-entitlements>

As above, but for entitlements

Prometheus::Conduits::LifecycleProcessing::Conduit

<username>: expiry email sent

This user has been sent the email to indicate account expiry

<username>: account disabled

This user has had the disableAccount flag set

<username>: expiryMailSent flag removed

This user has had the expiryMailSent flag removed, due to now having an entitlement to an account

<username>: date preserved entitlements set to expire today

This user has had any date preserved protected entitlements set to expire today - this means that the user now has the entitlement to an account, but possessed protected entitlements from a previous grace period. These have been set to expire today.

<username>: grace period set to expire today

This user has had the grace period for their account and all entitlements set to today. This happens when an account which has never been activated has expired.

<username>: authentication inactivity

This user has not successfully authenticated for more than X days and so has triggered the inactivity suspension.

<username>: inactivity email sent

This user has been sent the email to indicate inactivity suspension.

<username>: inactivitySuspension flag added

This user has had the inactivitySuspension flag set.

<username>: inactivitySuspension flag removed

This user has had the inactivitySuspension flag removed, due to the account having been re-enabled.

<username>: inactivityMailSent flag removed

This user has had the inactivityMailSent flag removed, due to the account having been re-enabled and the user successfully authenticating.

Using 'prometheus-lifecycle'

prometheus-lifecycle --help documents the available options.

How to find out the status of an account...

$ prometheus-lifecycle --user <username>

There are four possible statuses:

  • active: account is active
  • grace: account is in grace period
  • post-grace: account has grace period which has expired
  • defunct: account has no account-granting entitlement at all

How to find out which accounts are in their grace period...

$ prometheus-lifecycle --summary

... or use --showexpired to also display accounts which have gone past their grace period:

$ prometheus-lifecycle --summary --showexpired

The --eligible-for-deletion flag reports on all accounts which have gone past their suspension period and hence can be deleted.

$ prometheus-lifecycle --eligible-for-deletion

Use --dates to display account-end, grace-end and eligible-for-deletion dates, format is of the form:

name: status account-end grace-end eligible-for-deletion

Use --flags to display any flags set on the user's identity object. Flags are comma-separated and displayed (for brevity) without the conduit uuid, e.g.

[bolt]toby: prometheus-lifecycle --user t040011 --flags
t040011: active disableAccount,inactivityMailSent,inactivitySuspension
[bolt]toby:

See PrometheusDesignDetail#Flags for more information on flags.

The --protected argument will display all entitlements for a user that are currently being protected (i.e. will disappear once the grace period has expired). Note that each protected entitlement has an individual expiry date. This will usually be the same as the grace end date, but can be set to something different. Note that prometheus-lifecycle will not display end dates for individual protected entitlements, but these can be viewed by looking at the user's prometheus entity record, e.g.

ldapsearch -h prometheus:1234 -b ou=Entities,o=Prometheus,dc=inf,dc=ed,dc=ac,dc=uk prometheusUsername=<username> prometheusProtectedentitlements

How to change expiry date for a user...

$ prometheus-lifecycle --setexpiry '2099-11-01' --user <username>

How to change expiry date for one entitlement for a user...

$ prometheus-lifecycle --setexpiry 'an/entitlement:2099-11-01' --user <username>

The word 'today' can be used instead of a yyyy-mm-dd string, e.g.

$ prometheus-lifecycle --setexpiry 'today' --user <username>

All fixed entitlements can be removed from a user with --removeallfixedentitlements - this would typically be used immediately prior to an account's deletion.

$ prometheus-lifecycle --removeallfixedentitlements --user <username>

Inactivity suspension

As of February 2018, the LifecycleProcessing conduit is also responsible for implementing our inactivity suspension policy.

Authentication data (last successful authentication, last failed authentication and last password change dates) are synchronised from the master KDC twice daily (09:15am and 10:30am - the second run is to ensure the statistics are as up to date as possible prior to the running of the Lifecycle Processing conduit).

An account will not be considered for inactivity suspension if the password has been changed in the last 45 days. This covers new accounts which have had their initial password set through either (1) support printing out a password letter, or (2) the user setting it using the password portal.

An account will be suspended if it has not successfully authenticated for 180 days. When an account is suspended for inactivity, the user is emailed (the email looks like this) and the following flags will be set on the user's identity object in Prometheus:

disableAccount
inactivitySuspension
inactivityMailSent

An account which has been suspended for inactivity can therefore be identified using prometheus-get-info or prometheus-lifecycle --user <username> --flags

The disableAccount flag is the mechanism for disabling an account. See here for more detail.

Re-enabling an account suspended for inactivity is done in the normal way:

theogony enable-account --trigger <username>

(--trigger makes it happen almost immediately, see PrometheusEventQueue)

The user will then have at least 24 hours in which to authenticate before their account is disabled again. Full explanation follows...

An account that has been re-enabled after inactivity suspension involves a two-stage process for the next runs of the LifecycleProcessing conduit:

  1. On the first run following an account being re-enabled, the inactivitySuspension flag is removed.
  2. On the second run, the account will be checked for inactivity and the inactivityMailSent flag removed if the account is now active. If the account is still inactive, the disableAccount and inactivitySuspension flags will be added again.

This two-stage process is necessary because there is a period of time (between an inactive account being re-enabled and the user authenticating) where this conduit could suspend the account again. This process means that there is at least the period of time between successive runs of this conduit (i.e. usually one day) for a re-enabled user to successfully authenticate.

Preventing lifecycle actions for a user

The 'noLifecycleProcessing' flag can be used to prevent any lifecycle actions being taken on a given user. See PrometheusDesignDetail#Flags. This can be added with prometheus-lifecycle --disablelifecycle and removed with prometheus-lifecycle --enablelifecycle.


-- TobyBlake - 06 Mar 2019

Topic revision: r29 - 05 Jul 2019 - 12:08:30 - TobyBlake
 
This site is powered by the TWiki collaboration platformCopyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback
This Wiki uses Cookies