Update Azure Secrets docs (#5554)
Add coverage of application_object_id parameter.
This commit is contained in:
Jim Kalafut
GitHub
parent
c8015b5fa9
commit
c1d435c80c
|
|
@ -112,9 +112,10 @@ $ curl \
|
|||
|
||||
## Create/Update Role
|
||||
|
||||
Create or update a Vault role. The provided Azure roles must exist
|
||||
for this call to succeed. See the Azure secrets [roles docs][roles]
|
||||
for more information about roles.
|
||||
Create or update a Vault role. Either `application_object_id` or
|
||||
`azure_roles` must be provided, and these resources must exist for this
|
||||
call to succeed. See the Azure secrets [roles docs][roles] for more
|
||||
information about roles.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :------------------------| :------------------------ |
|
||||
|
|
@ -123,9 +124,12 @@ for more information about roles.
|
|||
|
||||
### Parameters
|
||||
|
||||
- `azure_roles` (`string: <required>`) - List of Azure roles to be assigned to the generated service
|
||||
- `azure_roles` (`string: ""`) - List of Azure roles to be assigned to the generated service
|
||||
principal. The array must be in JSON format, properly escaped as a string. See [roles docs][roles]
|
||||
for details on role definition.
|
||||
- `application_object_id` (`string: ""`) - Application Object ID for an existing service principal that will
|
||||
be used instead of creating dynamic service principals. If present, `azure_roles` will be ignored. See
|
||||
[roles docs][roles] for details on role definition.
|
||||
- `ttl` (`string: ""`) – Specifies the default TTL for service principals generated using this role.
|
||||
Accepts time suffixed strings ("1h") or an integer number of seconds. Defaults to the system/engine default TTL time.
|
||||
- `max_ttl` (`string: ""`) – Specifies the maximum TTL for service principals generated using this role. Accepts time
|
||||
|
|
|
|||
|
|
@ -19,6 +19,10 @@ Each service principal is associated with a Vault lease. When the lease expires
|
|||
(either during normal revocation or through early revocation), the service
|
||||
principal is automatically deleted.
|
||||
|
||||
If an existing service principal is specified as part of the role configuration,
|
||||
a new password will be dynamically generated instead of a new service principal.
|
||||
The password will be deleted when the lease is revoked.
|
||||
|
||||
## Setup
|
||||
|
||||
Most secrets engines must be configured in advance before they can perform their
|
||||
|
|
@ -50,10 +54,16 @@ management tool.
|
|||
If you are running Vault inside an Azure VM with MSI enabled, `client_id` and
|
||||
`client_secret` may be omitted. For more information on authentication, see the [authentication](#authentication) section below.
|
||||
|
||||
1. Configure a role. Roles determine the permissions that the service principal
|
||||
generated by Vault will have to Azure resources.
|
||||
1. Configure a role. A role may be set up with either an existing service principal, or
|
||||
a set of Azure roles that will be assigned to a dynamically created service principal.
|
||||
|
||||
To configure a role called "my-role":
|
||||
To configure a role called "my-role" with an existing service principal:
|
||||
|
||||
```text
|
||||
$ vault write azure/roles/my-role application_object_id=<existing_app_obj_id> ttl=1h
|
||||
```
|
||||
|
||||
Alternatively, to configure the role to create a new service principal with Azure roles:
|
||||
|
||||
```text
|
||||
$ vault write azure/roles/my-role ttl=1h azure_roles=-<<EOF
|
||||
|
|
@ -66,14 +76,15 @@ generated by Vault will have to Azure resources.
|
|||
EOF
|
||||
```
|
||||
|
||||
Roles may also have their own TTL configuration that is separate from the mount's
|
||||
TTL. For more information on roles see the [roles](#roles) section below.
|
||||
Roles may also have their own TTL configuration that is separate from the mount's
|
||||
TTL. For more information on roles see the [roles](#roles) section below.
|
||||
|
||||
|
||||
## Usage
|
||||
|
||||
After the secrets engine is configured and a user/machine has a Vault token with
|
||||
the proper permissions, it can generate credentials.
|
||||
the proper permissions, it can generate credentials. The usage pattern is the same
|
||||
whether an existing or dynamic service principal is used.
|
||||
|
||||
To generate a credential using the "my-role" role:
|
||||
|
||||
|
|
@ -89,18 +100,26 @@ client_id 408bf248-dd4e-4be5-919a-7f6207a307ab
|
|||
client_secret ad06228a-2db9-4e0a-8a5d-e047c7f32594
|
||||
```
|
||||
|
||||
This endpoint generates a renewable service principal. The application can login
|
||||
using the `client_id`/`client_secret` and will have access provided by the Azure roles set in
|
||||
the "my-role" configuration.
|
||||
This endpoint generates a renewable set of credentials. The application can login
|
||||
using the `client_id`/`client_secret` and will have access provided by configured service
|
||||
principal or the Azure roles set in the "my-role" configuration.
|
||||
|
||||
|
||||
## Roles
|
||||
|
||||
Vault roles let you configure mapped Azure roles and role-specific TTL parameters. One or more Azure
|
||||
roles will be assigned to a newly created service principal. The Vault role may optionally specify role-specific `ttl` and/or `max_ttl` values. When the lease is created, the
|
||||
more restrictive of the mount or role TTL value will be used.
|
||||
Vault roles let you configure either an existing service principal or a set of Azure roles, along with
|
||||
role-specific TTL parameters. If an existing service principal is not provided, the configured Azure
|
||||
roles will be assigned to a newly created service principal. The Vault role may optionally specify
|
||||
role-specific `ttl` and/or `max_ttl` values. When the lease is created, the more restrictive of the
|
||||
mount or role TTL value will be used.
|
||||
|
||||
### Application Object IDs
|
||||
If an existing service principal is to be used, the Application Object ID must be set on the Vault role.
|
||||
This ID can be found by inspecting the desired Application with the `az` CLI tool, or via the Azure Portal. Note
|
||||
that the Application **Object** ID must be provided, not the Application ID.
|
||||
|
||||
### Azure Roles
|
||||
If dynamic service principals are used, Azure roles must be configured on the Vault role.
|
||||
Azure roles are provided as a JSON list, with each element describing an Azure role and scope to be assigned.
|
||||
Azure roles may be specified using the `role_name` parameter ("Owner"), or `role_id`
|
||||
("/subscriptions/.../roleDefinitions/...").
|
||||
|
|
@ -153,6 +172,27 @@ The following Azure roles and Azure Active Directory (AAD) permissions are requi
|
|||
|
||||
These permissions can be configured through the Azure Portal, CLI tool, or PowerShell.
|
||||
|
||||
## Choosing between dynamic or existing service principals
|
||||
|
||||
Dynamic service principals are preferred if the desired Azure resources can be provided
|
||||
via the RBAC system and Azure roles defined in the Vault role. This form of credential is
|
||||
completely decoupled from any other clients, is not subject to permission changes after
|
||||
issuance, and offers the best audit granularity.
|
||||
|
||||
Access to some Azure services cannot be provided with the RBAC system, however. In these
|
||||
cases, an existing service principal can be set up with the necessary access, and Vault
|
||||
can create new passwords for this service principal. Any changes to the service principal
|
||||
permissions affect all clients. Furthermore, Azure does not provide any logging with
|
||||
regard to _which_ credential was used for an operation.
|
||||
|
||||
An important limitation when using an existing service princicpal is that Azure limits the
|
||||
number of passwords for a single Application. This limit is based on Application object
|
||||
size and isn't firmly specified, but in practice hundreds of passwords can be issued per
|
||||
Application. An error will be returned if the object size is reached. This limit can be
|
||||
managed by reducing the role TTL, or by creating another Vault role against a different
|
||||
Azure service principal configured with the same permissions.
|
||||
|
||||
|
||||
## Additional Notes
|
||||
|
||||
- **If a referenced Azure role doesn't exist, a credential will not be generated.**
|
||||
|
|
@ -171,8 +211,10 @@ These permissions can be configured through the Azure Portal, CLI tool, or Power
|
|||
- Service principal credential timeouts are not used. Vault will revoke access by
|
||||
deleting the service principal.
|
||||
|
||||
- The Application Name for the service principal will be prefixed with `vault-`. This may
|
||||
be used to search for Vault-created credentials using other tools or the Portal.
|
||||
- The Application Name for dynamic service principals will be prefixed with `vault-`. Similarly
|
||||
the `keyId` of any passwords added to an existing service principal will begin with
|
||||
`ffffff`. These may be used to search for Vault-created credentials using the `az` tool
|
||||
or Portal.
|
||||
|
||||
## Help & Support
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue