Alibaba auth docs (#5132)
This commit is contained in:
Becca Petrin
GitHub
parent
afc84286b9
commit
fb6a06a3fe
|
|
@ -0,0 +1,226 @@
|
|||
---
|
||||
layout: "api"
|
||||
page_title: "AliCloud - Auth Methods - HTTP API"
|
||||
sidebar_current: "docs-http-auth-alicloud"
|
||||
description: |-
|
||||
This is the API documentation for the Vault AliCloud auth method.
|
||||
---
|
||||
|
||||
# AliCloud Auth Method (API)
|
||||
|
||||
This is the API documentation for the Vault AliCloud auth method. For
|
||||
general information about the usage and operation of the AliCloud method, please
|
||||
see the [Vault AliCloud auth method documentation](/docs/auth/alicloud.html).
|
||||
|
||||
This documentation assumes the AliCloud auth method is mounted at the `/auth/alicloud`
|
||||
path in Vault. Since it is possible to enable auth methods at any location,
|
||||
please update your API calls accordingly.
|
||||
|
||||
## Create Role
|
||||
|
||||
Registers a role. Only entities using the role registered using this endpoint
|
||||
will be able to perform the login operation.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :------------------------------- | :--------------------- |
|
||||
| `POST` | `/auth/alicloud/role/:role` | `204 (empty body)` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `role` `(string: <required>)` - Name of the role. Must correspond with the name of the role reflected in the arn.
|
||||
- `arn` `(string: <required>)` - The role's arn.
|
||||
- `policies` `(array: [])` - Policies to be set on tokens issued using this
|
||||
role.
|
||||
- `ttl` `(string: "")` - The TTL period of tokens issued using this role,
|
||||
provided as "1h", where hour is the largest suffix.
|
||||
- `max_ttl` `(string: "")` - The maximum allowed lifetime of tokens issued using
|
||||
this role.
|
||||
- `period` `(string: "")` - If set, indicates that the token generated using
|
||||
this role should never expire. The token should be renewed within the duration
|
||||
specified by this value. At each renewal, the token's TTL will be set to the
|
||||
value of this parameter.
|
||||
- `bound_cidrs` `(string: "", or list: [])` – If set, restricts usage of the
|
||||
roles to client IPs falling within the range of the specified CIDR(s).
|
||||
|
||||
### Sample Payload
|
||||
|
||||
```json
|
||||
{
|
||||
"arn": "acs:ram::5138828231865461:role/dev-role",
|
||||
"policies": [
|
||||
"dev",
|
||||
"prod"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
--request POST \
|
||||
--data @payload.json \
|
||||
http://127.0.0.1:8200/v1/auth/alicloud/role/dev-role
|
||||
```
|
||||
|
||||
## Read Role
|
||||
|
||||
Returns the previously registered role configuration.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :--------------------------- | :--------------------- |
|
||||
| `GET` | `/auth/alicloud/role/:role` | `200 application/json` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `role` `(string: <required>)` - Name of the role.
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
http://127.0.0.1:8200/v1/auth/alicloud/role/dev-role
|
||||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
```json
|
||||
{
|
||||
"data": {
|
||||
"arn": "acs:ram::5138828231865461:role/dev-role",
|
||||
"policies": [
|
||||
"default",
|
||||
"dev",
|
||||
"prod"
|
||||
],
|
||||
"ttl": 1800000,
|
||||
"max_ttl": 1800000,
|
||||
"period": 0
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## List Roles
|
||||
|
||||
Lists all the roles that are registered with the method.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :--------------------------- | :--------------------- |
|
||||
| `LIST` | `/auth/alicloud/roles` | `200 application/json` |
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
--request LIST \
|
||||
http://127.0.0.1:8200/v1/auth/alicloud/roles
|
||||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
```json
|
||||
{
|
||||
"data": {
|
||||
"keys": [
|
||||
"dev-role",
|
||||
"prod-role"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Delete Role
|
||||
|
||||
Deletes the previously registered role.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :------------------------------- | :--------------------- |
|
||||
| `DELETE` | `/auth/alicloud/role/:role` | `204 (empty body)` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `role` `(string: <required>)` - Name of the role.
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
--request DELETE \
|
||||
http://127.0.0.1:8200/v1/auth/alicloud/role/dev-role
|
||||
```
|
||||
|
||||
## Login
|
||||
|
||||
Fetch a token. This endpoint verifies the signature of the signed
|
||||
GetCallerIdentity request.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :--------------------------- | :--------------------- |
|
||||
| `POST` | `/auth/alicloud/login` | `200 application/json` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `role` `(string: <required>)` - Name of the role.
|
||||
- `identity_request_url` `(string: <required>)` - Base64-encoded HTTP URL used in
|
||||
the signed request.
|
||||
- `identity_request_headers` `(string: <required>)` - Base64-encoded,
|
||||
JSON-serialized representation of the sts:GetCallerIdentity HTTP request
|
||||
headers. The JSON serialization assumes that each header key maps to either a
|
||||
string value or an array of string values (though the length of that array
|
||||
will probably only be one).
|
||||
|
||||
|
||||
### Sample Payload
|
||||
|
||||
```json
|
||||
{
|
||||
"role": "dev-role",
|
||||
"identity_request_url": "aWRlbnRpdHlabrVxdWVzdF91cmw=",
|
||||
"identity_request_headers": "aWRlimRpdHlfcmVxdWVzdF9oZWFkZXJz"
|
||||
}
|
||||
```
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
--request POST \
|
||||
--data @payload.json \
|
||||
http://127.0.0.1:8200/v1/auth/alicloud/login
|
||||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
```json
|
||||
{
|
||||
"auth": {
|
||||
"renewable": true,
|
||||
"lease_duration": 1800000,
|
||||
"metadata": {
|
||||
"role_tag_max_ttl": "0",
|
||||
"instance_id": "i-de0f1344",
|
||||
"ami_id": "ami-fce36983",
|
||||
"role": "dev-role",
|
||||
"auth_type": "ec2",
|
||||
"account_id": "5138828231865461",
|
||||
"user_id": "216959339000654321",
|
||||
"role_id": "4657-abcd",
|
||||
"arn": "acs:ram::5138828231865461:assumed-role/dev-role/vm-ram-i-rj978rorvlg76urhqh7q",
|
||||
"identity_type": "assumed-role",
|
||||
"principal_id": "vm-ram-i-rj978rorvlg76urhqh7q",
|
||||
"request_id": "D6E46F10-F26C-4AA0-BB69-FE2743D9AE62",
|
||||
"role_name": "dev-role"
|
||||
},
|
||||
"policies": [
|
||||
"default",
|
||||
"dev"
|
||||
],
|
||||
"accessor": "20b89871-e6f2-1160-fb29-31c2f6d4645e",
|
||||
"client_token": "c9368254-3f21-aded-8a6f-7c818e81b17a"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
|
@ -0,0 +1,112 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "AliCloud - Auth Methods"
|
||||
sidebar_current: "docs-auth-alicloud"
|
||||
description: |-
|
||||
The AliCloud auth method allows automated authentication of AliCloud entities.
|
||||
---
|
||||
|
||||
# AliCloud Auth Method
|
||||
|
||||
The `alicloud` auth method provides an automated mechanism to retrieve
|
||||
a Vault token for AliCloud entities. Unlike most Vault auth methods, this
|
||||
method does not require manual first-deploying, or provisioning
|
||||
security-sensitive credentials (tokens, username/password, client certificates,
|
||||
etc), by operators. It treats AliCloud as a Trusted Third Party and uses a
|
||||
special AliCloud request signed with private credentials. A variety of credentials
|
||||
can be used to construct the request, but AliCloud offers
|
||||
[instance metadata](https://www.alibabacloud.com/help/faq-detail/49122.htm)
|
||||
that's ideally suited for the purpose. By launching an instance with a role,
|
||||
the role's STS credentials under instance metadata can be used to securely
|
||||
build the request.
|
||||
|
||||
## Authentication Workflow
|
||||
|
||||
The AliCloud STS API includes a method,
|
||||
[`sts:GetCallerIdentity`](https://www.alibabacloud.com/help/doc-detail/43767.htm),
|
||||
which allows you to validate the identity of a client. The client signs
|
||||
a `GetCallerIdentity` query using the [AliCloud signature
|
||||
algorithm](https://www.alibabacloud.com/help/doc-detail/67332.htm). It then
|
||||
submits 2 pieces of information to the Vault server to recreate a valid signed
|
||||
request: the request URL, and the request headers. The Vault server then
|
||||
reconstructs the query and forwards it on to the AliCloud STS service and validates
|
||||
the result back.
|
||||
|
||||
Importantly, the credentials used to sign the GetCallerIdentity request can come
|
||||
from the ECS instance metadata service for an ECS instance, which obviates the
|
||||
need for an operator to manually provision some sort of identity material first.
|
||||
However, the credentials can, in principle, come from anywhere, not just from
|
||||
the locations AliCloud has provided for you.
|
||||
|
||||
Each signed AliCloud request includes the current timestamp and a nonce to mitigate
|
||||
the risk of replay attacks.
|
||||
|
||||
It's also important to note that AliCloud does NOT include any sort
|
||||
of authorization around calls to `GetCallerIdentity`. For example, if you have
|
||||
a RAM policy on your credential that requires all access to be MFA authenticated,
|
||||
non-MFA authenticated credentials will still be able to authenticate to Vault
|
||||
using this method. It does not appear possible to enforce a RAM principal to be
|
||||
MFA authenticated while authenticating to Vault.
|
||||
|
||||
## Authorization Workflow
|
||||
|
||||
The basic mechanism of operation is per-role.
|
||||
|
||||
Roles are associated with a role ARN that has been pre-created in AliCloud.
|
||||
AliCloud's console displays each role's ARN. A role in Vault has a 1:1 relationship
|
||||
with a role in AliCloud, and must bear the same name.
|
||||
|
||||
When a client assumes that role and sends its `GetCallerIdentity` request to Vault,
|
||||
Vault matches the arn of its assumed role with that of a pre-created role in Vault.
|
||||
It then checks what policies have been associated with the role, and grants a
|
||||
token accordingly.
|
||||
|
||||
## Authentication
|
||||
|
||||
### Via the CLI
|
||||
|
||||
#### Enable AliCloud authentication in Vault.
|
||||
|
||||
```
|
||||
$ vault auth enable alicloud
|
||||
```
|
||||
|
||||
#### Configure the policies on the role.
|
||||
|
||||
```
|
||||
$ vault write auth/alicloud/role/dev-role arn='acs:ram::5138828231865461:role/dev-role'
|
||||
```
|
||||
|
||||
#### Perform the login operation
|
||||
|
||||
```
|
||||
$ vault write auth/alicloud/login \
|
||||
role=dev-role \
|
||||
identity_request_url=$IDENTITY_REQUEST_URL_BASE_64 \
|
||||
identity_request_headers=$IDENTITY_REQUEST_HEADERS_BASE_64
|
||||
```
|
||||
|
||||
For the RAM auth method, generating the signed request is a non-standard
|
||||
operation. The Vault CLI supports generating this for you:
|
||||
|
||||
```
|
||||
$ vault login -method=alicloud access_key=... secret_key=... security_token=... region=...
|
||||
```
|
||||
|
||||
This assumes you have the AliCloud credentials you would find on an ECS instance using the
|
||||
following call:
|
||||
```
|
||||
curl 'http://100.100.100.200/latest/meta-data/ram/security-credentials/$ROLE_NAME'
|
||||
```
|
||||
Please note the `$ROLE_NAME` above is case-sensitive and must be consistent with how it's reflected
|
||||
on the instance.
|
||||
|
||||
An example of how to generate the required request values for the `login` method
|
||||
can be found found in the
|
||||
[Vault CLI source code](https://github.com/hashicorp/vault-plugin-auth-alicloud/blob/master/tools/tools.go).
|
||||
|
||||
## API
|
||||
|
||||
The AliCloud auth method has a full HTTP API. Please see the
|
||||
[AliCloud Auth API](/api/auth/alicloud/index.html) for more
|
||||
details.
|
||||
|
|
@ -138,6 +138,9 @@
|
|||
<li<%= sidebar_current("docs-http-auth-approle") %>>
|
||||
<a href="/api/auth/approle/index.html">AppRole</a>
|
||||
</li>
|
||||
<li<%= sidebar_current("docs-http-auth-alicloud") %>>
|
||||
<a href="/api/auth/alicloud/index.html">AliCloud</a>
|
||||
</li>
|
||||
<li<%= sidebar_current("docs-http-auth-aws") %>>
|
||||
<a href="/api/auth/aws/index.html">AWS</a>
|
||||
</li>
|
||||
|
|
|
|||
|
|
@ -553,6 +553,10 @@
|
|||
<a href="/docs/auth/approle.html">AppRole</a>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-auth-alicloud") %>>
|
||||
<a href="/docs/auth/alicloud.html">AliCloud</a>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-auth-aws") %>>
|
||||
<a href="/docs/auth/aws.html">AWS</a>
|
||||
</li>
|
||||
|
|
|
|||
Loading…
Reference in New Issue