INTEGRITY Dokumentace

← Cloudflare Fundamentals / fundamentals / api / how-to

Vytváření tokenů přes API

Nové API tokeny můžete generovat za běhu přímo přes API. Než to půjde, musíte v Cloudflare dashboardu vytvořit API token, který umí vytvářet další tokeny.

Generování počátečního tokenu

Než začnete používat API, musíte vygenerovat počáteční token prostřednictvím dashboardu Cloudflare. Potřebné oprávnění závisí na dané operaci API. Chcete-li uživatelům udělit přístup k účtu jako členům, vytvořte token s Účet > Nastavení účtu > Úprava. Chcete-li vytvořit API tokeny vlastněné účtem, vytvořte token s Účet > API tokeny účtu > Úprava. Chcete-li vytvořit API tokeny vlastněné uživatelem, použijte Vytvoření dalších tokenů šablona.

Doporučení

Při použití Vytvoření dalších tokenů šablony Cloudflare důrazně doporučuje, abyste tokenu neudělovali žádná další oprávnění. Nový token pečlivě chraňte, protože jím lze vytvářet tokeny s přístupem ke kterýmkoli prostředkům uživatele.

Cloudflare také doporučuje omezit použití tokenu filtrováním podle IP adresy klienta nebo pomocí TTL, aby se snížilo riziko zneužití v případě prozrazení tokenu. Přečtěte si Omezení použití tokenu s dalšími informacemi.

Vytváření API tokenů pomocí API

Pro použití s API si můžete vytvořit token vlastněný uživatelem nebo token vlastněný účtem. Viz token vlastněný uživatelem nebo token ve vlastnictví účtu Další informace najdete v dokumentaci schématu API.

Chcete-li vytvořit token:

  1. Definujte zásadu.
  2. Definujte omezení.
  3. Vytvořte token.

1. Definujte zásadu Access

Zásada Access definuje, na které prostředky může token působit a jaká oprávnění k nim má. Tento postup je podobný tomu, jak vytvořit tokeny v Cloudflare dashboardu.

Každý token může obsahovat více politik.

[
	{
		"id": "f267e341f3dd4697bd3b9f71dd96247f",
		"effect": "allow",
		"resources": {
			"com.cloudflare.api.account.zone.eb78d65290b24279ba6f44721b3ea3c4": "*",
			"com.cloudflare.api.account.zone.22b1de5f1c0e4b3ea97bb1e963b06a43": "*"
		},
		"permission_groups": [
			{
				"id": "c8fed203ed3043cba015a93ad1616f1f",
				"name": "Zone Read"
			},
			{
				"id": "82e64a83756745bbbb1c9c2701bf816b",
				"name": "DNS Read"
			}
		]
	}
]
Pole Popis
id Jedinečný identifikátor zásady pouze pro čtení, který se vygeneruje po jejím vytvoření.
effect Určuje, zda tato zásada přístup povoluje, nebo zamítá. Pokud vytváříte pouze jednu zásadu, použijte allow. Pořadí vyhodnocování zásad je následující: 1. Explicitní DENY Zásady; 2. Explicitní ALLOW Zásady; 3. Implicitní DENY ALL.
resources Definuje, které prostředky lze konfigurovat.
permission_groups Definuje, jaká oprávnění zásada uděluje zahrnutým prostředkům.

Zdroje

Zásady API tokenů podporují tři typy prostředků: User, Account, a Zone.

Účet

Do zásady tokenu zahrňte jeden účet, nebo všechny účty.

Zóna

Zahrňte jedna zóna, všechny zóny v účtu, nebo všechny zóny ve všech účtech v zásadě tokenu.

Uživatel

U uživatelských prostředků můžete odkazovat pouze sami na sebe, což se označuje takto:"com.cloudflare.api.user.<USER_TAG>": "*"

Skupiny oprávnění

Přidejte do tokenu API skupiny oprávnění zadáním jejich id hodnot. Doporučujeme použít id jako klíč pro interakci s API Cloudflare; oprávnění name je pouze kosmetické a může se změnit. Skupiny oprávnění jsou vázané na konkrétní prostředky (uživatel, účet nebo zóna), takže skupina oprávnění v zásadě se uplatní jen na typ prostředku, ke kterému je vázaná.

Chcete-li načíst všechny dostupné skupiny oprávnění a jejich ID, použijte Seznam skupin oprávnění koncový bod:

Požadovaná oprávnění API tokenu

Alespoň jeden z následujících oprávnění tokenu je povinné:
List Token Permission Groups
curl "https://api.cloudflare.com/client/v4/user/tokens/permission_groups" \
	--request GET \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
{
  "result": [
    {
      "id": "19637fbb73d242c0a92845d8db0b95b1",
      "name": "AI Crawl Control Read",
      "description": "Grants access to reading AI Crawl Control",
      "scopes": [
        "com.cloudflare.api.account.zone"
      ]
    },
    {
      "id": "1ba6ab4cacdb454b913bbb93e1b8cb8c",
      "name": "AI Crawl Control Write",
      "description": "Grants access to reading and editing AI Crawl Control",
      "scopes": [
        "com.cloudflare.api.account.zone"
      ]
    },
    // (...)
	]
}

2. Definujte omezení

Nastavte případná omezení použití tokenu. Tokeny API umožňují omezit přístup podle IP adresy klienta a nastavit TTL. Více informací najdete v Omezení použití tokenu s dalšími informacemi.

Při definování TTL můžete nastavit čas, kdy se token stane aktivním, pomocí not_before a čas jeho vypršení s expires_on. Obě tato pole přijímají časová razítka UTC v následujícím formátu: "2018-07-01T05:20:00Z".

Omezte používání tokenu pomocí filtrů IP adres klienta v následujícím objektu:

{
	"request.ip": {
		"in": ["199.27.128.0/21", "2400:cb00::/32"],
		"not_in": ["199.27.128.0/21", "2400:cb00::/32"]
	}
}

Každý parametr v in a not_in objekty musí být ve formátu CIDR. Použijte například 192.168.0.1/32 pro zadání jedné IP adresy.

3. Vytvořte token

Zkombinujte předchozí informace a vytvořte token podle následujícího příkladu:

curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/tokens" \
--header "Authorization: Bearer <API_TOKEN>" \
--header "Content-Type: application/json" \
--data '{
  "name": "readonly token",
  "policies": [
    {
      "effect": "allow",
      "resources": {
        "com.cloudflare.api.account.zone.eb78d65290b24279ba6f44721b3ea3c4": "*",
        "com.cloudflare.api.account.zone.22b1de5f1c0e4b3ea97bb1e963b06a43": "*"
      },
      "permission_groups": [
        {
          "id": "c8fed203ed3043cba015a93ad1616f1f",
          "name": "Zone Read"
        },
        {
          "id": "82e64a83756745bbbb1c9c2701bf816b",
          "name": "DNS Read"
        }
      ]
    }
  ],
  "not_before": "2020-04-01T05:20:00Z",
  "expires_on": "2020-04-10T00:00:00Z",
  "condition": {
    "request.ip": {
      "in": [
        "199.27.128.0/21",
        "2400:cb00::/32"
      ],
      "not_in": [
        "199.27.128.1/32"
      ]
    }
  }
}'
curl "https://api.cloudflare.com/client/v4/user/tokens" \
--header "Authorization: Bearer <API_TOKEN>" \
--header "Content-Type: application/json" \
--data '{
  "name": "readonly token",
  "policies": [
    {
      "effect": "allow",
      "resources": {
        "com.cloudflare.api.account.zone.eb78d65290b24279ba6f44721b3ea3c4": "*",
        "com.cloudflare.api.account.zone.22b1de5f1c0e4b3ea97bb1e963b06a43": "*"
      },
      "permission_groups": [
        {
          "id": "c8fed203ed3043cba015a93ad1616f1f",
          "name": "Zone Read"
        },
        {
          "id": "82e64a83756745bbbb1c9c2701bf816b",
          "name": "DNS Read"
        }
      ]
    }
  ],
  "not_before": "2020-04-01T05:20:00Z",
  "expires_on": "2020-04-10T00:00:00Z",
  "condition": {
    "request.ip": {
      "in": [
        "199.27.128.0/21",
        "2400:cb00::/32"
      ],
      "not_in": [
        "199.27.128.1/32"
      ]
    }
  }
}'
curl "https://api.cloudflare.com/client/v4/user/tokens" \
--header "Authorization: Bearer <API_TOKEN>" \
--header "Content-Type: application/json" \
--data '{
  "name": "readonly token",
  "policies": [
    {
      "effect": "allow",
      "resources": {
        "com.cloudflare.api.account.zone.eb78d65290b24279ba6f44721b3ea3c4": "*",
        "com.cloudflare.api.account.zone.22b1de5f1c0e4b3ea97bb1e963b06a43": "*"
      },
      "permission_groups": [
        {
          "id": "c8fed203ed3043cba015a93ad1616f1f",
          "name": "Zone Read"
        },
        {
          "id": "82e64a83756745bbbb1c9c2701bf816b",
          "name": "DNS Read"
        }
      ]
    }
  ],
  "not_before": "2020-04-01T05:20:00Z",
  "expires_on": "2020-04-10T00:00:00Z",
  "condition": {
    "request.ip": {
      "in": [
        "199.27.128.0/21",
        "2400:cb00::/32"
      ],
      "not_in": [
        "199.27.128.1/32"
      ]
    }
  }
}'