Getting Started

Overview

This guide walks you through connecting an Azure tenant to Britive and granting your first just-in-time Azure RBAC role assignment — no standing permissions, full audit trail on every checkout.

What you’ll accomplish:

Register a Britive enterprise application in Azure Active Directory
Grant required API permissions and assign the integration role
Onboard the Azure application in the Britive console
Create an access profile for an Azure role assignment
Check out and verify JIT access end-to-end

How It Works

Britive registers as an enterprise application in Azure AD and uses the Microsoft Graph API and Azure RBAC API to manage role assignments. At checkout, Britive creates a scoped role assignment for the user. At checkin (or on expiry), the assignment is deleted — no standing access remains.

User → Britive Console → Microsoft Graph API → Azure RBAC role assignment (scoped, timed) → Deleted on checkin

Before You Begin

Britive tenant with administrator access
Azure Global Administrator or Application Administrator access to register enterprise applications
An Azure subscription to protect with JIT access
Azure CLI installed (az login)

Never hardcode credentials. Use environment variables, your secret manager, or the Britive Secrets Store.

Step 1 — Register Britive in Azure AD

Britive needs an app registration in Azure AD to authenticate to the Microsoft Graph and Azure RBAC APIs.

Python Automation

The azure_setup.py script registers the Britive application in Azure AD and assigns a custom role at the Tenant Root Group level, giving Britive the permissions it needs to manage role assignments across all subscriptions.

git clone https://github.com/britive/onboarding.git
cd onboarding
pip3 install -r requirements.txt

Authenticate with Azure:

az login

Set required environment variables:

export AZURE_TENANT_ID=your-tenant-id
export BRITIVE_TENANT=your-tenant
export BRITIVE_API_TOKEN=your-api-token

BRITIVE_TENANT takes just the subdomain (not AZURE_TENANT_ID, which is a separate Azure identifier) — see Finding Your Tenant Name.

Run the setup script:

python python/azure/azure_setup.py

The script outputs the Application (client) ID and client secret — copy these, you’ll need them to register Azure in Britive.

Manual Setup

Register the application

In the Azure portal, go to Azure Active Directory → App registrations → New registration. Name it Britive and register it with default settings.

Grant API permissions

Under API permissions → Add a permission → Microsoft Graph, add the permissions required by Britive (listed in the Britive documentation). Click Grant admin consent for your tenant.

Create a client secret

Go to Certificates & secrets → New client secret. Set an expiry and copy the secret value immediately — it is displayed only once.

Assign the integration role

At the subscription (or management group) level, assign the Britive application the User Access Administrator built-in role. This allows Britive to create and delete role assignments on behalf of users.

Step 2 — Register Azure in Britive

After the app registration is complete, connect your Azure tenant to Britive.

Add the application

In the Britive console, go to Applications → Add Application → Azure. Enter:

Field	Value
Tenant ID	Your Azure AD tenant ID
Client ID	The application (client) ID from the app registration
Client Secret	The secret created in Step 1

Click Save.

Wait for the initial scan

Britive scans Azure to import your subscriptions and available role definitions. This takes 1–3 minutes. The application status changes to Connected when complete.

For detailed onboarding reference, see the Britive documentation and the britive/onboarding repository.

Create Your First Access Profile

An access profile defines which Azure role definitions a group of users can check out, at what scope, and for how long.

Using the Britive Console

Open the Azure application

Navigate to Applications → select your Azure application → Profiles → Add Profile.

Configure the profile

Field	Value
Name	A descriptive name (e.g., `DevOps-Contributor`)
Environment	Select the Azure subscription
Expiration	Max session duration (e.g., `1h0m0s`)

Add permissions

Under Permissions, add the Azure role definitions to grant on checkout (e.g., Contributor, Reader).

Add a policy

Under Policies, click Add Policy. Assign members (users or tags) and set any approval or time-of-access conditions.

Save and activate

Click Save. The profile appears in My Access for assigned members.

Using Terraform

data "britive_application" "azure" {
  name = "Azure"
}

resource "britive_profile" "devops" {
  app_container_id    = data.britive_application.azure.id
  name                = "DevOps-Contributor"
  expiration_duration = "1h0m0s"

  associations {
    type  = "Environment"
    value = "Production Subscription"
  }
}

resource "britive_profile_permission" "contributor" {
  profile_id      = britive_profile.devops.id
  permission_name = "Contributor"
  permission_type = "role"
}

resource "britive_profile_additional_settings" "devops" {
  profile_id          = britive_profile.devops.id
  console_access      = true
  programmatic_access = true
}

resource "britive_profile_policy" "devops" {
  profile_id  = britive_profile.devops.id
  policy_name = "DevOps-Access-Policy"

  members = jsonencode({
    tags  = [{ name = "devops-team" }]
    users = []
  })

  access_type = "Allow"
  consumer    = "papservice"
  is_active   = true
  is_draft    = false
}

Verify

Check out the profile

Navigate to My Access → find your profile → click Check Out.

Confirm the role assignment in Azure

az role assignment list \
  --assignee <your-user-object-id> \
  --subscription <subscription-id> \
  --output table

You should see a Contributor (or whichever role you added) assignment for your user.

Check in

Return to My Access → click Check In. Re-run the az role assignment list command — the assignment should no longer appear.

Troubleshoot

Symptom	Likely cause	Fix
Application shows “Disconnected”	Client secret expired or entered incorrectly	Regenerate the secret in Azure AD and update it in Britive
Checkout fails with `AuthorizationFailed`	User Access Administrator role not assigned to the Britive app	Assign the role at the correct scope (subscription or management group)
Subscriptions not visible after scan	Britive app lacks Reader access at management group level	Grant `Reader` on the root management group to the Britive app
Role assignment not deleted after checkin	Britive app lacks write permissions on that subscription	Verify User Access Administrator is assigned at the correct scope
`python azure_setup.py` fails on role assignment	Insufficient privileges for the logged-in account	Log in with a Global Administrator or Privileged Role Administrator account

Next Steps

Britive documentation — complete Azure onboarding reference
britive/onboarding on GitHub — Python automation scripts

Last updated on July 8, 2026