AI Clearance — Complete Operations Guide

1) Product overview and end-to-end flow

AI Clearance captures governance metadata at request creation, ingests it into app storage, applies policy-driven approval rules, and tracks the provisioning lifecycle through to recertification, expiry, and retention.

Canonical flow (runtime)

JSM portal create panel
  → writes snapshot fields to issue property
  → issue-created trigger ingests request (decision = pending)
	  → optional auto-approval policy evaluation
	      → if match: request auto-approved + connectorless grant active or connected provisioning queued
	      → else: pending approval queue
	  → approver approves/denies (single or bulk)
	      → approve: connectorless grant active or connected grant pendingProvision + job queued
	      → deny: request denied
	  → job-runner executes connected provisioning path
	      → Okta/Entra group success: grant becomes active
	      → failure/non-automated follow-up: clear retry or manual action state
  → recert/expiry/escalation/retention sweeps maintain lifecycle and evidence

2) Getting started and prerequisites

Platform prerequisites

• Jira Cloud site with Jira Service Management (for portal modules).
• AI Clearance installed and licensed on the site.
• Jira admin rights for initial setup (admin actions are site-admin gated).

Quick launch checklist

1. Open Jira admin → Apps → AI Clearance.
2. In Intake & Approvals, choose the intake project, portal, request types, approver routing, and recertification settings.
3. In Catalog, add or seed at least one requestable tool.
4. In Governance, review approval guardrails and default outcomes.
5. If you plan to automate Okta or Entra group membership, configure Connectors before adding connected catalog tools.
6. Submit one portal request and validate status in portal detail, the global page, and Jira admin requests history.

Connector prerequisites (for Okta/Entra provisioning)

• ARDSAOR_CORE_URL, ARDSAOR_CORE_APP_ID, ARDSAOR_CORE_APP_SECRET
• Active license required; otherwise connected connectors stay blocked.
• At least one active Okta or Microsoft Entra connector.
• Admin-managed identity mappings for each grantee and provider type.
• One provider entitlement group per connected catalog tool or role.
• Admin confirmation that the entitlement group is assigned to the real app/resource in Okta or Entra.

3) Navigation map (every page/view/state)

4) Jira admin page (all tabs)

Entry: Jira admin → Apps → AI Clearance.

Guardrail: site-admin permissions are required for management actions.

4.1 Overview

• Launch-readiness summary for intake, catalog, governance, approval defaults, and requestable catalog state.
• Next-step guidance routes admins directly into the setup area that still needs attention.
• Launch note: connectorless tools work without provider automation; connector-backed tools use the Connectors and Catalog setup path.

4.2 Intake & Approvals

• Select the single JSM intake project used for AI Clearance requests.
• Choose the portal and allowed request types for intake.
• Configure approver routing, SLA/escalation hours, and recertification issue type/window.
• Inline section status badges show whether project setup, routing, SLA, and recertification are complete.

4.3 Catalog

• Create and edit governed AI tools with status, risk, expiry, provider, and summary metadata.
• Seed the recommended starter catalog from the built-in catalog dataset.
• Approved, pilot, restricted, blocked, and retired statuses determine whether tools stay requestable.
• If a tool should use provider automation, select an Okta or Microsoft Entra connector during add/edit and create or bind the tool entitlement group.

4.4 Connectors

• Admins can create Okta group and Microsoft Entra group connectors.
• Connector configuration is site-wide; each connected catalog tool stores its own provider entitlement group.
• AI Clearance can create or bind the provider group, but customer admins still assign the real app/resource to that group in Okta or Entra.
• Admins manage Atlassian-account-to-provider-identity mappings on this page. Requesters do not enter Okta or Entra identities.
• Missing identity mappings produce a clear manual follow-up state instead of silently activating provider access.

4.5 Governance

• Define request guardrails such as unknown-tool blocking, review requirements, security review, Jira admin review, and risk-based duration limits.
• Configure automatic approval defaults by risk level.
• Manage request-specific exception overrides without leaving the admin surface.

4.6 Requests

• Operate the configured intake project from one place: pending approvals, connector follow-up work, and full request history.
• Approve, deny, bulk approve, and bulk deny pending requests.
• Complete provider follow-up actions when automation needs human intervention.
• Filter and export request history by decision, issue key, request ID, and date range.

4.7 Insights

• Review summary cards for tools with active access, users with active access, active grants, and most-adopted tool.
• Inspect tool adoption and people views with search, filters, and detail drawers.
• Group-level messaging stays explicit when organizational mappings are not configured.

4.8 Governance Logs

• Inspect the audit stream by action, request ID, grant ID, and date range.
• Verify the audit chain and review the last verification result.
• Export filtered audit events as JSONL and drill into individual event metadata.

5) Global page: AI Clearance (My Access + Approvals)

Entry: Jira Apps menu → AI Clearance.

5.1 Tab: My Access

• Shows active + pendingProvision grants for current user.
• Expiry labels: expired / expires today / expires tomorrow / N days remaining.
• Highlights expiring-soon and expired grants.
• Extension self-service button is currently disabled by design.

5.2 Tab: Request History

• Shows requester’s prior requests (paginated).
• Decision badges (approved/denied/pending styling).
• Issue key links open Jira issue view directly.

5.3 Conditional tab: Approvals

This tab appears only when the user has approval access in at least one registered project.

• Pending requests table: select rows, single approve/deny, bulk approve/deny.
• Bulk confirmation prompts before applying decisions.
• Manual provisioning actions table: provision/deprovision/check jobs pending human confirmation.
• Manual action completion buttons: Mark fulfilled / Mark deprovisioned / Mark verified.

Operational limits: bulk operations cap at 50 issue keys per request; rate-limited to 5 operations/minute per actor.

6) Focused admin routes and evidence views

Entry: Jira admin → Apps → AI Clearance, then open the desired hash route.

• Requests: operational review surface for pending approvals, connector follow-up, and request history.
• Insights: adoption visibility for tools and people.
• Governance Logs: audit explorer, verification, and export evidence.
• These focused routes are also used for deterministic screenshot and review-harness capture runs.

7) JSM portal pages

7.1 Request create panel: AI Clearance Request

Purpose: capture governance metadata before request submission.

Inputs: tool, business use, data classes, and requested duration.

• Auto-save submits snapshot payload to issue fields as user types (debounced).
• Provider identities for Okta or Entra are managed by admins in the connected Connectors page, not by requesters in the portal.
• Form is considered valid only when gate is enabled and required fields are complete.

Expected output: issue property includes aiclearance.snapshot.v1 with request context used by ingestion.

7.2 Request detail panel: AI Clearance

• Shows decision/status/tool/data classes/expiry when gate is enabled.
• If request exists but no grant yet: status remains pending/provisioning depending on decision state.
• If gating fails: friendly reason returned (portal or request type not enabled).

7.3 Portal subheader: Approved Tools

• Lists only tools with status approved.
• Empty state appears when no approved tools are configured.
• Shows gate-disabled reason when portal is out of scope.

8) Connector setup and operational flows

Connector types and behavior

Connected tool setup order

• Configure the Okta or Microsoft Entra connector. Use the Okta setup guide or Microsoft Entra setup guide for provider-specific steps.
• Add admin-managed identity mappings for each grantee and connector type.
• Add or edit a catalog tool and select the connector.
• Create the recommended entitlement group, such as AI Clearance - Claude Enterprise - Users, or bind an existing provider group by ID.
• Assign the provider group to the real app/resource in Okta or Entra.
• Confirm app/resource assignment in AI Clearance before approving the connected tool.

What AI Clearance does not automate in v1

• AI Clearance does not assign Okta or Entra apps/resources to groups.
• AI Clearance does not search provider app catalogs or manage provider app roles.
• AI Clearance does not grant generic API-key/API-platform products unless the customer’s IdP group truly controls that entitlement.

Provisioning/deprovision/check job outcomes

• Success: job succeeded; audit event recorded.
• Retryable failure: exponential retry backoff schedule.
• Terminal failure: job marked deadLetter.
• Manual follow-up: failed or non-automated work is surfaced for human completion.

9) Access grant/deny workflows with examples

Example A — Approve from Approvals tab

1. Select pending request in Approvals tab.
2. Click Approve (or bulk approve).
3. System writes request decision = approved.
4. Fulfillment depends on tool setup.
   • Connectorless tool: grant becomes active inside AI Clearance without provider-side changes.
   • Connected connector: grant becomes active after successful remote action.
5. Issue transition attempt is made using approve transition names (approve/approved/accept/accepted).
6. Audit events recorded: request approved + grant created + provisioning progress.

Example B — Deny request

1. Click Deny (single or bulk).
2. Decision becomes denied; no grant is created.
3. Issue transition attempt uses deny candidates (deny/denied/decline/reject/cancel variants).
4. Audit event request_denied is recorded.

Example C — Auto-approval policy path

1. Issue created trigger ingests valid snapshot and pending request.
2. Policy engine checks:
   • matching policy by project/tool (or all-tools policy),
   • autoApprove=true,
   • group membership match,
   • requested duration not above policy max (if configured).
3. If all pass: decision source set to auto-policy, grant/job created, issue commented with auto-approval evidence.

Example D — Extend or revoke active grant (issue-level management logic)

• Extensions are bounded by total max lifetime (180 days from original grant start).
• Expired grants can only be extended inside a 7-day grace window.
• Revoking queues deprovision job if one is not already active.

10) Scheduled jobs, automation, and lifecycle events

• Issue created trigger: ingests portal snapshot into request storage.
• Job runner (hourly): executes queued provisioning/deprovision/check jobs; expires overdue grants; prunes old job records.
• Approval escalation sweep (hourly): tracks pending approval timers, records SLA breaches/escalations, adds comments.
• Recertification sweep (daily): creates recert issues for grants entering recert window.
• Retention sweep (daily): prunes old audit events and retained external-identity metadata.
• Analytics runner (daily): updates telemetry rollups.

11) Troubleshooting by symptom

"Portal panel says not enabled"

• Confirm portal and request type IDs are configured in Jira admin under Intake & Approvals.
• If using request-type restrictions, ensure correct numeric request type IDs are saved.

"Requests are created but never appear in approvals"

• Verify snapshot property exists on created issue.
• Check issue-created trigger logs for snapshot validation errors.
• Ensure request decision is still pending and not already decided.

"Approve/Deny action fails"

• Confirm approver access policy for project (admin fallback or configured approver governance).
• Confirm issue transition/comment permissions are available.
• If bulk action, ensure selected count does not exceed 50.
• If repeated quickly, check for rate-limit errors.

"Connected connector cannot be enabled"

• Confirm the site has an active AI Clearance license and the admin has access to the Connectors tab.
• Core variables must be present: ARDSAOR_CORE_URL, ARDSAOR_CORE_APP_ID, ARDSAOR_CORE_APP_SECRET.
• Confirm the connector test passes for Okta or Entra before assigning it to catalog tools.
• If the tab is unavailable, contact support with the Jira site URL and installation details.

"Grant stays pendingProvision"

• For manual connectors, this is expected until a manual completion action is confirmed.
• For connected connectors, inspect job-runner logs for retry/dead-letter reasons.
• If the error mentions missing external identity, add the admin-managed Okta or Entra identity mapping for the grantee Jira user.

"Auto-approval not triggering"

• Policy must match tool scope and have autoApprove=true.
• Requester must be in at least one allowed Jira group.
• Requested duration must not exceed policy max expiry (if configured).

"Recert issues are not being created"

• Set a valid recert issue type ID in Recertification tab.
• Confirm grants are active and within recert window.
• Check recert sweep logs for issue creation failures.

12) FAQ

Does AI Clearance support unlicensed portal users?

Yes. Portal create/detail/subheader modules explicitly allow customer and unlicensed access.

Can users self-extend grants from My Access?

Not currently. Self-service extension is intentionally disabled; use approval workflow.

What is the default export date range?

90 days by default, with a maximum allowed window of 365 days per export request.

What if a user already has an active grant for the same tool?

Approval is blocked for duplicate open grants; the workflow returns an explicit conflict error.

How are connector follow-up steps closed?

Approvers complete them from the Approvals tab under “Manual provisioning actions” when automation needs human confirmation.

13) Permissions and data model

Forge scopes

• manage:jira-configuration
• read:jira-user
• read:jira-work
• write:jira-work
• read:servicedesk-request
• write:servicedesk-request
• storage:app

Core entities (high level)

• tool, approval-policy, connector, baseline-access
• request, access-grant, provisioning-job, audit-event
• site-identity-mapping, external-identity, reconciliation-record, project-registry

14) Admin and security considerations

• Connectorless operation runs on Atlassian Forge with no dedicated customer-managed server.
• Connector-backed tools use backend egress to ArdSaor Core for Okta or Microsoft Entra group membership actions.
• Connector secrets and external identity values use Forge secret storage references or approved backend secret storage.
• Requesters do not provide provider identities. Admins manage identity mappings by Jira user.
• No arbitrary webhook connector is supported.
• Audit trail is hash-chained (prevHash/entryHash/entryMac) and verifiable from settings export tooling.
• Retention defaults to 365 days for audit events (configurable by environment variable).
• External identity retention follows audit retention unless overridden.
• Sensitive actions (bulk approvals/exports/audit verify) are rate-limited.
• Approval governance supports admin fallback plus role-based and delegated approver routing.

15) Support

Need help, rollout guidance, or connector troubleshooting? Contact us via the Marketplace support channel, or via our support inbox. Include your Jira site URL, project key, and a short timeline of what happened.