Wysyłanie żądań tokenów dostępu i kodów autoryzacji

Przeglądasz dokumentację Apigee Edge.
Otwórz dokumentację Apigee X. Informacje

W tym temacie pokażemy, jak żądać tokenów dostępu i kodów autoryzacji, konfigurować punkty końcowe OAuth 2.0 i konfigurować zasady dla każdego obsługiwanego typu uwierzytelnienia.

Przykładowy kod

Dla ułatwienia zasady i punkty końcowe opisane w tym temacie są dostępne na GitHubie w projekcie oauth-doc-examples w repozytorium Apigee api-platform-samples. Możesz wdrożyć przykładowy kod i wypróbować przykładowe żądania przedstawione w tym temacie. Więcej informacji znajdziesz w pliku README projektu.

Żądanie tokena dostępu: typ przyznania kodu autoryzacji

Z tej sekcji dowiesz się, jak poprosić o token dostępu za pomocą przepływu typu uwierzytelnienia kodu autoryzacji. Wprowadzenie do typów uwierzytelniania przez OAuth 2.0 znajdziesz we wprowadzeniu do OAuth 2.0.

Przykładowe żądanie

$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' \
   -H 'Authorization: Basic c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ' \
   -X POST 'https://docs-test.apigee.net/oauth/accesstoken' \
   -d 'code=I9dMGHAN&grant_type=authorization_code&redirect_uri=http://example-callback.com'

Parametry wymagane

Domyślnie te parametry muszą mieć wartość x-www-form-urlencoded i muszą być określone w treści żądania (jak pokazano w przykładzie powyżej). Można jednak zmienić to ustawienie domyślne, konfigurując elementy <GrantType>, <Code> i <RedirectUri> w zasadzie OAuthV2 dołączonej do tego punktu końcowego /accesstoken. Szczegółowe informacje znajdziesz w artykule Zasady OAuthV2.

  • grant_type – musi mieć wartość authorization_code.
  • code – kod autoryzacji otrzymany z punktu końcowego /authorize (lub dowolną inną nazwę). Aby zażądać tokena dostępu w ramach procesu typu uwierzytelnienia kodu autoryzacji, musisz najpierw uzyskać kod autoryzacji. Zobacz sekcję Wysyłanie żądań kodów autoryzacji poniżej. Zapoznaj się też z informacjami o implementowaniu typu uwierzytelnienia kodu autoryzacji.
  • redirect_uri – musisz podać ten parametr, jeśli parametr redirect_uri został dołączony do poprzedniego żądania kodu autoryzacji. Jeśli żądanie kodu autoryzacji nie zawiera parametru redirect_uri, a jego nie podasz, ta zasada użyje wartości adresu URL wywołania zwrotnego podanego podczas rejestrowania aplikacji dewelopera.

Parametry opcjonalne

  • state – ciąg znaków, który zostanie odesłany z odpowiedzią. Zwykle używany do zapobiegania sfałszowaniu żądania z innej witryny.
  • scope – umożliwia filtrowanie listy usług API, z którymi można używać wygenerowanego tokena. Szczegółowe informacje o zakresie znajdziesz w artykule o korzystaniu z zakresów OAuth2.

Uwierzytelnianie

Identyfikator klienta i tajny klucz klienta należy przekazać jako nagłówek uwierzytelniania podstawowego (zakodowany w formacie Base64) lub jako parametry formularza client_id i client_secret. Te wartości uzyskujesz z zarejestrowanej aplikacji dewelopera. Zobacz też „Kodowanie podstawowych danych uwierzytelniających”.

Przykładowy punkt końcowy

Oto przykładowa konfiguracja punktu końcowego umożliwiająca generowanie tokena dostępu. Zostaną uruchomione zasady GenerateAccessToken, które należy skonfigurować tak, aby obsługiwały typ uwierzytelnienia przez kod autoryzacji.

...
       <Flow name="generate-access-token">
            <Description>Generate a token</Description>
            <Request>
                <Step>
                    <Name>GenerateAccessToken</Name>
                </Step>
            </Request>
            <Response/>
            <Condition>(proxy.pathsuffix MatchesPath "/token") and (request.verb = "POST")</Condition>
        </Flow>
...

Przykładowa zasada

To jest podstawowa zasada GenerateAccessToken skonfigurowana tak, by akceptować typ uwierzytelnienia authorization_code. Informacje o opcjonalnych elementach konfiguracji, które możesz skonfigurować za pomocą tej zasady, znajdziesz w artykule Zasady OAuthV2.

<OAuthV2 name="GenerateAccessToken">
    <Operation>GenerateAccessToken</Operation>
    <ExpiresIn>1800000</ExpiresIn>
    <RefreshTokenExpiresIn>86400000</RefreshTokenExpiresIn>
    <SupportedGrantTypes>
      <GrantType>authorization_code</GrantType>
    </SupportedGrantTypes>
    <GenerateResponse enabled="true"/>
</OAuthV2>

Zwroty

Gdy włączona jest zasada <GenerateResponse>, zasada zwraca odpowiedź JSON zawierającą token dostępu, jak pokazano poniżej. Typ uwierzytelnienia authorization_code tworzy token dostępu i tokeny odświeżania, więc odpowiedź może wyglądać tak:

{
    "issued_at": "1420262924658",
    "scope": "READ",
    "application_name": "ce1e94a2-9c3e-42fa-a2c6-1ee01815476b",
    "refresh_token_issued_at": "1420262924658",
    "status": "approved",
    "refresh_token_status": "approved",
    "api_product_list": "[PremiumWeatherAPI]",
    "expires_in": "1799", //--in seconds
    "developer.email": "tesla@weathersample.com",
    "organization_id": "0",
    "token_type": "BearerToken",
    "refresh_token": "fYACGW7OCPtCNDEnRSnqFlEgogboFPMm",
    "client_id": "5jUAdGv9pBouF0wOH5keAVI35GBtx3dT",
    "access_token": "2l4IQtZXbn5WBJdL6EF7uenOWRsi",
    "organization_name": "docs",
    "refresh_token_expires_in": "86399", //--in seconds
    "refresh_count": "0"
}

Jeśli <GenerateResponse> ma wartość Fałsz, zasada nie zwraca odpowiedzi. Zamiast tego wypełnia poniższy zestaw zmiennych przepływu danymi związanymi z przydzielonym tokenem dostępu.

oauthv2accesstoken.{policy-name}.access_token
oauthv2accesstoken.{policy-name}.expires_in //--in seconds
oauthv2accesstoken.{policy-name}.refresh_token
oauthv2accesstoken.{policy-name}.refresh_token_expires_in //--in seconds
oauthv2accesstoken.{policy-name}.refresh_token_issued_at
oauthv2accesstoken.{policy-name}.refresh_token_status

Na przykład:

oauthv2accesstoken.GenerateAccessToken.access_token
oauthv2accesstoken.GenerateAccessToken.expires_in
oauthv2accesstoken.GenerateAccessToken.refresh_token
oauthv2accesstoken.GenerateAccessToken.refresh_token_expires_in
oauthv2accesstoken.GenerateAccessToken.refresh_token_issued_at
oauthv2accesstoken.GenerateAccessToken.refresh_token_status

Żądanie tokena dostępu: typ przyznania danych logowania klienta

Z tej sekcji dowiesz się, jak poprosić o token dostępu za pomocą przepływu typu uwierzytelnienia danych logowania klienta. Wprowadzenie do typów uwierzytelniania przez OAuth 2.0 znajdziesz we wprowadzeniu do OAuth 2.0.

Przykładowe żądanie

Informacje o kodowaniu nagłówka podstawowego uwierzytelniania w poniższym wywołaniu znajdziesz w sekcji „Kodowanie podstawowych danych uwierzytelniających”. 

$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Authorization: Basic c3FIOG9vSGV4VHoAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ' \
  -X POST 'https://docs-test.apigee.net/oauth/accesstoken' \
  -d 'grant_type=client_credentials'

Parametry wymagane

Domyślnie wymagany parametr grant_type musi mieć wartość x-www-form-urlencoded i być określony w treści żądania (jak pokazano w przykładzie powyżej). Można jednak zmienić to ustawienie, konfigurując element <GrantType> w zasadzie OAuthV2 dołączonej do tego punktu końcowego /accesstoken. Możesz na przykład przekazać ten parametr w parametrze zapytania. Szczegółowe informacje znajdziesz w artykule Zasady OAuthV2.

  • grant_type – musi mieć wartość client_credentials.

Parametry opcjonalne

  • state – ciąg znaków, który zostanie odesłany z odpowiedzią. Zwykle używany do zapobiegania sfałszowaniu żądania z innej witryny.
  • scope – umożliwia filtrowanie listy usług API, z którymi można używać wygenerowanego tokena. Szczegółowe informacje o zakresie znajdziesz w artykule o korzystaniu z zakresów OAuth2.

Uwierzytelnianie

Identyfikator klienta i tajny klucz klienta należy przekazać jako nagłówek uwierzytelniania podstawowego (zakodowany w formacie Base64) lub jako parametry formularza client_id i client_secret. Te wartości uzyskujesz z rejestrowanej aplikacji dewelopera powiązanej z żądaniem. Zobacz też „Kodowanie podstawowych danych uwierzytelniających”.

Przykładowy punkt końcowy

Oto przykładowa konfiguracja punktu końcowego umożliwiająca generowanie tokena dostępu. Zostaną uruchomione zasady GenerateAccessToken, które należy skonfigurować tak, aby obsługiwały typ przyznania client_credentials.

...
       <Flow name="generate-access-token">
            <Request>
                <Step>
                    <Name>GenerateAccessToken</Name>
                </Step>
            </Request>
            <Response/>
            <Condition>(proxy.pathsuffix MatchesPath "/token") and (request.verb = "POST")</Condition>
        </Flow>
...

Przykładowa zasada

To jest podstawowa zasada GenerateAccessToken skonfigurowana tak, by akceptować typ uwierzytelnienia client_credentials. Informacje o opcjonalnych elementach konfiguracji, które możesz skonfigurować za pomocą tej zasady, znajdziesz w artykule Zasady OAuthV2.

<OAuthV2 name="GenerateAccessToken">
    <Operation>GenerateAccessToken</Operation>
    <ExpiresIn>1800000</ExpiresIn> <!-- 30 minutes -->
    <SupportedGrantTypes>
      <GrantType>client_credentials</GrantType>
    </SupportedGrantTypes>
    <GenerateResponse enabled="true"/>
</OAuthV2>

Zwroty

Gdy zasada <GenerateResponse> jest włączona, zasada zwraca odpowiedź JSON. Pamiętaj, że w przypadku typu uwierzytelnienia client_credentials tokeny odświeżania nie są obsługiwane. Generowany jest tylko token dostępu. Na przykład:

{
    "issued_at": "1420260525643",
    "application_name": "ce1e94a2-9c3e-42fa-a2c6-1ee01815476b",
    "scope": "READ",
    "status": "approved",
    "api_product_list": "[PremiumWeatherAPI]",
    "expires_in": "1799", //--in seconds
    "developer.email": "tesla@weathersample.com",
    "organization_id": "0",
    "token_type": "BearerToken",
    "client_id": "5jUAdGv9pBouF0wOH5keAVI35GBtx3dT",
    "access_token": "XkhU2DFnMGIVL2hvsRHLM00hRWav",
    "organization_name": "docs"
}

Jeśli <GenerateResponse> ma wartość Fałsz, zasada nie zwraca odpowiedzi. Zamiast tego wypełnia poniższy zestaw zmiennych przepływu danymi związanymi z przydzielonym tokenem dostępu.

oauthv2accesstoken.{policy-name}.access_token
oauthv2accesstoken.{policy-name}.expires_in //--in seconds

Na przykład:

oauthv2accesstoken.GenerateAccessToken.access_token
oauthv2accesstoken.GenerateAccessToken.expires_in     //--in seconds

Żądanie tokena dostępu: typ przyznania hasła

Z tej sekcji dowiesz się, jak poprosić o token dostępu za pomocą przepływu typu uwierzytelnienia (hasła) właściciela zasobu. Wprowadzenie do typów uwierzytelniania przez OAuth 2.0 znajdziesz w artykule Wprowadzenie do OAuth 2.0.

Więcej informacji o typie przyznawania hasła, w tym 4-minutowy film pokazujący, jak je wdrożyć, znajdziesz w artykule o implementowaniu typu przyznania hasła.

Przykładowe żądanie

Informacje o kodowaniu nagłówka podstawowego uwierzytelniania w poniższym wywołaniu znajdziesz w sekcji „Kodowanie podstawowych danych uwierzytelniających”. 

$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Authorization: Basic c3FIOG9vSGV4VHo4QzAySVg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ' \
  -X POST https://docs-test.apigee.net/oauth/token \
  -d 'grant_type=password&username=the-user-name&password=the-users-password'

Parametry wymagane

Domyślnie te parametry muszą mieć wartość x-www-form-urlencoded i muszą być określone w treści żądania (jak pokazano w przykładzie powyżej). Można jednak zmienić to ustawienie domyślne, konfigurując elementy <GrantType>, <Username> i <Password> w zasadzie OAuthV2 dołączonej do tego punktu końcowego /token. Szczegółowe informacje znajdziesz w artykule Zasady OAuthV2.

Dane logowania użytkownika są zwykle sprawdzane w ramach magazynu danych logowania przy użyciu zasady LDAP lub JavaScript.

  • grant_type – musi mieć wartość password.
  • nazwa_użytkownika – nazwa użytkownika właściciela zasobu.
  • hasło – hasło właściciela zasobu.

Parametry opcjonalne

  • state – ciąg znaków, który zostanie odesłany z odpowiedzią. Zwykle używany do zapobiegania sfałszowaniu żądania z innej witryny.
  • scope – umożliwia filtrowanie listy usług API, z którymi można używać wygenerowanego tokena. Szczegółowe informacje o zakresie znajdziesz w artykule o korzystaniu z zakresów OAuth2.

Uwierzytelnianie

Identyfikator klienta i tajny klucz klienta należy przekazać jako nagłówek uwierzytelniania podstawowego (zakodowany w formacie Base64) lub jako parametry formularza client_id i client_secret. Te wartości uzyskujesz z rejestrowanej aplikacji dewelopera powiązanej z żądaniem. Zobacz też „Kodowanie podstawowych danych uwierzytelniających”.

Przykładowy punkt końcowy

Oto przykładowa konfiguracja punktu końcowego umożliwiająca generowanie tokena dostępu. Zostaną uruchomione zasady GenerateAccessToken, które należy skonfigurować tak, aby obsługiwały typ przyznania hasła.

...
       <Flow name="generate-access-token">
            <Request>
                <Step>
                    <Name>GenerateAccessToken</Name>
                </Step>
            </Request>
            <Response/>
            <Condition>(proxy.pathsuffix MatchesPath "/token") and (request.verb = "POST")</Condition>
        </Flow>
...

Przykładowa zasada

To jest podstawowa zasada GenerateAccessToken skonfigurowana tak, by akceptowała typ przyznania hasła. Informacje o opcjonalnych elementach konfiguracji, które możesz skonfigurować za pomocą tej zasady, znajdziesz w artykule Zasady OAuthV2.

<OAuthV2 name="GenerateAccessToken">
    <Operation>GenerateAccessToken</Operation>
    <ExpiresIn>1800000</ExpiresIn> <!-- 30 minutes -->
    <RefreshTokenExpiresIn>28800000</RefreshTokenExpiresIn> <!-- 8 hours -->
    <SupportedGrantTypes>
      <GrantType>password</GrantType>
    </SupportedGrantTypes>
    <GenerateResponse enabled="true"/>
</OAuthV2>

Zwroty

Gdy zasada <GenerateResponse> jest włączona, zasada zwraca odpowiedź JSON. Pamiętaj, że w przypadku typu uwierzytelnienia hasła generowany jest zarówno token dostępu, jak i token odświeżania. Na przykład:

{
    "issued_at": "1420258685042",
    "scope": "READ",
    "application_name": "ce1e94a2-9c3e-42fa-a2c6-1ee01815476b",
    "refresh_token_issued_at": "1420258685042",
    "status": "approved",
    "refresh_token_status": "approved",
    "api_product_list": "[PremiumWeatherAPI]",
    "expires_in": "1799", //--in seconds
    "developer.email": "tesla@weathersample.com",
    "organization_id": "0",
    "token_type": "BearerToken",
    "refresh_token": "IFl7jlijYuexu6XVSSjLMJq8SVXGOAAq",
    "client_id": "5jUAdGv9pBouF0wOH5keAVI35GBtx3dT",
    "access_token": "I6daIgMSiUgYX1K2qgQWPi37ztS6",
    "organization_name": "docs",
    "refresh_token_expires_in": "28799", //--in seconds
    "refresh_count": "0"
}

Jeśli <GenerateResponse> ma wartość Fałsz, zasada nie zwraca odpowiedzi. Zamiast tego wypełnia poniższy zestaw zmiennych przepływu danymi związanymi z przydzielonym tokenem dostępu.

oauthv2accesstoken.{policy-name}.access_token
oauthv2accesstoken.{policy-name}.expires_in   //--in seconds
oauthv2accesstoken.{policy-name}.refresh_token
oauthv2accesstoken.{policy-name}.refresh_token_expires_in  //--in seconds
oauthv2accesstoken.{policy-name}.refresh_token_issued_at
oauthv2accesstoken.{policy-name}.refresh_token_status

Na przykład:

oauthv2accesstoken.GenerateAccessToken.access_token
oauthv2accesstoken.GenerateAccessToken.expires_in
oauthv2accesstoken.GenerateAccessToken.refresh_token
oauthv2accesstoken.GenerateAccessToken.refresh_token_expires_in
oauthv2accesstoken.GenerateAccessToken.refresh_token_issued_at
oauthv2accesstoken.GenerateAccessToken.refresh_token_status

Żądanie tokena dostępu: niejawny typ uwierzytelnienia

W tej sekcji objaśniamy, jak zażądać tokena dostępu za pomocą przepływu niejawnego typu uwierzytelnienia. Wprowadzenie do typów uwierzytelniania przez OAuth 2.0 znajdziesz w artykule Wprowadzenie do OAuth 2.0.

Przykładowe żądanie

$ curl -X POST -H 'Content-Type: application/x-www-form-urlencoded' \
  'https://docs-test.apigee.net/oauth/implicit?response_type=token&client_id=ABC123&redirect_uri=http://callback-example.com'

Parametry wymagane

Domyślnie te parametry muszą być parametrami zapytania (jak pokazano w przykładzie powyżej). Można jednak zmienić to ustawienie, konfigurując elementy <ResponseType>, <ClientId> i <RedirectUri> w zasadzie OAuthV2 dołączonej do tego punktu końcowego /token. Szczegółowe informacje znajdziesz w artykule Zasady OAuthV2.

Dane logowania użytkownika są zwykle sprawdzane w odniesieniu do magazynu danych logowania przy użyciu wywołania usługi LDAP lub zasady JavaScript.

  • response_type – musi mieć wartość token.
  • client_id: identyfikator klienta zarejestrowanej aplikacji dewelopera.
  • redirect_uri – ten parametr jest wymagany, jeśli podczas rejestrowania aplikacji dewelopera nie podano identyfikatora URI wywołania zwrotnego. Jeśli URL wywołania zwrotnego został podany podczas rejestracji klienta, zostanie on porównany z tą wartością i musi być dokładnie taki sam.

Parametry opcjonalne

  • state – ciąg znaków, który zostanie odesłany z odpowiedzią. Zwykle używany do zapobiegania sfałszowaniu żądania z innej witryny.
  • scope – umożliwia filtrowanie listy usług API, z którymi można używać wygenerowanego tokena. Szczegółowe informacje o zakresie znajdziesz w artykule o korzystaniu z zakresów OAuth2.

Uwierzytelnianie

Uwierzytelnianie niejawne nie wymaga podstawowego uwierzytelniania. Musisz przekazać identyfikator klienta jako parametr żądania, jak opisano tutaj.

Przykładowy punkt końcowy

Oto przykładowa konfiguracja punktu końcowego umożliwiająca generowanie tokena dostępu. Zostaną uruchomione zasady GenerateAccessTokenImplicitGrant.

...
       <Flow name="generate-access-token-implicit">
            <Request>
                <Step>
                    <Name>GenerateAccessTokenImplicitGrant</Name>
                </Step>
            </Request>
            <Response/>
            <Condition>(proxy.pathsuffix MatchesPath "/implicit") and (request.verb = "POST")</Condition>
        </Flow>
...

Przykładowa zasada

To jest podstawowa zasada GenerateAccessTokenImplicitGrant, która przetwarza żądania tokenów na potrzeby przepływu niejawnego typu uwierzytelnienia. Więcej informacji o opcjonalnych elementach konfiguracji, które możesz skonfigurować za pomocą tej zasady, znajdziesz w artykule Zasady OAuthV2.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<OAuthV2 name="GenerateAccessTokenImplicit">
    <DisplayName>GenerateAccessTokenImplicit</DisplayName>
    <Operation>GenerateAccessTokenImplicitGrant</Operation>
    <GenerateResponse enabled="true"/>
</OAuthV2>

Zwroty

Gdy zasada <GenerateResponse> jest włączona, zasada zwraca w nagłówku odpowiedzi przekierowanie 302 do lokalizacji. Przekierowanie prowadzi do adresu URL określonego w parametrze redirect_uri i jest do niego dołączony token dostępu oraz czas jego wygaśnięcia. Pamiętaj, że typ uwierzytelnienia niejawnego nie obsługuje tokenów odświeżania. Na przykład:

https://callback-example.com#expires_in=1799&access_token=In4dKm4ueoGZRbIYJhC9yZCmTFw5

Jeśli <GenerateResponse> ma wartość Fałsz, zasada nie zwraca odpowiedzi. Zamiast tego wypełnia poniższy zestaw zmiennych przepływu danymi związanymi z przydzielonym tokenem dostępu.

oauthv2accesstoken.{policy-name}.access_token
oauthv2accesstoken.{policy-name}.expires_in  //--in seconds

Na przykład:

oauthv2accesstoken.GenerateAccessToken.access_token
oauthv2accesstoken.GenerateAccessToken.expires_in   //--in seconds

Żądanie kodu autoryzacji

Jeśli korzystasz z procesu przyznawania kodu autoryzacji, przed zgłoszeniem prośby o token dostępu musisz uzyskać kod autoryzacji.

Przykładowe żądanie

$ curl -X POST -H 'Content-Type: application/x-www-form-urlencoded' \
  'http://myorg-test.apigee.net/oauth/authorize?client_id={consumer_key}&response_type=code'

gdzie w punkcie końcowym serwera proxy /oauth/authorize jest dołączona zasada OAuthV2 GenerateAuthorizationCode (zobacz poniżej przykładowy punkt końcowy).

Parametry wymagane

Domyślnie te parametry muszą być parametrami zapytania (jak pokazano w przykładzie powyżej). Można jednak zmienić to ustawienie, konfigurując elementy <ResponseType>, <ClientId> i <RedirectUri> w zasadzie OAuthV2 dołączonej do tego punktu końcowego /authorize. Szczegółowe informacje znajdziesz w artykule Zasady OAuthV2.

  • response_type – musi mieć wartość code.
  • client_id: identyfikator klienta zarejestrowanej aplikacji dewelopera.

Parametry opcjonalne

  • redirect_uri – jeśli w zarejestrowanej aplikacji klienckiej jest określony pełny (nie częściowy) identyfikator URI wywołania zwrotnego, ten parametr jest opcjonalny. W przeciwnym razie jest wymagany. Wywołanie zwrotne to adres URL, na który Edge wysyła nowo wygenerowany kod autoryzacji. Zobacz też Rejestrowanie aplikacji i zarządzanie kluczami interfejsu API.
  • state – ciąg znaków, który zostanie odesłany z odpowiedzią. Zwykle używany do zapobiegania sfałszowaniu żądania z innej witryny.
  • scope – umożliwia filtrowanie listy usług API, z którymi można używać wygenerowanego tokena. Szczegółowe informacje o zakresie znajdziesz w artykule o korzystaniu z zakresów OAuth2.

Uwierzytelnianie

Nie wymaga uwierzytelniania podstawowego, ale w żądaniu musi być podany identyfikator klienta zarejestrowanej aplikacji klienta.

Przykładowy punkt końcowy

Oto przykładowa konfiguracja punktu końcowego do generowania kodu autoryzacji:


<OAuthV2 name="GenerateAuthorizationCode">
  <Operation>GenerateAuthorizationCode</Operation>
    <!--
    ExpiresIn, in milliseconds. The ref is optional. The explicitly specified
    value is the default, when the variable reference cannot be resolved.
        60000 = 1 minute
       120000 = 2 minutes
    -->
  <ExpiresIn>60000</ExpiresIn>
  <GenerateResponse enabled="true"/>
</OAuthV2>

Przykładowa zasada

To jest podstawowa zasada GenerateAuthorizationCode. Więcej informacji o opcjonalnych elementach konfiguracji, które możesz skonfigurować za pomocą tej zasady, znajdziesz w artykule Zasady OAuthV2.

<OAuthV2 name="GenerateAuthorizationCode">
    <Operation>GenerateAuthorizationCode</Operation>
    <GenerateResponse enabled="true"/>
</OAuthV2>

Zwroty

Gdy zasada <GenerateResponse> jest włączona, zasada zwraca parametr zapytania ?code do lokalizacji redirect_uri (identyfikator URI wywołania zwrotnego) z dołączonym kodem autoryzacji. Jest ona wysyłana za pomocą przekierowania 302 w przeglądarce z adresem URL podanym w nagłówku Location odpowiedzi. Na przykład: ?code=123456.

Jeśli zasada <GenerateResponse> ma wartość false, zasada nie zwraca odpowiedzi. Zamiast tego wypełnia poniższy zestaw zmiennych przepływu danymi dotyczącymi kodu autoryzacji.

oauthv2authcode.{policy-name}.code
oauthv2authcode.{policy-name}.scope
oauthv2authcode.{policy-name}.redirect_uri
oauthv2authcode.{policy-name}.client_id

Na przykład:

oauthv2authcode.GenerateAuthorizationCode.code
oauthv2authcode.GenerateAuthorizationCode.scope
oauthv2authcode.GenerateAuthorizationCode.redirect_uri
oauthv2authcode.GenerateAuthorizationCode.client_id

Odświeżanie tokena dostępu

Token odświeżania to dane logowania, których używasz do uzyskania tokena dostępu, zwykle po wygaśnięciu lub unieważnieniu tokena dostępu. Gdy otrzymasz token dostępu, w odpowiedzi zostanie zwrócony token odświeżania.

Aby poprosić o nowy token dostępu za pomocą tokena odświeżania:

Przykładowe żądanie

Informacje o kodowaniu nagłówka podstawowego uwierzytelniania w poniższym wywołaniu znajdziesz w sekcji „Kodowanie podstawowych danych uwierzytelniających”. 

$ curl -X POST \
  -H "Content-type: application/x-www-form-urlencoded" \
  -H 'Authorization: Basic c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ' \
  https://myorg-test.apigee.net/my_oauth_endpoint/refresh_accesstoken \
  -d 'grant_type=refresh_token&refresh_token=my-refresh-token'

Parametry wymagane

  • grant_type – musi mieć wartość refresh_token.
  • refresh_token – token odświeżania powiązany z tokenem dostępu, który chcesz odnowić.

Domyślnie zasada szuka ich jako parametrów x-www-form-urlencoded określonych w treści żądania, jak pokazano w przykładzie powyżej. Aby skonfigurować alternatywną lokalizację dla tych danych wejściowych, możesz użyć elementów <GrantType> i <RefreshToken> w zasadzie OAuthV2. Szczegółowe informacje znajdziesz w artykule Zasady OAuthV2.

Parametry opcjonalne

  • state – ciąg znaków, który zostanie odesłany z odpowiedzią. Zwykle używany do zapobiegania sfałszowaniu żądania z innej witryny.
  • scope – umożliwia filtrowanie listy usług API, z którymi można używać wygenerowanego tokena. Szczegółowe informacje o zakresie znajdziesz w artykule o korzystaniu z zakresów OAuth2.

Uwierzytelnianie

  • client_id
  • client_secret

Identyfikator klienta i tajny klucz klienta należy przekazać jako nagłówek uwierzytelniania podstawowego (zakodowany w formacie Base64) lub jako parametry formularza client_id i client_secret. Zapoznaj się też z sekcją „Kodowanie podstawowych danych uwierzytelniających”.

Odświeżenie tokena dostępu nie powoduje ponownego uwierzytelnienia użytkownika.

Oto przykładowa konfiguracja punktu końcowego, w której można wygenerować token dostępu za pomocą tokena odświeżania. Zostaną uruchomione zasady refreshAccessToken.

 ...
       <Flow name="generate-refresh-token">
            <Request>
                <Step>
                    <Name>RefreshAccessToken</Name>
                </Step>
            </Request>
            <Response/>
            <Condition>(proxy.pathsuffix MatchesPath "/refresh") and (request.verb = "POST")</Condition>
       </Flow>
...

Przykładowa zasada

To jest podstawowa zasada refreshAccessToken skonfigurowana tak, by akceptowała typ uwierzytelnienia refresh_token. Informacje o opcjonalnych elementach konfiguracji, które możesz skonfigurować za pomocą tej zasady, znajdziesz w artykule Zasady OAuthV2.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<OAuthV2 name="RefreshAccessToken">
    <Operation>RefreshAccessToken</Operation>
    <GenerateResponse enabled="true"/>
    <ExpiresIn>1800000</ExpiresIn> <!-- 30 minutes -->
    <RefreshTokenExpiresIn>28800000</RefreshTokenExpiresIn> <!-- 8 hours -->
</OAuthV2>

Zwroty

Gdy zasada <GenerateResponse> jest włączona, zasada zwraca odpowiedź JSON zawierającą nowy token dostępu. Typ uwierzytelnienia refresh_token obsługuje generowanie zarówno tokenów dostępu, jak i nowych tokenów odświeżania. Na przykład:

{
    "issued_at": "1420301470489",
    "application_name": "ce1e94a2-9c3e-42fa-a2c6-1ee01815476b",
    "scope": "READ",
    "refresh_token_issued_at": "1420301470489",
    "status": "approved",
    "refresh_token_status": "approved",
    "api_product_list": "[PremiumWeatherAPI]",
    "expires_in": "1799", //--in seconds
    "developer.email": "tesla@weathersample.com",
    "token_type": "BearerToken",
    "refresh_token": "8fKDHLryAD9KFBsrpixlq3qPJnG2fdZ5",
    "client_id": "5jUAdGv9pBouF0wOH5keAVI35GBtx3dT",
    "access_token": "jmZ2Hqv3iNsABUtAAsfWR3QGNctw",
    "organization_name": "docs",
    "refresh_token_expires_in": "28799", //--in seconds
    "refresh_count": "2"
}

Pamiętaj, że po wygenerowaniu nowego tokena odświeżania oryginał traci ważność.

Powyższa odpowiedź wyświetli się, jeśli <GenerateResponse> ma wartość Prawda. Jeśli zasada <GenerateResponse> ma wartość Fałsz, zasada nie zwraca odpowiedzi. Zamiast tego wypełnia poniższy zestaw zmiennych kontekstu (przepływu) danymi związanymi z przydzielonym tokenem dostępu.

oauthv2accesstoken.{policy-name}.access_token
oauthv2accesstoken.{policy-name}.expires_in   //--in seconds
oauthv2accesstoken.{policy-name}.refresh_token
oauthv2accesstoken.{policy-name}.refresh_token_expires_in  //--in seconds
oauthv2accesstoken.{policy-name}.refresh_token_issued_at
oauthv2accesstoken.{policy-name}.refresh_token_status

Na przykład:

oauthv2accesstoken.RefreshAccessToken.access_token
oauthv2accesstoken.RefreshAccessToken.expires_in
oauthv2accesstoken.RefreshAccessToken.refresh_token
oauthv2accesstoken.RefreshAccessToken.refresh_token_expires_in
oauthv2accesstoken.RefreshAccessToken.refresh_token_issued_at
oauthv2accesstoken.RefreshAccessToken.refresh_token_status

Kodowanie podstawowych danych uwierzytelniających

Użycie wywołania interfejsu API w celu żądania tokena lub kodu autoryzacji jest dobrym zwyczajem. Specyfikacja OAuth 2.0 zaleca przekazywanie wartości client_id i client_secret jako nagłówka podstawowego uwierzytelniania HTTP, zgodnie z opisem w IETF RFC 2617. Aby to zrobić, musisz zakodować wynik połączenia tych 2 wartości zakodować w formacie base64, oddzielając je dwukropkiem.

W pseudokodzie:

result = Base64Encode(concat('ns4fQc14Zg4hKFCNaSzArVuwszX95X', ':', 'ZIjFyTsNgQNyxI'))

W tym przykładzie ns4fQc14Zg4hKFCNaSzArVuwszX95X to identyfikator klienta, a ZIjFyTsNgQNyxI to tajny klucz klienta.

Niezależnie od języka programowania użytego do obliczania wartości zakodowanej w formacie base64 w przypadku tych danych logowania klienta wynik zakodowany w tym formacie to: bnM0ZlFjMTRaZzRoS0ZDTmFTekFyVnV3c3pYOTVYOlpJakZ5VHNOZ1FOeXhJOg==

Następnie możesz wysłać żądanie tokena w ten sposób:

$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Authorization: Basic bnM0ZlFjMTRaZzRoS0ZDTmFTekFyVnV3c3pYOTVYOlpJakZ5VHNOZ1FOeXhJOg==' \
  -X POST 'https://docs-test.apigee.net/oauth/accesstoken' \
  -d 'grant_type=client_credentials'

Jeśli użyjesz opcji -u, narzędzie curl faktycznie utworzy podstawowy nagłówek HTTP. Ten tekst jest odpowiednikiem powyższego:

$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' \
  -u 'ns4fQc14Zg4hKFCNaSzArVuwszX95X:ZIjFyTsNgQNyxI' \
  -X POST 'https://docs-test.apigee.net/oauth/accesstoken' \
  -d 'grant_type=client_credentials'

Inne środowiska programowania mogą mieć podobne skróty, które automatycznie generują nagłówek zakodowany w formacie base64.

Haszowanie tokenów w bazie danych

Aby chronić dostęp OAuth i odświeżać tokeny w przypadku naruszenia bezpieczeństwa bazy danych, możesz włączyć automatyczne szyfrowanie tokenów w organizacji Edge. Gdy ta funkcja jest włączona, Edge automatycznie tworzy zaszyfrowaną wersję nowo wygenerowanego dostępu OAuth i tokenów odświeżania przy użyciu określonego algorytmu. (poniżej znajdziesz informacje o zbiorczym szyfrowaniu istniejących tokenów). Tokeny niezaszyfrowane są używane w wywołaniach interfejsu API, a Edge weryfikuje je względem zahaszowanych wersji w bazie danych.

Poniższe właściwości na poziomie organizacji kontrolują szyfrowanie tokenów OAuth.

features.isOAuthTokenHashingEnabled = true
features.OAuthTokenHashingAlgorithm = SHA1 | SHA256 | SHA384 | SHA512 | PLAIN

Jeśli masz już zaszyfrowane tokeny i chcesz je zachować do momentu ich wygaśnięcia, ustaw w organizacji poniższe właściwości, w których algorytm szyfrowania będzie zgodny z istniejącym algorytmem (na przykład SHA1 – poprzednia wartość domyślna Edge). Jeśli tokeny nie były zaszyfrowane, użyj PLAIN.

features.isOAuthTokenFallbackHashingEnabled = true
features.OAuthTokenFallbackHashingAlgorithm = SHA1 | SHA256 | SHA384 | SHA512 | PLAIN

Jeśli korzystasz z Edge Cloud, skontaktuj się z zespołem pomocy Apigee Edge, aby ustawić te właściwości w organizacji i opcjonalnie zbiorczo haszować istniejące tokeny.

Powiązane artykuły