Proses akses OAuth 2.0 untuk aplikasi seluler dan aplikasi desktop - Drive and Photo Service

Catatan

Bagian ini menjelaskan cara aplikasi seluler dan desktop mengakses Drive and Photo Service menggunakan OAuth 2.0.

1. Ikhtisar

Aplikasi seluler dan desktop adalah aplikasi asli. Tidak aman untuk menyimpan informasi rahasia seperti AppSecret di dalam aplikasi-aplikasi ini.

Aplikasi seluler untuk Android atau iOS dapat membangunkan aplikasi otorisasi menggunakan skema URL.

Aplikasi desktop untuk macOS, Linux, atau Windows dapat membangunkan aplikasi otorisasi menggunakan alamat IP loopback atau skema URL.

Sebagai alternatif, aplikasi Anda dapat menggunakan WebView untuk mengirim permintaan otorisasi ke aplikasi web.

(1) Cara Kerjanya

Mode kode otorisasi: Proses akses menggunakan kode otorisasi untuk aplikasi seluler atau desktop serupa dengan proses untuk aplikasi web. Satu-satunya perbedaan adalah Anda tidak perlu memberikan AppSecret untuk mendapatkan token akses karena tidak ada server web yang tersedia dan tidak aman untuk menyimpan AppSecret di aplikasi seluler atau desktop.

(2) Diagram Alur

2. Persiapan

(1) Buat Domain

Buat domain di Konsol Drive and Photo Service. Setelah domain dibuat, nama domain API tingkat empat dalam format https://{domainId}.api.aliyunpds.com disediakan.

(2) Aktifkan Fitur Log Masuk Sistem Pengguna

Drive and Photo Service menyediakan beberapa sistem pengguna umum untuk otentikasi log masuk. Pengembang dapat mengaktifkan fitur log masuk sistem pengguna di Konsol Drive and Photo Service. Untuk informasi lebih lanjut, lihat Sistem Pengguna PDS.

(3) Buat Aplikasi sebagai Klien OAuth di Konsol Drive and Photo Service

Buat aplikasi asli. Tentukan ruang lingkup aplikasi yang akan ditampilkan pada halaman persetujuan. Setelah aplikasi dibuat, Anda bisa mendapatkan AppId dan AppSecret dari aplikasi tersebut. AppId dan AppSecret digunakan sebagai ClientId dan ClientSecret untuk otorisasi OAuth. AppKey dan AppSecret adalah kredensial untuk otorisasi dan autentikasi. Anda harus menjaga kerahasiaan AppSecret.

(4) Rencanakan URI Pengalihan

Gunakan Skema URL Kustom untuk Aplikasi Android atau iOS

Daftarkan skema URL untuk aplikasi guna mengidentifikasi aplikasi secara unik. Format skema adalah sebagai berikut: <skema nama domain>://<path>?<params>=<nilai>.

Gunakan Alamat IP Loopback Kustom untuk Aplikasi Desktop

Anda dapat memulai layanan web lokal untuk mendengarkan port tertentu. Contoh: http://127.0.0.1:3000/callback atau http://[::1]:3000.

3. Dapatkan token akses OAuth 2.0

(1) Panggil Operasi Authorize

Sintaks Permintaan API:

GET /v2/oauth/authorize?client_id=<appId>&redirect_uri=<redirect_uri>&scope=<scope>&login_type=<login_type>&state=[state]&prompt=[prompt] HTTP/1.1
Host: {domainId}.api.aliyunpds.com

Parameter	Diperlukan	Deskripsi
client_id	Ya	AppId aplikasi Anda. Jika Anda tidak memiliki AppId, buat aplikasi untuk mendapatkan AppId di konsol Drive and Photo Service.
redirect_uri	Ya	URI tempat server otorisasi Drive and Photo Service mengarahkan pengguna setelah proses otorisasi selesai. Atur parameter ini ke skema URL atau alamat IP lookback yang disediakan oleh aplikasi. Contoh: `pdshz001://callback/`. Setelah otorisasi selesai, server otorisasi Drive and Photo Service mengarahkan pengguna ke URI pengalihan dengan akhiran kode otorisasi satu kali dalam format `pdshz001://callback/?code=xxxx`. Anda dapat menukar kode otorisasi ini dengan token akses. Catatan: URI pengalihan yang Anda tentukan harus sama dengan yang Anda konfigurasikan untuk aplikasi Anda.
scope	Ya	Ruang lingkup yang menentukan izin yang diperlukan oleh aplikasi Anda. Ruang lingkup tersebut akan ditampilkan pada halaman persetujuan. Untuk informasi lebih lanjut, lihat Otorisasi.
response_type	Ya	Jenis respons. Atur nilainya menjadi `code`.
state	Tidak, tetapi direkomendasikan	Jika parameter ini ditentukan, server otorisasi Drive and Photo Service mengembalikan nilai ini utuh dalam URI pengalihan untuk mencegah serangan ulang. Contoh: `pdshz001://callback/?code=xxxx&state=abc`.
login_type	Ya	Metode log masuk. Nilai valid: `default, phone, ding, ldap, wx, and ram`. `default`: masuk ke halaman log masuk default. Halaman log masuk default juga menyediakan tautan ke metode log masuk lainnya, seperti log masuk menggunakan kode verifikasi SMS. `phone`: masuk menggunakan kode verifikasi SMS. `ding`: masuk menggunakan aplikasi DingTalk untuk memindai kode QR. `ldap`: masuk menggunakan Active Directory (AD) domain atau Lightweight Directory Access Protocol (LDAP). `wx`: masuk menggunakan WeChat. `ram`: masuk sebagai pengguna RAM.
hide_consent	Tidak	Menentukan apakah akan menampilkan halaman persetujuan jika pengguna masuk untuk pertama kalinya. Nilai valid: `true and false`. Jika nilainya `true`, halaman persetujuan tidak ditampilkan.
lang	Tidak	Bahasa dalam halaman ditampilkan. Nilai valid: `zh_CN` dan `en_US`. Nilai default: `zh_CN`.

Setelah pengguna mengirim permintaan ini, server otorisasi Drive and Photo Service menginstruksikan pengguna untuk masuk. Jika pengguna masuk untuk pertama kalinya dan tidak menyetel parameter hide_consent ke true, server otorisasi Drive and Photo Service mengarahkan pengguna ke halaman persetujuan. Sebaliknya, server otorisasi Drive and Photo Service mengarahkan pengguna ke URI pengalihan yang ditentukan oleh parameter redirect_uri. Contoh: pdshz001://callback/?code=xxxx&state=abc.

(2) Berikan Izin kepada Aplikasi pada Halaman Persetujuan

Pada halaman persetujuan, pengguna dapat memutuskan apakah akan memberikan izin yang diminta kepada aplikasi. Jika pengguna menolak memberikan izin, proses berakhir. Jika pengguna setuju, server otorisasi Drive and Photo Service mengarahkan pengguna ke URI pengalihan yang ditentukan oleh parameter redirect_uri. Contoh: pdshz001://callback/?code=xxxx&state=abc.

(3) Tukar Kode Otorisasi dengan Token Akses

Setelah kode otorisasi diperoleh, Anda dapat memanggil operasi Token untuk menukar kode otorisasi dengan token akses.

Sintaks Permintaan API:

POST /v2/oauth/token HTTP/1.1
Host: {domainId}.api.aliyunpds.com
Content-Type: application/x-www-form-urlencoded

code=xxx\
&client_id=your_app_id\
&redirect_uri=pdshz001://callback\
&grant_type=authorization_code

Parameter	Diperlukan	Deskripsi
code	Ya	Kode otorisasi satu kali.
client_id	Ya	AppId aplikasi Anda.
redirect_uri	Ya	URI pengalihan yang Anda konfigurasikan untuk aplikasi Anda.
grant_type	Ya	Atur nilainya menjadi authorization_code berdasarkan spesifikasi OAuth 2.0.

Parameter Respons

Parameter	Lokasi	Tipe	Diperlukan	Deskripsi
access_token	body	STRING	Ya	Token akses yang dihasilkan, yang berlaku selama dua jam.
expires_time	body	STRING	Ya	Masa berlaku token akses.
expire_in	body	STRING	Ya	Sisa masa berlaku token akses. Unit: detik.
token_type	body	STRING	Ya	Nilainya tetap Bearer.

Contoh Respons Sukses:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "access_token":"Aiasd76YSo23...LSdyssd2",
  "expires_time":"2019-11-11T10:10:10.009Z",
  "expire_in": 7200,
  "token_type":"Bearer",
  "refresh_token":"LSLKdklksd...li3ew6"
}

Catatan

Respons terhadap permintaan ini sama dengan yang dikembalikan saat Anda mendapatkan token akses menggunakan kode otorisasi, kecuali bahwa parameter refresh_token tidak termasuk.

Catatan

Abaikan parameter opsional dalam respons.

4. Panggil operasi API Drive and Photo Service

Aplikasi dapat menggunakan token akses untuk memanggil operasi API Drive and Photo Service. Token akses harus disertakan dalam header Authorization dari permintaan API.

Untuk informasi lebih lanjut, lihat Metode Pemanggilan.

5. Perbarui token akses

(1) Sintaks Permintaan API

POST /v2/oauth/token HTTP/1.1
Host: {domainId}.api.aliyunpds.com
Content-Type: application/x-www-form-urlencoded

refresh_token=xxx\
&client_id=xxx\
&grant_type=refresh_token

Parameter Permintaan

Parameter	Diperlukan	Deskripsi
refresh_token	Ya	Token penyegaran yang dikembalikan saat Anda menukar kode otorisasi dengan token akses.
client_id	Ya	AppId aplikasi Anda.
grant_type	Ya	Jenis metode pemberian. Atur nilainya menjadi refresh_token berdasarkan spesifikasi OAuth 2.0.
client_secret	Tidak	AppSecret aplikasi Anda. AppSecret digunakan untuk mengotentikasi aplikasi.

(2) Respons

HTTP/1.1 200 OK
Content-Type: application/json

{
  "access_token":"xxxxxxxxx",
  "expires_in":3920,
  "expire_time":"2019-11-11T10:10:10.009Z",
  "token_type":"Bearer"
}

Parameter Respons

Struktur respons terhadap permintaan untuk menyegarkan token akses sama dengan struktur respons terhadap permintaan untuk menukar kode otorisasi dengan token akses.