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 --help Query Azure PIM for eligible resource assignments (azure resources) Usage: az-pim-cli list resource [flags] Aliases: resource, r, res, resource, resources, sub, subs, subscriptions Flags: -h, --help help for resource

Global 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

Groups

List groups

:warning: Requires an access token with the appropriate scope. See Token for Entra ID Groups for more details.

$ az-pim-cli list groups --help Query Azure PIM for eligible group assignments Usage: az-pim-cli list group [flags] Aliases: group, g, grp, groups Flags: -h, --help help for group -t, --token string An access token for the PIM 'Entra Roles' and 'Groups' API (required). Consult the README for more information.

Entra roles

List entra roles

:warning: Requires an access token with the appropriate scope. See Token for Entra ID Groups and Roles for more details.

$ az-pim-cli list roles --help Query Azure PIM for eligible Entra role assignments Usage: az-pim-cli list role [flags] Aliases: role, rl, role, roles Flags: -h, --help help for role -t, --token string An access token for the PIM 'Entra Roles' and 'Groups' API (required). Consult the README for more information.

Activate a role

Azure resources

Activate azure resources

$ az-pim-cli activate resource --help Sends a request to Azure PIM to activate the given resource (azure resources) Usage: az-pim-cli activate resource [flags] Aliases: resource, r, res, resource, resources, sub, subs, subscriptions Flags: -h, --help help for resource

Global 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 --dry-run Display the resource that would be activated, without requesting the activation -d, --duration int Duration in minutes that the role should be activated for (default 480) -n, --name string The name of the resource to activate -p, --prefix string The name prefix of the resource to activate (e.g. 'S399'). Alternative to 'name'. --reason string Reason for the activation (default "config") -r, --role string Specify the role to activate, if multiple roles are found for a resource (e.g. 'Owner' and 'Contributor') --start-date string Start date for the activation (as DD/MM/YYYY) -s, --start-time string Start time for the activation (as HH:MM) -T, --ticket-number string Ticket number for the activation --ticket-system string Ticket system for the activation -v, --validate-only Send the request to the validation endpoint of Azure PIM, without requesting the activation

Groups

Activate groups

:warning: Requires an access token with the appropriate scope. See Token for Entra ID Groups for more details.

$ az-pim-cli activate group --help Sends a request to Azure PIM to activate the given group Usage: az-pim-cli activate group [flags] Aliases: group, g, grp, groups Flags: -h, --help help for group -t, --token string An access token for the PIM 'Entra Roles' and 'Groups' API (required). Consult the README for more information.

Entra roles

Activate entra roles

:warning: Requires an access token with the appropriate scope. See Token for Entra ID Groups and Roles for more details.

$ az-pim-cli activate role --help Sends a request to Azure PIM to activate the given Entra role Usage: az-pim-cli activate role [flags] Aliases: role, rl, role, roles Flags: -h, --help help for role -t, --token string An access token for the PIM 'Entra Roles' and 'Groups' API (required). Consult the README for more information.

Examples

Azure resources

# List eligible Azure resource role assignments
$ az-pim-cli list resources
== S100-Example-Subscription ==
         - Contributor
         - Owner
== S1337-Another-Subscription ==
         - Contributor
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=S100-Example-Subscription 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=S100-Example-Subscription 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=S100-Example-Subscription 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=S100-Example-Subscription 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=S100-Example-Subscription 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=S100-Example-Subscription 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=S100-Example-Subscription 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=S100-Example-Subscription 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=S100-Example-Subscription 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=S100-Example-Subscription status=Provisioned

Groups

# List eligible group assignments
$ az-pim-cli list groups
== my-entra-id-group ==
         - Owner
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

# List eligible Entra role assignments
$ az-pim-cli list roles
== my-entra-id-role ==
         - Owner
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

token: The Bearer token to use for authorization when requesting the Azure PIM Groups endpoint, i.e. listing/activating Azure PIM Groups and Entra Roles

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
token: eyJ0[...]
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_TOKEN=eyJ0[...]
export PIM_CLOUD=global

Token for Entra ID Groups and Roles

Due to limitations with authorization for Azure PIM, this software may only acquire a token authorized for listing and activating 'Azure resources' roles. In order to list or activate 'Entra groups' and 'Entra roles', you must acquire a token from an authenticated browser session. This token will have a limited lifetime, which means you'll likely have to perform this step each time you wish to activate or list Entra groups.

To acquire the token, do the following:

Navigate to 'Microsoft Entra Privileged Identity Management > Activate > Groups' or 'Microsoft Entra Privileged Identity Management > Activate > Microsoft Entra roles'
Open DevTools (CTRL+Shift+I), and locate a request to https://api.azrbac.mspim.azure.com/api/v2/privilegedAccess/aadGroups/roleAssignments or https://api.azrbac.mspim.azure.com/api/v2/privilegedAccess/aadroles/roleAssignments
- If no such request can be seen, press the "Refresh" button above the table to issue a new request
- In DevTools, the "File" attribute should start with "roleAssignments"
In DevTools, under the "Headers" tab for the given request, copy the value of the Authorization header, which should start with "Bearer eyJ0[...]"
Remove the prefix "Bearer" from the value, resulting in "eyJ0[...]"
Set an environment variable or config file value according to the description in Configuration options, e.g.

PIM_TOKEN=eyJ0[...]

You may now, and for the duration of the token's lifetime, list and activate 'Entra groups' and 'Entra roles' using this tool

Troubleshooting

To ease the process of troubleshooting, you can add the flag --debug to enable debug logging.

:warning: 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

NAME

SYNOPSIS

INFO

DESCRIPTION

README

Azure PIM CLI

Install

Install with go install

Clone and build yourself

Navigate into the repo directory and build

Move the az-pim-cli binary into your path

Configuration

Prerequisites

Usage

List eligible role assignments

Azure resources

Groups

Entra roles

Activate a role

Azure resources

Groups

Entra roles

Examples

Azure resources

Activate the first matching role for a resource with the prefix 'S100'

Activate a specific role ('Owner') for a resource with the prefix 's100'

Activate a resource role and specify a ticket number for the activation

Activate a resource role and specify the start time for the activation. Uses the local timezone.

Activate a resource role and specify the start time and start date for the activation. Uses the local timezone.

Groups

Activate the first matching role for the group 'my-entra-id-group'

Entra roles

Activate the first matching role for the Entra role 'my-entra-id-role'

Configuration options

YAML file

Environment variables

Token for Entra ID Groups and Roles

Troubleshooting

Testing

Contributing

SEE ALSO

Install with `go install`