OAuth2¶

OAuth2, bir kullanıcının bir uygulamaya hesabına erişim izni vermesinin yoludur. Aynı onay adımı, uygulamanın botunu bir sunucuya veya grup DM'ye de kurabilir. Uygulama kayıtları, istemci gizli anahtarları ve bot token'ları Uygulamalar kaynağına aittir.

Yetkilendirme kodu akışı¶

1. Uygulama, kullanıcının tarayıcısını Uygulamayı yetkilendir (GET /oauth2/authorize) adresine gönderir. TEBHOS tarayıcıyı, tüm sorgu parametrelerini ileterek web uygulamasının onay ekranına (https://tebhos.com/oauth2/authorize) yönlendirir.
2. Kullanıcı onayladığında web uygulaması OAuth2 onayı ver yolunu çağırır. TEBHOS bir yetkilendirme kodu üretir ve sonuna code (ve state) eklenmiş olarak uygulamanın geri çağırma URL'sini döndürür.
3. Uygulamanın sunucusu, istemci kimlik bilgileriyle kodu OAuth2 token'ı değiş tokuş et yolunda takas eder ve bir erişim token'ı ile bir yenileme token'ı alır.
4. Uygulama, Authorization: Bearer <access_token> ile OAuth2 kullanıcı bilgilerini al veya Geçerli OAuth2 yetkilendirmesini al yolunu çağırır.

Proof Key for Code Exchange (PKCE), S256 ve plain yöntemleriyle desteklenir. Meydan okuma (challenge), kod üretildiği anda koda bağlanır. code_challenge_method olmadan verilen bir code_challenge, plain olarak değerlendirilir. Meydan okuması olan bir kodun takasında eşleşen bir code_verifier verilmesi zorunludur.

Kimlik bilgileri ve ömürleri¶

Yetkilendirme kodlarını, istemci gizli anahtarlarını, erişim token'larını ve yenileme token'larını opak gizli değerler olarak ele alın. Her biri base64url ile kodlanmış 32 rastgele bayttır.

Yenileme takası, sunulan yenileme token'ını tüketir ve yeni bir çift üretir. Daha önce üretilmiş erişim token'ları süreleri dolana kadar geçerli kalır.

Yol kimlik doğrulaması¶

Uygulamayı yetkilendir, OAuth2 onayı ver ve yetkilendirme listeleme yolları kullanıcının kimliğini bir oturum token'ıyla doğrular. Token, iç gözlem (introspection) ve iptal yolları ise uygulamanın kimliğini istemci kimliği ve istemci gizli anahtarıyla doğrular ve hız sınırlarını istemcinin IP adresine göre anahtarlar. OAuth2 kullanıcı bilgilerini al ve Geçerli OAuth2 yetkilendirmesini al OAuth2 erişim token'ı ile kimlik doğrular.

OAuth2 kapsamları¶

Bir kapsam (scope), uygulamanın kullanıcı adına okuyabileceği veya yapabileceği tek bir şeyi adlandırır.

TEBHOS kapsam dizesini boşluk ve + karakterlerinden böler, boş parçaları atar ve tekrarlanan değerleri birleştirir. Tanınmayan bir değer isteği invalid_scope ile reddeder.

OAuth2 hataları¶

OAuth2 hataları olağan hata yanıtını kullanır. OAuth2 hata adı message içindedir; bazen ardından iki nokta üst üste ve ayrıntı gelir:

{
  "error": "400 Bad Request",
  "code": "BAD_REQUEST",
  "message": "invalid_grant"
}

İstemci dallanmayı HTTP durumuna ve message başındaki hata adına göre yapmak ZORUNDADIR; metnin geri kalanına göre asla yapmamalıdır.

OAuth2 token nesnesi¶

Başarılı bir token takasının döndürdüğü çift.

Yapı¶

Örnek¶

{
  "access_token": "M2xQb1RkY0hqTmZLc1B2WndBcUx1RWc2WXRJbk9iUmE",
  "token_type": "Bearer",
  "expires_in": 604800,
  "refresh_token": "VGhpc0lzQUZha2VSZWZyZXNoVG9rZW5Gb3JEb2NzMDE",
  "scope": "email identify"
}

OAuth2 kullanıcı bilgisi nesnesi¶

Yapı¶

OAuth2 iç gözlem nesnesi¶

Yapı¶

Etkin olmayan bir sonuç yalnızca active: false içerir. active true olduğunda diğer tüm alanlar bulunur; yalnızca exp hariç, çünkü yenileme token'ında hiçbir zaman yoktur.

Geçerli OAuth2 yetkilendirme nesnesi¶

Yapı¶

OAuth2 uygulama özeti nesnesi¶

Yapı¶

OAuth2 yetkilendirme nesnesi¶

Geçerli kullanıcının yetkilendirdiği bir uygulama.

Yapı¶

Kullanıcı bir uygulama için en az bir geçerli erişim token'ına sahip olduğu sürece uygulama listede görünür.

Uygulamayı yetkilendir¶

GET /oauth2/authorize

Bir yetkilendirme isteği başlatır. Her zaman 302 yönlendirmesiyle yanıt verir. Kimlik doğrulama isteğe bağlıdır.

Sorgu parametreleri¶

Yanıt¶

prompt=none olmadan yönlendirme, verilen tüm parametreler iletilerek https://tebhos.com/oauth2/authorize adresine gider. Bu aşamada hiçbir şey doğrulanmaz; doğrulamayı onay ekranı OAuth2 onayı ver yolunu çağırdığında yapar.

prompt=none ile TEBHOS sessizce kod üretmeyi dener:

Hata hedefi, uygulama tam olarak o dizeyi kaydetmişse verilen redirect_uri, aksi hâlde web uygulaması URL'sidir; bu sayede bu yol hiçbir zaman rastgele bir kaynağa yönlendirmez. Hata yönlendirmesi error ve state taşır, error_description taşımaz.

Hız sınırı¶

oauth:authorize kovasında, her IP adresi için dakikada 60 istek.

OAuth2 onayı ver¶

POST /oauth2/authorize/consent

Oturum açmış kullanıcı adına bir yetkilendirme isteğini tamamlar ve bot kapsamının bir hedefi varsa botu kurar. Bir kullanıcı oturum token'ı gerektirir. code ve, verildiyse, state içeren geri çağırma URL'sini {"redirect_to": string} olarak döndürür.

Bu, TEBHOS onay ekranının çağırdığı yoldur. Üçüncü taraf bir uygulama onu doğrudan çağırmaz.

JSON gövdesi¶

guild_id ve channel_id birbirini dışlar. redirect_uri olmadan yapılan yalnızca-bot isteği, geri çağırmasını web uygulaması URL'sine çözümler.

Yanıt¶

Bot kurulumu¶

bot kapsamı ve bir guild_id ile çağıranın sunucu sahibi olması ya da o sunucuda Manage Guild veya Administrator iznine sahip olması gerekir. Administrator izni olmayan bir çağıran yalnızca kendisinin sahip olduğu izin bitlerini isteyebilir.

Bot, çağıran davet eden olarak kaydedilerek sunucuya katılır. Sıfır olmayan bir izin maskesi istendiğinde TEBHOS ayrıca uygulamanın adını taşıyan ve tam olarak bu maskeye sahip bir rol oluşturur (renk #99AAB5, ayrı gösterilmez, bahsedilemez, mevcut rollerin üstüne yerleştirilir) ve rolü bota atar. Sunucunun oturumları bir üye ekleme olayı alır. Bu yolla kurulan bir bot için sunucunun üye sınırı ve yasak listesi denetlenmez.

bot kapsamı ve bir channel_id ile çağıranın grup DM'nin alıcısı olması gerekir. Bot alıcı olarak eklenir ve bir alıcı-ekleme sistem mesajı gönderilir. Zaten alıcı olan bir bot olduğu gibi bırakılır.

Kurulum başarısız olduğunda aynı isteğin ürettiği yetkilendirme kodu silinir; böylece çağıran hiçbir zaman kullanılabilir bir kod almaz.

Hız sınırı¶

oauth:authorize kovasında, her IP adresi için dakikada 60 istek.

OAuth2 token'ı değiş tokuş et¶

POST /oauth2/token

Bir yetkilendirme kodunu veya yenileme token'ını bir OAuth2 token nesnesiyle takas eder.

Gövde application/x-www-form-urlencoded biçimindedir. Uygulama HTTP Basic (Authorization: Basic base64(client_id:client_secret)) ile ya da client_id ve client_secret form alanlarıyla kimlik doğrular. İkisi birden verildiğinde her form alanı, eşleşen Basic değerinden önceliklidir.

Form gövdesi: yetkilendirme kodu¶

Form gövdesi: yenileme token'ı¶

Yanıt¶

İzin denetlenmeden önce istemcinin kimliği doğrulanır. Kod, token'lar üretilmeden önce silinir; bu yüzden bir kodu yeniden oynatmak invalid_grant döndürür. İstemci kimlik bilgileri (client-credentials) akışı yoktur: her token bir kullanıcıya bağlıdır.

Hız sınırı¶

oauth:token kovasında, her IP adresi için dakikada 120 istek.

Örnek¶

curl -X POST https://tebhos.com/api/v1/oauth2/token \
  -u "1501314428688998182:<client_secret>" \
  -d grant_type=authorization_code \
  -d code=<code> \
  -d redirect_uri=https://example.com/callback \
  -d code_verifier=<verifier>

OAuth2 kullanıcı bilgilerini al¶

GET /oauth2/userinfo

Erişim token'ının üretildiği kullanıcı için OAuth2 kullanıcı bilgisi nesnesini döndürür. identify kapsamıyla Authorization: Bearer <access_token> gerektirir.

Yanıt¶

Hız sınırı¶

oauth:introspect kovasında, her istemci için dakikada 120 istek.

OAuth2 token'ına iç gözlem yap¶

POST /oauth2/introspect

Tek bir erişim veya yenileme token'ı için bir OAuth2 iç gözlem nesnesi döndürür. Gövde application/x-www-form-urlencoded biçimindedir ve uygulama OAuth2 token'ı değiş tokuş et yolundaki gibi kimlik doğrular.

Form gövdesi¶

Yanıt¶

Hız sınırı¶

oauth:introspect kovasında, her IP adresi için dakikada 120 istek.

OAuth2 token'ını iptal et¶

POST /oauth2/token/revoke

Bir token'ı iptal eder. Gövde application/x-www-form-urlencoded biçimindedir ve uygulama OAuth2 token'ı değiş tokuş et yolundaki gibi kimlik doğrular.

Form gövdesi¶

Bir yenileme token'ını iptal eden istemci token_type_hint=refresh_token göndermek ZORUNDADIR; aksi hâlde hiçbir şey eşleşmez.

Yanıt¶

Bilinmeyen bir token 200 döndürür; böylece yanıt bir token'ın var olup olmadığını hiçbir zaman göstermez.

Hız sınırı¶

oauth:introspect kovasında, her IP adresi için dakikada 120 istek.

Geçerli OAuth2 yetkilendirmesini al¶

GET /oauth2/@me

Sunulan erişim token'ı için geçerli OAuth2 yetkilendirme nesnesini döndürür. Authorization: Bearer <access_token> gerektirir; kapsam gerekmez. user üyesi yalnızca token identify içerdiğinde eklenir.

Yanıt¶

OAuth2 yetkilendirmelerini listele¶

GET /oauth2/@me/authorizations

Geçerli kullanıcının verdiği OAuth2 yetkilendirme nesnelerini döndürür. Bir kullanıcı oturum token'ı gerektirir. Liste sayfalanmaz.

Hız sınırı¶

oauth_dev:clients:list kovasında, her hesap için dakikada 60 istek.

OAuth2 yetkilendirmesini iptal et¶

DELETE /oauth2/@me/authorizations/{application_id}

Geçerli kullanıcının tek bir uygulama için erişim token'larını iptal eder. Bir kullanıcı oturum token'ı gerektirir. Hiçbir şey verilmemiş olsa bile 204 döndürür.

Yol parametreleri¶

Uygulamanın kurduğu bot, katıldığı her sunucuda ve grup DM'de kalır. Uygulamaya bildirim gönderilmez.

Hız sınırı¶

oauth:introspect kovasında, her hesap için dakikada 120 istek.

OAuth2 yetkilendirmelerini toplu iptal et¶

POST /oauth2/@me/authorizations/revoke

Geçerli kullanıcının birkaç uygulama için verdiği iznin tamamını (erişim ve yenileme token'ları) iptal eder. Bir kullanıcı oturum token'ı gerektirir. 204 döndürür.

JSON gövdesi¶

Hiçbir şey silinmeden önce her uygulama aranır; bu yüzden tek bir bilinmeyen kimlik 404 döndürür ve tüm izinleri olduğu gibi bırakır. Snowflake olmayan bir değer 400 döndürür.

Hız sınırı¶

oauth:introspect kovasında, her hesap için dakikada 120 istek.