> ## Documentation Index
> Fetch the complete documentation index at: https://help.dingtalk.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Memperoleh kredensial akses pengguna yang telah masuk

> Pelajari cara memperoleh kredensial akses agar aplikasi dapat memanggil DingTalk OpenAPI atas nama pengguna yang telah masuk — melalui empat langkah: pembuatan aplikasi, otorisasi OAuth, pengambilan kredensial, dan pemanggilan API.

Ketika aplikasi perlu memanggil DingTalk OpenAPI atas nama pengguna yang telah masuk untuk mengoperasikan resource, ikuti prosedur pada topik ini untuk memperoleh kredensial akses guna memanggil API.

<Note>
  Prosesnya serupa untuk aplikasi internal dan aplikasi perusahaan pihak ketiga. Topik ini menggunakan aplikasi internal sebagai contoh.
</Note>

## Langkah 1: Buat aplikasi

1. Masuk ke [DingTalk Developer Platform](https://open-dev.dingtalk.io/#/loginMan).

2. Buka halaman detail aplikasi yang telah Anda buat. Pada halaman **Basic Information**, lihat **SuiteKey/SuiteSecret (Aplikasi perusahaan pihak ketiga) atau AppKey/AppSecret (Aplikasi internal)** milik aplikasi.

3. Pada halaman detail aplikasi, klik **Development Configuration** > **Security Settings**, lalu masukkan redirect URI (domain callback).

   > Redirect URI adalah alamat yang Anda harapkan menjadi tujuan pengalihan setelah otorisasi masuk.

## Langkah 2: Otorisasi masuk OAuth

Untuk menggunakan DingTalk OpenAPI membaca dan menulis resource atas nama pengguna, selesaikan otorisasi melalui alur Otorisasi OAuth 2.0. Alur Otorisasi OAuth 2.0 diilustrasikan di bawah ini.

### Menggunakan halaman otorisasi masuk yang disediakan oleh DingTalk

Susun halaman otorisasi masuk. Parameter halaman adalah sebagai berikut:

### Penting

* Untuk keterbacaan, jeda baris ditambahkan pada contoh parameter berikut. Jeda baris tidak diperlukan dalam penggunaan sebenarnya.
* Nilai parameter harus dienkode dalam format URL. Contoh berikut sudah dienkode dalam format URL.

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
https://login.dingtalk.io/oauth2/auth?
redirect_uri=https%3A%2F%2Fwww.aaaaa.com%2Fa%2Fb
&response_type=code
&client_id=dingbbbbbbb
&scope=openid corpid
&state=dddd
&prompt=consent
```

| Nama            | Wajib | Deskripsi                                                                                                                                                                                                                                                                                                                                                                                                                   |
| --------------- | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| redirect\_uri   | Ya    | URL callback setelah otorisasi diberikan atau ditolak.  **Penting**  Harus sesuai dengan domain yang terdaftar untuk aplikasi.                                                                                                                                                                                                                                                                                              |
| response\_type  | Ya    | Nilai tetap code.  Mengembalikan authCode setelah otorisasi diberikan.                                                                                                                                                                                                                                                                                                                                                      |
| client\_id      | Ya    | Diperoleh dari detail aplikasi yang dibuat pada Langkah 1.   - Aplikasi internal: client\_id adalah App Key aplikasi. - Aplikasi perusahaan pihak ketiga: client\_id adalah SuiteKey aplikasi.                                                                                                                                                                                                                              |
| scope           | Ya    | Cakupan otorisasi. Informasi otorisasi yang ditampilkan pada halaman otorisasi didasarkan pada konfigurasi saat registrasi aplikasi.  Saat ini, hanya dua nilai yang didukung:   - **openid**: Setelah otorisasi, ID pengguna diperoleh. - **openid** corpid: Setelah otorisasi, ID pengguna dan ID organisasi yang dipilih pengguna saat masuk diperoleh, dipisahkan dengan spasi. Perhatikan bahwa enkode URL diperlukan. |
| prompt          | Ya    | Ketika disetel ke consent, halaman konfirmasi otorisasi ditampilkan.                                                                                                                                                                                                                                                                                                                                                        |
| state           | Tidak | Dikembalikan apa adanya bersama authCode.                                                                                                                                                                                                                                                                                                                                                                                   |
| org\_type       | Tidak | Mengontrol output tipe daftar organisasi tertentu. org\_type=management menunjukkan bahwa hanya organisasi dengan izin administratif yang dikembalikan.  **Penting**  Parameter ini hanya bermakna ketika scope berisi corpid.                                                                                                                                                                                              |
| corpId          | Tidak | Menentukan organisasi yang harus dipilih pengguna.  **Penting**   - Parameter ini hanya bermakna ketika scope berisi corpid. - corpId yang diteruskan harus merupakan organisasi tempat pengguna saat ini bergabung.                                                                                                                                                                                                        |
| exclusiveLogin  | Tidak | Ketika disetel ke true, menunjukkan masuk akun eksklusif dan menampilkan halaman input Kode Organisasi.                                                                                                                                                                                                                                                                                                                     |
| exclusiveCorpId | Tidak | corpId dari organisasi yang mengaktifkan fitur akun eksklusif.  **Penting**  Parameter ini hanya bermakna ketika exclusiveLogin bernilai true,  dan mengalihkan langsung ke halaman masuk organisasi tersebut.                                                                                                                                                                                                              |

Jika berhasil, mengalihkan ke: [https://www.aaaaa.com/a/b?authCode=xxxx\&state=dddd](https://www.aaaaa.com/a/b?authCode=xxxx\&state=dddd)

Jika gagal, mengalihkan ke: [https://www.aaaaa.com/a/b?error=yyyyyy\&state=dddd](https://www.aaaaa.com/a/b?error=yyyyyy\&state=dddd)

### Otorisasi masuk dengan Kode QR tersemat

<Warning>
  Halaman yang menyematkan Kode QR harus "same-origin" dengan halaman yang ditentukan oleh parameter redirect\_uri. Jika tidak, pemindaian Kode QR tidak akan berpengaruh. "Same-origin" berarti protokol yang sama, domain tingkat kedua atau ketiga yang sama, nomor port yang sama, dan seterusnya. Untuk detail, lihat [Same-origin policy](https://developer.mozilla.org/zh-CN/docs/Web/Security/Same-origin_policy).
</Warning>

1. Sertakan DingTalk Scan QR Code sign-in JSSDK pada halaman.

   ```xml theme={"theme":{"light":"github-light","dark":"github-dark"}}
   <script src="https://g.alicdn.com/dingding/h5-dingtalk-login/0.21.0/ddlogin.js"></script>
   ```
2. Panggil metode berikut di tempat yang memerlukan masuk dengan Pindai Kode QR.

   ```html theme={"theme":{"light":"github-light","dark":"github-dark"}}
   <!-- STEP1: Tambahkan elemen kontainer pembungkus dalam HTML -->
   <div id="self_defined_element" class="self-defined-classname"></div>
   <style>
       /* STEP2: Tentukan gaya CSS untuk elemen kontainer pembungkus ini. Perhatikan secara khusus width dan height. */
       .self-defined-classname {
           width: 300px;
           height: 300px;
       }
   </style>
   <script>
       // STEP3: Saat diperlukan, panggil metode window.DTFrameLogin untuk menyusun Kode QR masuk dan menangani callback berhasil atau gagal.
       window.DTFrameLogin(
           {
               id: 'self_defined_element',
               width: 300,
               height: 300,
           },
           {
               redirect_uri: encodeURIComponent('http://www.aaaaa.com/a/b/'),
               client_id: 'dingxxxxxxxxxxxx',
               scope: 'openid',
               response_type: 'code',
               state: 'xxxxxxxxx',
               prompt: 'consent',
           },
           (loginResult) => {
               const {redirectUrl, authCode, state} = loginResult;
               // Anda dapat mengalihkan langsung di sini
               window.location.href = redirectUrl;
               // Atau gunakan code untuk otorisasi tanpa mengalihkan halaman
               console.log(authCode);
           },
           (errorMsg) => {
               // Biasanya, tampilkan alasan spesifik kegagalan masuk di sini
               alert(`Login Error: ${errorMsg}`);
           },
       );
   </script>
   ```

   Deskripsi parameter (dalam TypeScript):

   ```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
   // ********************************************************************************
   // Definisi metode window.DTFrameLogin
   // ********************************************************************************
   window.DTFrameLogin: (
     frameParams: IDTLoginFrameParams, // Parameter terkait kontainer pembungkus DOM
     loginParams: IDTLoginLoginParams, // Parameter masuk terpadu
     successCbk: (result: IDTLoginSuccess) => void, // Fungsi callback saat masuk berhasil
     errorCbk?: (errorMsg: string) => void,         // Fungsi callback saat masuk gagal
   ) => void;

   // ********************************************************************************
   // Parameter terkait kontainer pembungkus DOM
   // ********************************************************************************
   // Catatan! Parameter width dan height hanya menetapkan ukuran elemen iframe Kode QR dan tidak memengaruhi ukuran kontainer pembungkus.
   // Ukuran dan gaya kontainer pembungkus harus disetel oleh integrator menggunakan CSS.
   interface IDTLoginFrameParams {
     id: string;      // Wajib. ID elemen kontainer pembungkus, tanpa '#'.
     width?: number;  // Opsional. Lebar elemen iframe Kode QR. Minimum 280. Default 300.
     height?: number; // Opsional. Tinggi elemen iframe Kode QR. Minimum 280. Default 300.
   }

   // ********************************************************************************
   // Parameter masuk terpadu
   // ********************************************************************************
   // Arti parameter identik dengan metode integrasi "Construct a link to initiate sign-in authorization" (dengan beberapa parameter dihilangkan).
   // Parameter isPre ditambahkan untuk menyetel lingkungan runtime.
   interface IDTLoginLoginParams {
     redirect_uri: string;     // Wajib. Perhatikan bahwa URL harus dienkode.
     response_type: string;    // Wajib. Nilai tetap code.
     client_id: string;        // Wajib.
     scope: string;            // Wajib. Jika nilainya openid+corpid, parameter org_type dan corpId di bawah ini wajib. Jika tidak, masuk akan gagal.
     prompt: string;           // Wajib. Nilainya consent.
     state?: string;           // Opsional.
     org_type?: string;        // Opsional. Wajib ketika scope adalah openid+corpid.
     corpId?: string;          // Opsional. Wajib ketika scope adalah openid+corpid.
     exclusiveLogin?: string;  // Opsional. Untuk menghasilkan Kode QR khusus organisasi eksklusif, setel ini ke true agar masuk dibatasi hanya untuk akun organisasi.
     exclusiveCorpId?: string; // Opsional. Wajib ketika exclusiveLogin bernilai true. Menentukan corpId organisasi eksklusif.
   }

   // ********************************************************************************
   // Hasil masuk yang dikembalikan saat masuk berhasil
   // ********************************************************************************
   interface IDTLoginSuccess {
     redirectUrl: string;   // URL pengalihan setelah masuk berhasil. Integrator dapat langsung menggunakan URL ini untuk pengalihan.
     authCode: string;      // authCode yang diperoleh setelah masuk berhasil. Integrator dapat melakukan autentikasi langsung tanpa mengalihkan halaman.
     state?: string;        // state yang diperoleh setelah masuk berhasil.
   }
   ```

## Langkah 3: Peroleh kredensial akses

Gunakan auth\_code yang dikembalikan dan informasi aplikasi untuk memanggil API [Get user token](/id/open/development/obtain-user-token) guna memperoleh access\_token.

Contoh kode:

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
POST /v1.0/oauth2/userAccessToken HTTP/1.1
Host:api.dingtalk.io
x-acs-dingtalk-access-token:BE3xxxx
Content-Type:application/json

{
  "clientId" : "dingxxx",
  "clientSecret" : "1234",
  "code" : "abcd",
  "refreshToken" : "abcd",
  "grantType" : "authorization_code"
}
```

## Langkah 4: Panggil API dengan kredensial akses

Setelah memperoleh access\_token, Anda dapat menggunakan kredensial ini untuk memanggil API [Get user contact profile](/id/open/development/dingtalk-retrieve-user-information).