README
¶
Azure PIM CLI
Azure Privileged Identity Management Command Line Interface
az-pim-cli eases the process of listing and activating Azure PIM roles by allowing activation via the command line. Authentication is handled with the azure.identity library by utilizing the AzureCLICredential method.
It currently supports 'azure resources', 'groups', and 'entra roles'
Install
Install with go install
$ go install github.com/netr0m/az-pim-cli@latest
Clone and build yourself
# Clone the git repo
$ git clone https://github.com/netr0m/az-pim-cli.git
# Navigate into the repo directory and build
$ cd az-pim-cli
$ go build
# Move the az-pim-cli binary into your path
$ mv ./az-pim-cli /usr/local/bin
Configuration
In addition to supporting environment variables and command line arguments, the script also supports certain config parameters stored in a file. By default, the script will try to look for a YAML config file at $HOME/.az-pim-cli.yaml, but you may also override the config file to use by supplying the --config flag.
See Configuration options for more details
Prerequisites
This tool depends on az-cli for authentication. Please ensure that you've authenticated with your Azure tenant by running the command az login. A new browser window will open, asking you to authenticate. This should only be necessary to do once.
Usage
$ az-pim-cli --help
az-pim-cli is a utility that allows the user to list and activate eligible role assignments
from Azure Entra ID Privileged Identity Management (PIM) directly from the command line.
Usage:
az-pim-cli [command]
Available Commands:
activate Send a request to Azure PIM to activate a role assignment
completion Generate the autocompletion script for the specified shell
help Help about any command
list Query Azure PIM for eligible role assignments
version Display the version of az-pim-cli
Flags:
--cloud string Which Azure environment to use ('global', 'usgov', 'china') (default "global")
-c, --config string config file (default is $HOME/.az-pim-cli.yaml)
--debug Enable debug logging
-h, --help help for az-pim-cli
Use "az-pim-cli [command] --help" for more information about a command.
List eligible role assignments
Azure resources
List azure resources
$ az-pim-cli list resources
Example
# List eligible Azure resource role assignments
$ az-pim-cli list resources
== S100-Example-Subscription ==
- Contributor
- Owner
== S1337-Another-Subscription ==
- Contributor
Groups
List groups
$ az-pim-cli list groups
Example
# List eligible group assignments
$ az-pim-cli list groups
== my-entra-id-group ==
- Owner
Entra roles
List entra roles
$ az-pim-cli list roles
Example
# List eligible Entra role assignments
$ az-pim-cli list roles
== my-entra-id-role ==
- Owner
Activate a role
Azure resources
Activate azure resources
$ az-pim-cli activate resource
Examples
# Activate the first matching role for a resource with the prefix 'S100'
$ az-pim-cli activate resource --prefix S100
time=2024-11-20T08:08:08.534+01:00 level=INFO msg="Requesting activation" role=Contributor scope=/subscriptions/6d80fbe7-7508-46e8-9fbf-a9d2e0dfec83 reason="" ticketNumber="" ticketSystem="" duration=480 startDateTime=""
time=2024-11-20T08:08:20.129+01:00 level=INFO msg="The role assignment request was successful" status=Provisioned
time=2024-11-20T08:08:20.129+01:00 level=INFO msg="Request completed" role=Contributor scope=/subscriptions/6d80fbe7-7508-46e8-9fbf-a9d2e0dfec83 status=Provisioned
# Activate a specific role ('Owner') for a resource with the prefix 's100'
$ az-pim-cli activate resource --prefix s100 --role owner
time=2024-11-20T08:08:08.534+01:00 level=INFO msg="Requesting activation" role=Owner scope=/subscriptions/6d80fbe7-7508-46e8-9fbf-a9d2e0dfec83 reason="" ticketNumber="" ticketSystem="" duration=480 startDateTime=""
time=2024-11-20T08:08:20.129+01:00 level=INFO msg="The role assignment request was successful" status=Provisioned
time=2024-11-20T08:08:20.129+01:00 level=INFO msg="Request completed" role=Owner scope=/subscriptions/6d80fbe7-7508-46e8-9fbf-a9d2e0dfec83 status=Provisioned
# Activate a specific role ('Owner') for a resource with a narrower scope
$ az-pim-cli activate resource --name S100-Example-Subscription --scope /subscriptions/6d80fbe7-7508-46e8-9fbf-a9d2e0dfec83/resourceGroups/example-rg --role Owner
time=2024-11-20T08:08:08.534+01:00 level=INFO msg="Requesting activation" role=Owner scope=/subscriptions/6d80fbe7-7508-46e8-9fbf-a9d2e0dfec83/resourceGroups/example-rg reason="" ticketNumber="" ticketSystem="" duration=480 startDateTime=""
time=2024-11-20T08:08:20.129+01:00 level=INFO msg="The role assignment request was successful" status=Provisioned
time=2024-11-20T08:08:20.129+01:00 level=INFO msg="Request completed" role=Owner scope=/subscriptions/6d80fbe7-7508-46e8-9fbf-a9d2e0dfec83/resourceGroups/example-rg status=Provisioned
# Activate a resource role and specify a ticket number for the activation
$ az-pim-cli activate resource --name S100-Example-Subscription --role Owner --ticket-system Jira --ticket-number T-1337
time=2024-11-20T08:08:08.534+01:00 level=INFO msg="Requesting activation" role=Owner scope=/subscriptions/6d80fbe7-7508-46e8-9fbf-a9d2e0dfec83 reason="" ticketNumber=T-1337 ticketSystem=Jira duration=480 startDateTime=""
time=2024-11-20T08:08:20.129+01:00 level=INFO msg="The role assignment request was successful" status=Provisioned
time=2024-11-20T08:08:20.129+01:00 level=INFO msg="Request completed" role=Owner scope=/subscriptions/6d80fbe7-7508-46e8-9fbf-a9d2e0dfec83 status=Provisioned
# Activate a resource role and specify the start time for the activation. Uses the local timezone.
$ az-pim-cli activate resource --name S100-Example-Subscription --role Owner --start-time 14:30
time=2024-11-20T08:08:08.534+01:00 level=INFO msg="Requesting activation" role=Owner scope=/subscriptions/6d80fbe7-7508-46e8-9fbf-a9d2e0dfec83 reason="" ticketNumber=T-1337 ticketSystem=Jira duration=480 startDateTime=2024-11-20T14:30:00+01:00
time=2024-11-20T08:08:20.129+01:00 level=INFO msg="The role assignment request was successful" status=Provisioned
time=2024-11-20T08:08:20.129+01:00 level=INFO msg="Request completed" role=Owner scope=/subscriptions/6d80fbe7-7508-46e8-9fbf-a9d2e0dfec83 status=Provisioned
# Activate a resource role and specify the start time and start date for the activation. Uses the local timezone.
$ az-pim-cli activate resource --name S100-Example-Subscription --role Owner --start-date 31/12/2024 --start-time 09:30
time=2024-11-20T08:08:08.534+01:00 level=INFO msg="Requesting activation" role=Owner scope=/subscriptions/6d80fbe7-7508-46e8-9fbf-a9d2e0dfec83 reason="" ticketNumber=T-1337 ticketSystem=Jira duration=480 startDateTime=2024-12-31T09:30:00+01:00
time=2024-11-20T08:08:20.129+01:00 level=INFO msg="The role assignment request was successful" status=Provisioned
time=2024-11-20T08:08:20.129+01:00 level=INFO msg="Request completed" role=Owner scope=/subscriptions/6d80fbe7-7508-46e8-9fbf-a9d2e0dfec83 status=Provisioned
Groups
Activate groups
$ az-pim-cli activate group
Example
ℹ See examples under Activate - Azure resources for additional parameters.
# Activate the first matching role for the group 'my-entra-id-group'
$ az-pim-cli activate group --name my-entra-id-group --duration 5
time=2024-11-20T08:08:08.534+01:00 level=INFO msg="Requesting activation" role=Owner scope=my-entra-id-group reason="" ticketNumber="" ticketSystem="" duration=5 startDateTime=""
time=2024-11-20T08:08:20.129+01:00 level=INFO msg="The role assignment request was successful" status=Provisioned subStatus=""
time=2024-11-20T08:08:20.129+01:00 level=INFO msg="Request completed" role=Owner scope=my-entra-id-group status=Active
Entra roles
Activate entra roles
$ az-pim-cli activate role
Example
ℹ See examples under Activate - Azure resources for additional parameters.
# Activate the first matching role for the Entra role 'my-entra-id-role'
$ az-pim-cli activate role --name my-entra-id-role --duration 5
time=2024-11-20T08:08:08.534+01:00 level=INFO msg="Requesting activation" role=Owner scope=my-entra-id-role reason="" ticketNumber="" ticketSystem="" duration=5 startDateTime=""
time=2024-11-20T08:08:20.129+01:00 level=INFO msg="The role assignment request was successful" status=Provisioned subStatus=""
time=2024-11-20T08:08:20.129+01:00 level=INFO msg="Request completed" role=Owner scope=my-entra-id-role status=Active
Configuration options
YAML file
You may define configuration options in a YAML file.
By default, the program will use the file ~/.az-pim-cli.yaml ($HOME/.az-pim-cli.yaml), if present. You may override this path with the command line flag --config [PATH].
$ cat ~/.az-pim-cli.yaml
reason: static-reason
ticketSystem: System
ticketNumber: T-1337
duration: 5
cloud: global
Environment variables
You may also define these configuration options as environment variables by prefixing any global variable with PIM_.
export PIM_DURATION=30
export PIM_CLOUD=global
Troubleshooting
To ease the process of troubleshooting, you can add the flag --debug to enable debug logging.
⚠ Debug logs contain sensitive information. Take care to sensor any sensitive data before sharing the output.
$ az-pim-cli activate role --name my-entra-id-role --duration 5 --debug
Testing
To run the unit tests, run the following command from the project root:
$ go test -v ./...
Contributing
Want to contribute to the project? There are a few things you need to know.
See CONTRIBUTING to get started
Documentation
Source Files
Directories