reviewboard.accounts.service_accounts¶

Service account creation, management, and registration.

New in version 8.1.

class ServiceAccount(*, api_token_expiration_secs: Unsettable[int] = UnsetSymbol.UNSET, api_token_policy: Unsettable[JSONDictImmutable] = UnsetSymbol.UNSET, api_token_version: Unsettable[int] = UnsetSymbol.UNSET, avatar_urls: Unsettable[Mapping[str, str]] = UnsetSymbol.UNSET, claim_username: bool = False, email: Unsettable[str] = UnsetSymbol.UNSET, name: Unsettable[str] = UnsetSymbol.UNSET, preferred_username: Unsettable[str | None] = UnsetSymbol.UNSET, profile_version: Unsettable[int] = UnsetSymbol.UNSET, service_account_id: Unsettable[str] = UnsetSymbol.UNSET)[source]¶

Bases: object

A service account used for automation and integration purposes.

Service accounts are special entities that are allowed to perform operations using the Review Board API, but cannot otherwise log in, and do not take a seat on the license.

They’re intended for extensions and integrations that need to associate data with a managed user account or pass an API token to another service.

Service accounts are created by either providing the necessary attributes in a subclass or when constructing an instance. In either case, the instance needs to be registered in service_account_registry prior to use.

New in version 8.1.

__init__(*, api_token_expiration_secs: Unsettable[int] = UnsetSymbol.UNSET, api_token_policy: Unsettable[JSONDictImmutable] = UnsetSymbol.UNSET, api_token_version: Unsettable[int] = UnsetSymbol.UNSET, avatar_urls: Unsettable[Mapping[str, str]] = UnsetSymbol.UNSET, claim_username: bool = False, email: Unsettable[str] = UnsetSymbol.UNSET, name: Unsettable[str] = UnsetSymbol.UNSET, preferred_username: Unsettable[str | None] = UnsetSymbol.UNSET, profile_version: Unsettable[int] = UnsetSymbol.UNSET, service_account_id: Unsettable[str] = UnsetSymbol.UNSET) → None[source]¶

Initialize the service account.

This can override any default attributes on the class, allowing extensions to either maintain service accounts fully or partly as subclasses or through instantiation.

To claim a specific username (typically when one was already created and stored in the extension’s settings), pass claim_username=True and preferred_username=username.

Parameters:

api_token_expiration_secs (int, optional) –
The expiration time for any created API tokens, in seconds.

See api_token_expiration.
api_token_policy (dict, optional) –
The token policy document to use for any created API tokens.

See api_token_policy.
api_token_version (dict, optional) –
The version of the API token state.

See api_token_version.
avatar_urls (dict, optional) –
Explicit avatars to use for managed accounts.

See avatar_urls.
claim_username (bool, optional) –
Whether to claim the preferred username as the managed service account user, if it already exists in the database.

If set to True, it’s best to pass preferred_username.
email (str, optional) –
The e-mail address for the service account.

See email.
name (str, optional) –
The name of this service account.

See name.
preferred_username (str, optional) –
The preferred username for managed users.

This should be provided if passing claim_username=True.

See preferred_username`.
profile_version (int, optional) –
The version of the profile state.

See profile_version.
service_account_id (str, optional) –
The unique ID of the service account.

See service_account_id.

Raises:

ValueError – A required argument or attribute was not provided.

service_account_id: str = ''¶

The unique ID of the service account.

This must be in slug format.

This ID will be used as the username for new accounts if preferred_username is not provided on the class or during construction.

name: str = 'Service Account'¶

The name of this service account.

This will be used for any managed users.

avatar_urls: Mapping[str, str] | None = None¶

Explicit avatars to use for managed accounts.

This is a mapping of resolution indicators (e.g., 1x, 2x, 3x) to image URLs (absolute or relative).

If not set, avatars will not be configured.

email: str = ''¶

The e-mail address for the service account.

This will be used for any managed users. If not provided, the default e-mail address for the server will be used.

preferred_username: str = ''¶

The preferred username for managed users.

This will be used instead of service_account_id as the username used when attempting to look up or create a user account.

profile_version: int = 1¶

The version of the profile state.

Service accounts should explicitly increment this value whenever they need to ensure new state (e-mail address, name, or avatars) is saved to the managed user.

api_token_expiration_secs: int | None = 2592000¶

The expiration time for any created API tokens, in seconds.

When creating a new API token for access, this will be used to set the expiration for the token.

This defaults to 30 days.

api_token_policy: JSONDictImmutable | None = None¶

The token policy document to use for any created API tokens.

It’s recommended that a token policy document is set that covers the minimum set of permissions needed for the service account to perform its responsibilities.

To ensure older tokens with an outdated policy are not used, increment api_token_version when updating the policy.

api_token_version: int = 1¶

The version of the API token state.

Service accounts should explicitly increment this value whenever they need to ensure a new expiration or token policy is used the next time a token is accessed.

get_user(*, _claim_map: dict[str, reviewboard.accounts.service_accounts.ServiceAccount] | None = None, _max_attempts: int = 100) → User[source]¶

Return a user managed by this service account.

If the user was already fetched from the database, it will be returned as-is. Otherwise, a new user will be looked up or created. This works as follows:

If the service account is registered as claiming a specific username that already exists (such as one stored from a prior creation), that user will be returned.
If one is not claimed, this will attempt to look up an existing user that’s recorded as being associated with service_account_id.
If the user was not found, one will be created.

The username defined by preferred_username (or, if not set, service_account_id) will be used for lookup or creation. If a user is not being claimed by this service account, and another user already has this username, this will add a number to the username (starting with 1, then 2, etc.) until it finds a user that it can fetch or create.

Parameters:

_claim_map (dict, optional) –
A map for storing a claim for a username.

This is meant only for internal use and is not considered part of the stable API.
_max_attempts (int, optional) –
The default maximum number of attempts for claiming a user.

This is meant only for internal use and is not considered part of the stable API.

Returns:

The resulting user.

Return type:

django.contrib.auth.models.User

Raises:

reviewboard.accounts.errors.ServiceAccountUserError – A user could not be fetched, created, or claimed, and the maximum number of attempts have run out.

get_api_token(*, local_site: LocalSite | None, min_validity_secs: int = 7200) → WebAPIToken[source]¶

Return an API token for the service account.

If a matching token already exists, and will remain valid for a minimum amount of time (2 hours by default, if the configured expiration is more than that), then the token will be returned.

If a valid token does not already exist, a new one will be created with policy document and expiration time provided on the service account.

The API token will be keyed off from the api_token_version number.

Note that this does not check if the expiration time or policy document has been modified to be different from those set on this service account. What’s in the database will be returned as-is.

Parameters:

local_site (reviewboard.site.models.LocalSite, optional) – The Local Site the token must be tied to.
min_validity_secs (int, optional) –
The minimum number of seconds left in any existing token considered for a result.

This defaults to 2 hours.

Returns:

The resulting API token.

Return type:

reviewboard.webapi.models.WebAPIToken

class ServiceAccountRegistry(*args, **kwargs)[source]¶

Bases: Registry[ServiceAccount]

A registry tracking service accounts.

This tracks all service accounts registered via Review Board or extensions. Registered service accounts can only log in via API tokens, and do not take a seat on the license.

New in version 8.1.

lookup_attrs: Sequence[str] = ('service_account_id',)[source]¶

A list of attributes that items can be looked up by.

Type:: list of str

default_errors: RegistryErrorsDict = {'already_registered': 'Could not register service account %(item)s. It is already registered.', 'attribute_registered': 'Could not register service account %(item)s: Another service account (%(duplicate)s) is already registered with the same ID.', 'invalid_attribute': '"%(attr_name)s" is not a registered lookup attribute.', 'load_entry_point': 'Could not load entry point %(entry_point)s: %(error)s.', 'missing_attribute': 'Could not register %(item)s: it does not have a "%(attr_name)s" attribute.', 'not_registered': 'No service account was found with the ID "%(attr_value)s".', 'unregister': 'Could not unregister service account %(item)s: This service account was not yet registered.'}[source]¶

The default error formatting strings.

If subclasses need to provide additional errors that can be overridden, they should copy DEFAULT_ERRORS and set their copy on the subclass as this attribute.

Type:: dict

__init__(*args, **kwargs) → None[source]¶

Initialize the registry.

Parameters:

*args (tuple) – Positional arguments to pass to the parent.
**kwargs (tuple) – Keyword arguments to pass to the parent.

get_for_service_account_id(service_account_id: str) → reviewboard.accounts.service_accounts.ServiceAccount | None[source]¶

Return a service account with the given ID.

Parameters:: service_account_id (str) – The ID of the service account.
Returns:: The registered service account, or None if not found.
Return type:: ServiceAccount

get_for_username(username: str) → reviewboard.accounts.service_accounts.ServiceAccount | None[source]¶

Return a service account for a given username.

Parameters:: username (str) – The username to check for.
Returns:: The registered service account, or None if not found.
Return type:: ServiceAccount

on_item_registered(item: ServiceAccount) → None[source]¶

Handle post-registration of a service account.

This will fetch or create the managed user and add it to the username map.

Parameters:: item (ServiceAccount) – The service account that was registered.

on_item_unregistered(item: ServiceAccount) → None[source]¶

Handle post-unregistration of a service account.

This will remove its claim from the username map.

Parameters:: item (ServiceAccount) – The service account that was unregistered.

service_account_registry = <reviewboard.accounts.service_accounts.ServiceAccountRegistry object>[source]¶: The main service account registry for Review Board.

New in version 8.1.