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 + grant created + provisioning job queued
      → else: pending approval queue
  → approver approves/denies (single or bulk)
      → approve: grant pendingProvision + job queued
      → deny: request denied
  → job-runner executes provisioning path
      → connected connector success: grant becomes active
      → manual path: job moves to manualPending until approver confirms
  → 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 site setup and management actions.

Quick launch checklist

1. Open Jira settings → Apps → AI Clearance.
2. In Intake & Approvals, select the JSM intake project, portal, request types, approvers, escalation targets, and review-before-expiry settings.
3. In Catalog, add at least one approved AI tool with risk, default expiry, and optional connector binding.
4. In Governance, review risk rules, approval defaults, unknown-tool handling, and exception limits.
5. In Connectors, optionally configure Okta or Microsoft Entra group automation.
6. Submit one portal request and validate status in the portal, global page, requests table, and governance logs.

Connected mode prerequisite (for Okta/Entra provisioning)

• AICLEARANCE_CONNECTED_ENABLED=true
• ARDSAOR_CORE_URL, ARDSAOR_CORE_APP_ID, ARDSAOR_CORE_APP_SECRET
• Active license required; otherwise connected connector automation stays blocked.
• Each connected catalog tool creates or binds a dedicated provider entitlement group. AI Clearance manages membership in that group only; customers assign the real app/resource to the group in Okta or Microsoft Entra.

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

4) Jira admin control plane

Entry: Jira settings → Apps → AI Clearance.

Guardrail: management actions are admin-gated. The app is now site-governance first; there is no separate project-settings happy path in the current release model.

4.1 Overview

• Launch readiness cards for catalog, governance, approval defaults, intake project, portal entry point, and optional connector automation.
• Route actions open the exact section needed to complete setup.
• Summary counters show catalog tools, approvals, connectors, and current readiness state.

4.2 Intake & Approvals

• Select the JSM intake project and portal entry point.
• Restrict allowed portal request types when needed.
• Configure approver routing, fallback behavior, escalation timing, and review-before-expiry issue creation.

4.3 Catalog

Purpose: define governed AI tools and approval metadata.

• Add tool form: display name, provider, status, risk level, default expiry, local guidance, optional connector binding, and entitlement-group metadata.
• Status model: approved tools are requestable; blocked/denied tools are governed but not requestable.
• Catalog seed: administrators can seed common AI tools from the supported tools/models catalog and then customize local policy.

4.4 Connectors

• Supported connected providers: okta-group and entra-group; manual fulfillment remains the fallback.
• Create, edit, test, enable, disable, or delete provider connectors.
• Connector config is stored through Forge secret storage.
• Identity mappings can match Jira users to provider accounts by email or explicit mapping.
• Connected types require connected mode and ArdSaor Core credentials.

4.5 Governance

• Configure risk-level approval requirements, max duration by risk level, security/Jira-admin review rules, unknown-tool blocking, and critical exception limits.
• Approval defaults are versioned so audit history can show which policy version was active at decision time.
• Controlled override and exception flows are tracked for review and expiration.

4.6 Requests

• Review pending, approved, denied, active, historical, and manual follow-up records from one admin surface.
• Apply single or bulk approval/denial actions where permitted.
• Close manual provisioning, deprovisioning, and verification tasks.
• Export request and grant data for operational review.

5) Global page: AI Clearance

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: Approved Tools

• Lists tools that are available to request under the current governance policy.
• Shows status, expiry defaults, request guidance, and any configured fulfillment notes.

5.3 Tab: Request History

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

5.4 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) Admin reporting, requests, and audit logs

Entry: Jira settings → Apps → AI Clearance.

• Requests: pending approvals, request history, grants, manual follow-up, and exports.
• Insights: monthly rollups, adoption, active access, risk mix, people insights, and operational counters.
• Governance Logs: audit event search, detail drawers, chain fields, metadata, and export controls.
• Embedded help: links route administrators to the relevant documentation anchors.

7) JSM portal and native Jira request surfaces

7.1 Request create panel: Select AI tool

Purpose: capture governance metadata before request submission.

Inputs: approved AI tool or “Request new tool”, optional tool URL for new tools, and requested duration.

• The panel appears only for the configured intake portal and allowed request types.
• Submitting writes an AI Clearance snapshot to the created issue property.
• Request context is later enriched from the native Jira issue summary and description.
• 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 Native Jira request view

• The issue-created trigger reads the portal snapshot and Jira request fields.
• AI Clearance can enrich the issue summary/description into a structured access request record.
• Approval, denial, auto-approval, grant, and provisioning events can add issue comments and transition the request where matching workflow transitions exist.

7.3 Portal gating behavior

• Wrong project does not ingest.
• Wrong portal renders no AI Clearance create panel.
• Wrong request type renders no AI Clearance create panel.

8) Connector setup and operational flows

Connector types and behavior

Connected mode is optional. Manual fulfillment remains available when no provider connector is configured. When connected mode is enabled, AI Clearance talks to ArdSaor Core over signed HTTPS; ArdSaor Core dispatches the provider action.

Connected mode prerequisites

• Connected mode feature flag enabled.
• Core remote credentials configured.
• License active.
• A dedicated entitlement group per connected catalog tool. AI Clearance manages group membership only; the customer must assign the real AI app/resource to that group in the provider.

Connector data and trust boundary

• Requests to ArdSaor Core are HMAC signed with X-Ardsaor-App, X-Ardsaor-Date, and X-Ardsaor-Sig.
• Remote payloads can include cloud ID, connector metadata, grant metadata, subject identifiers, external identity, and optional operational context.
• Connector credentials and external identity secret values are stored through Forge secret storage.
• Upstream remote errors are normalized and sanitized before being surfaced to logs or users.

Provisioning/deprovision/check job outcomes

• Success: job succeeded; audit event recorded.
• Retryable failure: exponential retry backoff schedule.
• Terminal failure: job marked deadLetter.
• Manual mode: job marked manualPending until human completion.

9) Access grant/deny workflows with examples

Example A — Manual approve from Approvals tab

1. Select pending request in Approvals tab.
2. Click Approve (or bulk approve).
3. System writes request decision = approved and creates grant in pendingProvision.
4. Provisioning job is queued.
   • Connected connector: grant becomes active after successful remote action.
   • Manual connector: job becomes manualPending until approver marks fulfilled.
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 the intake project, portal ID, and request type IDs in 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"

• Connected mode must be enabled and licensed.
• Core env vars must be present: ARDSAOR_CORE_URL, ARDSAOR_CORE_APP_ID, ARDSAOR_CORE_APP_SECRET.

"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.

"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 review-before-expiry issue type ID in Intake & Approvals.
• 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. The JSM portal request-create panel explicitly allows customer and unlicensed access where Atlassian permits the request form.

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 manual provisioning steps closed?

Approvers complete them from the Approvals tab under “Manual provisioning actions”.

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
• governed-asset, risk-profile, governance-policy, site-intake-config
• request, access-grant, provisioning-job, audit-event
• external-identity, reconciliation-record, project-registry

14) Admin and security considerations

• Runs on Atlassian Forge; no dedicated customer-managed server required for baseline mode.
• Connected mode uses signed HTTPS calls to ArdSaor Core and the configured Okta or Microsoft Entra provider.
• Connector secrets and external identity values use Forge secret storage references.
• 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.

Related documentation

Current product docs are listed first. Older app docs are reference material unless ArdSaor support confirms a current rollout.

Current product docs

• AI Clearance (tools/models catalog)
• Access Evidence

Reference docs

• DriftGuard
• Filter Hygiene
• ImpactLoop
• Label Doctor
• TaskPort