Governance in your tenant

The access catalog

A catalog item is a group, a management role or an application role from the authorization engine. Each item has a description people see before they ask, an owner and a deputy owner, a sensitivity (low, medium or high), the approvals it needs in order (the person's manager, the item's owner, administrators, or none), the longest time it may be held, and whether a reason is required. An item can be requestable, offered just in time to eligible people, or both. Adding an item needs the same permissions as giving the access directly: a group needs tenant.groups.update, a management role needs every permission the role grants and tenant.users.management_roles.assign, and an application role needs tenant.authz.update. Platform roles can never be offered. A management role cannot use the manager approval step, because managers come from the directory and a provisioning feed can set them; offered for request, it needs at least one approval, whether it is standing or just in time, and an administrator deciding or reassigning its request must hold what it grants. A group that gives or scopes management roles is never offered in the catalog. In the BTL organization, BTL Admins decide every request and review item on its Governance page.

Requests and approvals

On /account/access a person picks an item, gives a reason and chooses a duration up to the item's longest. The request is checked when it is submitted, routed to its first approver, and each approval routes it to the next. After the last approval the tenant gives the access with its end date, reads it back, and marks the request fulfilled and confirmed. A denial ends the request. People see where their requests stand and can cancel one that is still waiting. Administrators with tenant.governance.requests.manage see every request on the Requests tab, can send a waiting step to someone else, and can cancel a request. On the end date the access is removed by itself and the end is recorded against the request.

Who decides

A step is routed when it becomes current, and the requester and the person receiving the access are never chosen. Each step needs a different person: someone who decided an earlier step of the request is passed over, and cannot decide a later one as an administrator.

A decision is accepted only from the person the step is routed to, or from an administrator for an administrators step, and the check runs again when the decision is made. Holding a management role never lets someone decide a step routed to another person. A person who is locked or deleted has their waiting steps moved to administrators. The tenant can require an authentication level for management changes; the same level then applies to approvals and review decisions.

A management role is decided only by people who hold what it gives. It never has a manager step, an owner, deputy or delegate without the role sends the step to administrators, and an administrator deciding it must hold the role too. Waiting requests follow the item: when it is no longer offered that way or a person's eligibility ends, the request closes, and when its owner, deputy, delegation or the person's manager changes, the step is routed again before anyone decides it.

Delegating approvals

On /account/approvals an approver can hand their decisions to someone else for up to 90 days, and end the delegation early. When the delegate is the requester or the person receiving the access, the step goes past them to the delegating approver's manager instead. Administrators with tenant.governance.delegations.manage can set anyone's delegation through the API. For a management role, only a delegation the approver set themselves counts, and only to a delegate who holds the role.

Just in time and emergency access

For an item offered just in time, administrators choose who is eligible, optionally until a date, on the item's Eligible people list. An eligible person activates it on /account/access with a reason and a duration, after any approvals the item needs. Just-in-time access always ends, by default within a day. An item can also allow emergency activation: an eligible person takes the access at once, with a required reason and no approval. Each emergency use is recorded with its own Audit operation and opens an item in the tenant's standing Emergency access review, for the owner to decide within the item's review window. While a management role is held this way, every Audit record of the actions it allowed carries the request as its correlation ID. When the window closes, the role is removed and the person's tenant sign-ins end.

Time-bound grants

On the Grants tab, administrators with tenant.governance.grants.manage give a group membership, management role or application role directly, with a reason, an optional owner and an end date. It needs the same authority as giving the access directly. The access ends by itself at that date, or earlier with End now. Access removed another way, for example from the Groups page or by a provisioning client, ends its grant too, so nothing later tries to remove it again. Ending a grant removes only what it gave: the same role held for a scope group stays.

Access reviews

A review campaign takes up to 20 catalog items and lists everyone who holds them when it starts: group members, holders of management roles (including groups that hold them) and members of application roles. Reviewers are each item's owner, each person's manager, or one named reviewer, and a reviewer is never the subject of an item; such items go to the subject's manager, then to administrators. Access with no recorded reason, which did not come from a request or a grant, is marked and listed first, and keeping it needs a reason. Removing an item takes the access away at once, reads it back, and stores the confirmation with the decision. At the deadline, undecided items escalate once to the reviewer's manager with a new deadline; they never count as kept. Reviewers decide on /account/reviews; administrators decide items routed to them in the campaign on the Reviews tab. Management authority (a management role, or a group that gives one) is never reviewed by a manager: its items go to the owner, then administrators, and starting the review or removing the access needs that authority.

Management roles through groups and scopes

Under Groups, Management roles lets a group give its members management roles, for the whole tenant or only for the members of a scope group. Under Users, Roles for part of the tenant gives one person a role for the members of a scope group. A scoped role applies only to reading, editing, locking and unlocking those members, setting their passwords, resetting their sign-in methods and their connected applications; its other permissions are not given, and scoped permissions never let the holder grant access to others. Once a group gives or scopes management roles, changing its members needs the same permissions as assigning those roles directly, and a provisioning client's SCIM changes to its members are refused. A group that people can request from the catalog, or that an access rule fills, cannot give or scope management roles, because whoever offered it or wrote the rule never had to hold that authority. Group-held and time-bound Tenant Admin never count toward keeping an administrator, and no review, revocation or expiry removes the last BTL user's standing Tenant Admin. Groups hold people only, so there are no nested groups.

Access rules

On the Access rules tab, a rule names a group and a condition over people's attributes: department, title, organization, division, cost center, employee number, user name, email domain, person type, or any of your own extension attributes. Each line compares one attribute (is, is not, is one of, starts with, has a value, has no value), and a rule matches when every line, or any line, is true. The tenant recalculates the rule whenever it changes and whenever someone's attributes change, from the portal or a provisioning client. People who match join the group; people the rule added leave when they stop matching. A rule never removes a member it did not add, someone holding the group through a time-bound grant, or someone with an exception: a record with a reason, an owner and an end date that keeps one person in the group until then. When a rule would remove more than its share of members within an hour (20% by default, but always at least five), the rest wait as held removals until an administrator applies or keeps them. In a review, a rule's members are one item for the rule; removing it turns the rule off and removes the members it added.

Separation of duties

On the Separation tab, a conflict rule names two sides, each a list of management permissions, groups, management roles or application roles. A preventive rule refuses the change that would give someone both sides, whatever the path: a role assignment, a group membership (including one from an access rule or SCIM), a group's management roles, an application role, an approved request or a time-bound grant. The refusal is recorded with the rule. An exception lets one person hold both sides until a date, with a reason, a compensating control and an owner who is never that person; each use is recorded. A detective rule only reports, and Run scan lists everyone who holds both sides now, including pairs created by editing a role. A rule of the second kind stops people editing or deleting a management role they hold.

Lifecycle dates and leave

Under Settings, map your own extension attributes (from Schemas) to a start date, an end date and a sponsor. While a mapping or an access rule uses an attribute, Schemas will not delete it or its schema; change the mapping or rule first. Before a person's start date their account cannot sign in; at the start it opens, and the tenant can email a one-time activation link that works until the end of that day. At the end date the account is locked, its sign-ins and tokens end, and the lock records contract_ended. A sponsor is told a set number of days before the end and can extend it, or confirm it, on their Approvals page; the decision is recorded. On the Lifecycle tab, a leave window suspends sign-in from its first day to its return date and keeps groups and roles. Each lock and restore names its reason and leave. Lifecycle only unlocks what lifecycle locked, so an administrator's own lock stays. Lifecycle dates and leave apply to tenant users only: a BTL user's status belongs to the BTL directory, so it is never locked from a tenant. Mapping the start or end date decides when accounts lock and open, so changing it needs the authority to lock and unlock the people it covers, including over their management roles.

Email notices and moves

The tenant emails people when a request is routed to them and when they have access to review, with a reminder before the deadline. The emails name no person or access; they point to the tenant's Approvals and Reviews pages. Each send is recorded. Turn either off under Settings. With moves turned on, a change to someone's department or manager opens a small review for their new manager of the access no access rule recalculated.

Change reasons

Changes to people, their passwords and sign-in methods, their status, group memberships and role assignments can name why they were made. Audit never stores free text, so a reason is one of a fixed list: joiner, mover, leaver, an approved access request, an access review decision, a help desk or support request, identity verified for account recovery, a security incident response, a correction of wrong data, or a policy or compliance change. Under Settings, Change reasons chooses which of these people can pick, all of them at first, and whether changes made in the portal, or through SCIM, must name one. Neither is required at first, and a requirement needs at least one reason to choose from.

In User Management and Groups, each change's dialog has a Change reason field while the tenant offers any. A change through the management API names its reason in the change_reason field of its body. A SCIM client sends the BTL-Change-Reason header with a reason code, such as leaver, on a write; a Bulk request's header applies to each of its operations. A missing reason, while one is required, is refused with change_reason_required, a value outside the list with unknown_change_reason, and a reason the tenant does not offer with change_reason_not_offered; nothing changes. Each record of the change in Audit, including a refusal, shows the reason, for example "Change reason: Leaver: someone leaves.", and so does an export. Reads and sessions or application access ended from a user's details take no reason.

Reports and ownership

The Reports tab answers the questions a review starts from. Sign-ins lists accounts by last sign-in, never-used first, filtered to those without a sign-in for 30, 90, 180 or 365 days, with each account's source, status and, for shared accounts, its owner. Export CSV downloads what the table shows, up to 1,000 rows; a cell a spreadsheet would read as a formula is kept as text. Client use shows how each OAuth client used the tenant over the last 90 days: grants and response types, how it authenticated, whether it sent PKCE, the redirect URIs it used, its last use, and when its current and previous secrets were last presented, so a rotation can see the old secret fall out of use before ending it. Only issued tokens count as use; refused requests are in Audit. Ownership records an owner, a description and a sensitivity for clients, accounts, groups, management roles and application roles, and whether an account is shared. An owner who has since been deleted or locked is shown as left, so orphaned items stand out, and Audit records each owner by account ID. A catalog item keeps its own owner and deputy, who decide requests and reviews for that offer; an ownership record describes the item itself.

Under Report-only settings on Client use, a stricter setting can run before it is enforced. A confidential client that does not require PKCE yet can have its requests without a challenge counted, to preview requiring it. A grant answered at the token endpoint (client credentials, refresh tokens, JWT bearer assertions or token exchange) can be marked for removal: it leaves the client's list in the same change but is still accepted and counted. A client under FAPI 2.0 accepts only the grants it lists, so it has no report-only grants, and any it had stop being accepted when FAPI 2.0 applies. Each request that would have been refused is counted and listed by shape, so you can see who still relies on the old behavior. A redirect URI or response type the client registers can be marked for removal the same way: it leaves the client's registration in the same change, authorization requests that use it still work, and each one is counted when its code is redeemed, or when its tokens are issued for responses that carry them. The redirect URIs left must still give a pairwise client its sector and a front channel logout address its origin. Untick a mark to refuse it from then on. For people, a sign-in requirement in report-only mode counts the sign-ins that did not use a passkey, or two kinds of factor, under Sign-in requirement on the Reports tab; see Sign-in requirement. SCIM and portal changes do not carry a change reason.

Audit, permissions and limits

Every catalog change, request, step routing, decision, fulfilment, grant, end, review decision and escalation is recorded in the tenant's Audit under the User directory source, with the request or campaign as its correlation ID, so searching that ID returns the whole decision trail. The request's dialog shows its Request ID and a review shows its Review ID. Reasons and notes stay with the request and are shown in Governance; Audit records that a reason was given, never its text. When a change is refused because the actor does not hold a permission they tried to hand out, the answer is access denied and Audit records the reason delegation_limit with the permissions that were missing. The catalog, requests, grants and reviews each have read and manage permissions, approving administrator steps has its own, and Tenant Admin holds them all. Access rules, separation rules, lifecycle and settings each have read and manage permissions. Reading reports and changing ownership records have their own permissions, every report read is recorded, and report-only settings are changed with the client update permission. A tenant can keep 200 catalog items, 500 waiting requests (20 per person), 2,000 grants in effect, 2,000 items in one review, 100 access rules, 100 separation rules and 10 open leave windows per person, shown in its usage view. A point-in-time restore keeps management roles removed from groups and scopes removed.