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

Wyświetlasz dokumentację Apigee Edge.
Otwórz dokumentację Apigee X. info

W tym artykule pokazujemy, jak wysyłać żądania tokenów dostępu i kodów autoryzacji, konfigurować punkty końcowe OAuth 2.0 oraz konfigurować zasady dla każdego obsługiwanego typu przyznawania uprawnień.

Przykładowy kod

Dla Twojej wygody zasady i punkty końcowe omówione w tym artykule 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 podane w tym temacie. Szczegóły znajdziesz w pliku README projektu.

Wysyłanie prośby o token dostępu: typ przyznawania uprawnień za pomocą kodu autoryzacji

Z tej sekcji dowiesz się, jak poprosić o token dostępu przy użyciu przepływu typu uprawnień kodu autoryzacji. Więcej informacji o typach uwierzytelnienia przez OAuth 2.0 znajdziesz w tym artykule.

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'

Wymagane parametry

Domyślnie te parametry muszą mieć wartość x-www-form-urlencoded i 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 zasadach OAuthV2 dołączonych do tego punktu końcowego /accesstoken. Więcej informacji znajdziesz w sekcji Zasady OAuthV2.

  • grant_type – musi mieć wartość authorization_code.
  • code – kod autoryzacji otrzymany z punktu końcowego /authorize (lub z dowolnego innego punktu końcowego). Aby poprosić o token dostępu w przepływie typu uwierzytelnienia kodem autoryzacji, musisz najpierw uzyskać kod autoryzacji. Więcej informacji znajdziesz w sekcji Prośba o kody autoryzacji poniżej. Zobacz też Implementowanie typu uwierzytelnienia za pomocą kodu autoryzacji.
  • redirect_uri – musisz podać ten parametr, jeśli w poprzednim żądaniu kodu autoryzacji został uwzględniony parametr redirect_uri. Jeśli parametr redirect_uri nie został uwzględniony w żądaniu kodu autoryzacji i nie podasz tego parametru, ta zasada użyje wartości adresu URL wywołania zwrotnego, która została podana podczas rejestracji aplikacji dewelopera.

Parametry opcjonalne

  • state – ciąg, który zostanie odesłany w odpowiedzi. Zwykle używany do zapobiegania atakom typu żądanie z innej witryny.
  • scope – umożliwia filtrowanie listy usług API, w których można używać wygenerowanego tokena. Szczegółowe informacje o zakresie znajdziesz w artykule Praca z zakresami OAuth2.

Uwierzytelnianie

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

Przykładowy punkt końcowy

Oto przykładowa konfiguracja punktu końcowego do generowania tokena dostępu. Wykonuje ona zasadę GenerateAccessToken, która musi być skonfigurowana tak, aby obsługiwać typ udzielenia authorization_code.

...
       <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ładowe zasady

Jest to podstawowa zasada GenerateAccessToken skonfigurowana tak, aby akceptować typ uprawnień authorization_code. Informacje o opcjonalnych elementach konfiguracji, które możesz skonfigurować za pomocą tych zasad, 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 <GenerateResponse> jest włączona, zasada zwraca odpowiedź JSON, która zawiera token dostępu, jak pokazano poniżej. Typ autoryzacji authorization_code tworzy token dostępu i token 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 zasada <GenerateResponse> ma wartość Fałsz, nie zwraca odpowiedzi. Zamiast tego wypełnia następujący zestaw zmiennych przepływu danymi dotyczącymi przyznania tokena 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

Wysyłanie prośby o token dostępu: typ przyznawanych uprawnień klienta

Z tej sekcji dowiesz się, jak poprosić o token dostępu przy użyciu przepływu typu przyznania danych uwierzytelniających klienta. Więcej informacji o typach uwierzytelnienia przez OAuth 2.0 znajdziesz w tym artykule.

Przykładowe żądanie

Informacje o kodowaniu nagłówka uwierzytelniania podstawowego w tym wywołaniu znajdziesz w sekcji „Kodowanie danych logowania uwierzytelniania podstawowego”. 

$ 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'

Wymagane parametry

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 domyślne, konfigurując element <GrantType> w zasadach OAuthV2, które są dołączone do tego punktu końcowego /accesstoken. Możesz na przykład przekazać parametr w parametrze zapytania. Więcej informacji znajdziesz w sekcji Zasady OAuthV2.

  • grant_type – musi mieć wartość client_credentials.

Parametry opcjonalne

  • state – ciąg, który zostanie odesłany w odpowiedzi. Zwykle używany do zapobiegania atakom typu żądanie z innej witryny.
  • scope – umożliwia filtrowanie listy usług API, w których można używać wygenerowanego tokena. Szczegółowe informacje o zakresie znajdziesz w artykule Praca z zakresami OAuth2.

Uwierzytelnianie

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

Przykładowy punkt końcowy

Oto przykładowa konfiguracja punktu końcowego do generowania tokena dostępu. Wykonuje ona zasadę GenerateAccessToken, która musi być skonfigurowana tak, aby obsługiwać typ przyznawanych uprawnień 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ładowe zasady

Jest to podstawowa zasada GenerateAccessToken skonfigurowana tak, aby akceptować typ uprawnień client_credentials. Informacje o opcjonalnych elementach konfiguracji, które możesz skonfigurować za pomocą tych zasad, 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 <GenerateResponse> jest włączone, zasada zwraca odpowiedź w formacie JSON. Pamiętaj, że w przypadku typu uprawnień 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 zasada <GenerateResponse> ma wartość Fałsz, nie zwraca odpowiedzi. Zamiast tego wypełnia następujący zestaw zmiennych przepływu danymi dotyczącymi przyznania tokena 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

Prośba o token dostępu: typ przyznawanych uprawnień „hasło”

Z tej sekcji dowiesz się, jak poprosić o token dostępu przy użyciu przepływu typu udzielenia danych logowania właściciela zasobu (hasła). Wprowadzenie do typów uwierzytelniania przez OAuth 2.0 znajdziesz w artykule Wprowadzenie do OAuth 2.0.

Więcej informacji o typie uprawnień hasła, w tym 4-minutowy film pokazujący, jak go wdrożyć, znajdziesz w artykule Implementowanie typu uprawnień hasła.

Przykładowe żądanie

Informacje o kodowaniu nagłówka uwierzytelniania podstawowego w tym wywołaniu znajdziesz w sekcji „Kodowanie danych logowania uwierzytelniania podstawowego”. 

$ 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'

Wymagane parametry

Domyślnie te parametry muszą mieć wartość x-www-form-urlencoded i 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 zasadach OAuthV2 dołączonych do tego punktu końcowego /token. Więcej informacji znajdziesz w sekcji Zasady OAuthV2.

Dane logowania użytkownika są zwykle weryfikowane w magazynie danych logowania za pomocą zasad LDAP lub JavaScript.

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

Parametry opcjonalne

  • state – ciąg, który zostanie odesłany w odpowiedzi. Zwykle używany do zapobiegania atakom typu żądanie z innej witryny.
  • scope – umożliwia filtrowanie listy usług API, w których można używać wygenerowanego tokena. Szczegółowe informacje o zakresie znajdziesz w artykule Praca z zakresami OAuth2.

Uwierzytelnianie

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

Przykładowy punkt końcowy

Oto przykładowa konfiguracja punktu końcowego do generowania tokena dostępu. Wykonuje ona zasadę GenerateAccessToken, która musi być skonfigurowana tak, aby obsługiwać 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ładowe zasady

Jest to podstawowa zasada GenerateAccessToken skonfigurowana tak, aby akceptować typ udzielenia hasła. Informacje o opcjonalnych elementach konfiguracji, które możesz skonfigurować za pomocą tych zasad, 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 <GenerateResponse> jest włączone, zasada zwraca odpowiedź w formacie JSON. Uwaga: w przypadku typu autoryzacji hasłem generowane są zarówno token dostępu, jak i token odświeżania. Obejmuje to 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 zasada <GenerateResponse> ma wartość Fałsz, nie zwraca odpowiedzi. Zamiast tego wypełnia następujący zestaw zmiennych przepływu danymi dotyczącymi przyznania tokena 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

Prośba o token dostępu: typ przyznania niejawnego

Z tej sekcji dowiesz się, jak poprosić o token dostępu za pomocą przepływu typu przyznawania uprawnień w sposób dorozumiany. Wprowadzenie do typów uwierzytelnienia 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'

Wymagane parametry

Domyślnie te parametry muszą być parametrami zapytania (jak pokazano w przykładzie powyżej). Można jednak zmienić to ustawienie domyślne, konfigurując elementy <ResponseType>, <ClientId> i <RedirectUri> w zasadach OAuthV2 dołączonych do tego punktu końcowego /token. Więcej informacji znajdziesz w sekcji Zasady OAuthV2.

Dane logowania użytkownika są zwykle weryfikowane w magazynie danych logowania za pomocą 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 rejestracji aplikacji programisty klienta nie podano identyfikatora URI wywołania zwrotnego. Jeśli podczas rejestracji klienta podano adres URL wywołania zwrotnego, zostanie on porównany z tą wartością i musi być dokładnie taki sam.

Parametry opcjonalne

  • state – ciąg, który zostanie odesłany w odpowiedzi. Zwykle używany do zapobiegania atakom typu żądanie z innej witryny.
  • scope – umożliwia filtrowanie listy usług API, w których można używać wygenerowanego tokena. Szczegółowe informacje o zakresie znajdziesz w artykule Praca z zakresami OAuth2.

Uwierzytelnianie

Udzielenie uprawnień w sposób dorozumiany nie wymaga podstawowego uwierzytelniania. Musisz przekazać identyfikator klienta jako parametr żądania, jak wyjaśniono tutaj.

Przykładowy punkt końcowy

Oto przykładowa konfiguracja punktu końcowego do generowania tokena dostępu. Wykonana zostanie zasada 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ładowe zasady

Jest to podstawowa zasada GenerateAccessTokenImplicitGrant, która przetwarza żądania tokenów w przypadku przepływu typu przyznawanie uprawnień w sposób dorozumiany. Informacje o opcjonalnych elementach konfiguracji, które możesz skonfigurować za pomocą tych zasad, 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 <GenerateResponse> jest włączona, zasada zwraca w nagłówku odpowiedzi przekierowanie 302 Location. Przekierowanie wskazuje adres URL określony w parametrze redirect_uri i jest uzupełniane o token dostępu oraz czas wygaśnięcia tokena. Pamiętaj, że typ uprawnień implicit nie obsługuje tokenów odświeżania. Na przykład:

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

Jeśli zasada <GenerateResponse> ma wartość Fałsz, nie zwraca odpowiedzi. Zamiast tego wypełnia następujący zestaw zmiennych przepływu danymi dotyczącymi przyznania tokena 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

Prośba o kod autoryzacji

Jeśli używasz przepływu typu uwierzytelnienia authorization_code, musisz uzyskać kod autoryzacji, zanim poprosisz o token dostępu.

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 do /oauth/authorizepunktu końcowego proxy (zobacz przykładowy punkt końcowy poniżej) jest dołączona zasada OAuthV2 GenerateAuthorizationCode.

Wymagane parametry

Domyślnie te parametry muszą być parametrami zapytania (jak pokazano w przykładzie powyżej). Można jednak zmienić to ustawienie domyślne, konfigurując elementy <ResponseType>, <ClientId> i <RedirectUri> w zasadach OAuthV2 dołączonych do tego punktu końcowego /authorize. Więcej informacji znajdziesz w sekcji 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 podano pełny (nie częściowy) adres URI wywołania zwrotnego, ten parametr jest opcjonalny. W przeciwnym razie jest wymagany. Adres zwrotny 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, który zostanie odesłany w odpowiedzi. Zwykle używany do zapobiegania atakom typu żądanie z innej witryny.
  • scope – umożliwia filtrowanie listy usług API, w których można używać wygenerowanego tokena. Szczegółowe informacje o zakresie znajdziesz w artykule Praca z zakresami OAuth2.

Uwierzytelnianie

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

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ładowe zasady

Jest to podstawowa zasada GenerateAuthorizationCode. Informacje o opcjonalnych elementach konfiguracji, które możesz skonfigurować za pomocą tych zasad, znajdziesz w artykule Zasady OAuthV2.

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

Zwroty

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

Jeśli wartość parametru <GenerateResponse> to false, zasada nie zwraca odpowiedzi. Zamiast tego wypełnia on danymi dotyczącymi kodu autoryzacji ten zestaw zmiennych przepływu:

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 uzyskiwania tokena dostępu, zwykle po wygaśnięciu lub unieważnieniu tokena dostępu. Token odświeżania jest zwracany w odpowiedzi, gdy otrzymasz token dostępu.

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

Przykładowe żądanie

Informacje o kodowaniu nagłówka uwierzytelniania podstawowego w tym wywołaniu znajdziesz w sekcji „Kodowanie danych logowania uwierzytelniania podstawowego”. 

$ 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 wyszukuje te parametry x-www-form-urlencoded określone w treści żądania, jak pokazano w przykładzie powyżej. Aby skonfigurować alternatywną lokalizację tych danych wejściowych, możesz użyć elementów <GrantType> i <RefreshToken> w zasadach OAuthV2. Więcej informacji znajdziesz w sekcji Zasady OAuthV2.

Parametry opcjonalne

  • state – ciąg, który zostanie odesłany w odpowiedzi. Zwykle używany do zapobiegania atakom typu żądanie z innej witryny.
  • scope – umożliwia filtrowanie listy usług API, w których można używać wygenerowanego tokena. Szczegółowe informacje o zakresie znajdziesz w artykule Praca z zakresami OAuth2.

Uwierzytelnianie

  • client_id
  • client_secret

Identyfikator klienta i tajny klucz klienta musisz przekazać jako nagłówek uwierzytelniania podstawowego (zakodowany w standardzie base64) lub jako parametry formularza client_id i client_secret. Zobacz też „Kodowanie danych uwierzytelniających w przypadku podstawowego uwierzytelniania”.

Podczas odświeżania tokena dostępu użytkownik nie jest ponownie uwierzytelniany.

Oto przykładowa konfiguracja punktu końcowego do generowania tokena dostępu za pomocą tokena odświeżania. Wykonana zostanie zasada 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ładowe zasady

Jest to podstawowa zasada RefreshAccessToken skonfigurowana tak, aby akceptować typ uprawnień refresh_token. Informacje o opcjonalnych elementach konfiguracji, które możesz skonfigurować za pomocą tych zasad, 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 <GenerateResponse> jest włączone, zasada zwraca odpowiedź JSON zawierającą nowy token dostępu. Typ autoryzacji 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 pierwotny token przestaje być ważny.

Powyższa odpowiedź jest generowana, gdy zasada <GenerateResponse> ma wartość Prawda. Jeśli zasada <GenerateResponse> ma wartość Fałsz, nie zwraca odpowiedzi. Zamiast tego wypełnia danymi dotyczącymi przyznania tokena dostępu ten zestaw zmiennych kontekstowych (przepływu):

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

Gdy wysyłasz wywołanie interfejsu API, aby poprosić o token lub kod autoryzacji, zaleca się przekazywanie wartości client_id i client_secret jako nagłówka uwierzytelniania HTTP Basic, zgodnie z opisem w IETF RFC 2617. Jest to dobra praktyka i jest zalecana przez specyfikację protokołu OAuth 2.0. Aby to zrobić, musisz zakodować w formacie base64 wynik połączenia tych 2 wartości za pomocą dwukropka.

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, którego używasz do obliczania wartości zakodowanej w formacie base64, w przypadku podanych danych logowania klienta wynik zakodowany w formacie base64 to:bnM0ZlFjMTRaZzRoS0ZDTmFTekFyVnV3c3pYOTVYOlpJakZ5VHNOZ1FOeXhJOg==

Następnie możesz wysłać prośbę o token 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'

Narzędzie curl utworzy za Ciebie nagłówek uwierzytelniania podstawowego HTTP, jeśli użyjesz opcji -u. Poniższy kod jest równoważny powyższemu:

$ 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 programistyczne mogą mieć podobne skróty, które automatycznie generują nagłówek zakodowany w formacie base64.

Haszowanie tokenów w bazie danych

Aby chronić tokeny dostępu i odświeżania OAuth w przypadku naruszenia bezpieczeństwa bazy danych, możesz włączyć automatyczne haszowanie tokenów w organizacji Edge. Gdy ta funkcja jest włączona, Edge automatycznie tworzy zaszyfrowaną wersję nowo wygenerowanych tokenów dostępu i odświeżania OAuth, używając określonego przez Ciebie algorytmu. (Dalsze informacje o masowym haszowaniu istniejących tokenów). W wywołaniach interfejsu API używane są niezaszyfrowane tokeny, a Edge weryfikuje je na podstawie zaszyfrowanych wersji w bazie danych.

Te właściwości na poziomie organizacji kontrolują haszowanie tokenów OAuth.

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

Jeśli masz już zaszyfrowane tokeny i chcesz je zachować do czasu wygaśnięcia, ustaw w organizacji te właściwości, gdzie algorytm szyfrowania jest zgodny z dotychczasowym algorytmem (np. SHA1, czyli poprzednim domyślnym algorytmem Edge). Jeśli tokeny nie zostały zaszyfrowane, użyj wartości PLAIN.

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

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

Powiązane artykuły