Pengesahan aplikasi dan akaun¶

Proses pengesahan cTrader Open API adalah berdasarkan standard OAuth 2.0.

Kerangka kerja ini membolehkan aplikasi pihak ketiga mendapatkan akses terhad kepada perkhidmatan sama ada bagi pihak pemilik sumber, dengan mengaturkan interaksi kelulusan antara pemilik sumber dan perkhidmatan, atau dengan membenarkan aplikasi pihak ketiga mendapatkan akses bagi pihaknya sendiri.

Aliran pengesahan ¶

Seperti standard OAuth 2.0, pengesahan akaun memerlukan kedua-dua kod pengesahan dan token akses.

Biasanya, proses seseorang yang baru mula menggunakan aplikasi anda untuk kali pertama kelihatan seperti berikut:

1. Pengguna dengan cTID tertentu mengakses aplikasi anda di mana sahaja ia dihoskan; pengguna berinteraksi dengan butang tindakan atau yang setara.

2. Aplikasi menggunakan penyemak imbas terbenam (atau cara lain yang sesuai) untuk mengalihkan pengguna ke URI tertentu di mana mereka akan memberikan aplikasi kebenaran yang diperlukan.

3. Pengguna dipindahkan ke URL pengalihan yang telah ditetapkan. URL ini mengandungi token akses sebagai nilai parameter pertanyaan code.

4. Pengguna dipindahkan kembali ke aplikasi sama ada secara sukarela atau automatik. Aplikasi dimaklumkan tentang nilai parameter code.

5. Aplikasi menghantar permintaan untuk menukar kod pengesahan dengan token akses ke titik akhir tertentu.

6. Aplikasi menerima respons yang mengandungi token akses sebagai nilai kunci accessToken.

7. Aplikasi menghantar mesej ProtoOAApplicationAuthReq yang mengandungi medan clientId dan clientSecret.

8. Aplikasi menghantar mesej ProtoOAGetAccountListByAccessTokenReq yang mengandungi medan accessToken. Respons (ProtoOAGetAccountListByAccessTokenRes) mengandungi medan berulang ctidTraderAccountId.

9. Selepas menerima respons, aplikasi menghantar mesej ProtoOAAccountAuthReq yang mengandungi medan ctidTraderAccountId dan accessToken.

Selepas itu, pengguna harus disahkan di bawah akaun yang ctidTraderAccountIdnya sepadan dengan ctidTraderAccountId yang diberikan semasa langkah 8.

Rajah di bawah menerangkan bagaimana aliran pengesahan asas berfungsi dari perspektif aplikasi Open API anda.

graph TB
  A([Alihkan pengguna ke <br/> URI tertentu]) ==> B([Terima kod <br/> kebenaran]);
  B ==> C([Hantar permintaan untuk <br/> mendapatkan kod akses]);
  C ==> D([Hantar mesej <br/> ProOAApplicationAuthReq]);
  D ==> E([Hantar mesej <br/> ProtoOAAccountAuthReq]);

Dalam sub-bahagian di bawah, kami menerangkan langkah utama aliran pengesahan secara terperinci.

Tambah URI pengalihan ¶

Seperti yang ditunjukkan sebelumnya, aplikasi anda perlu mendapatkan kod pengesahan selepas pengguna dihantar ke URI pengalihan tertentu. URI ini akan termasuk kod pengesahan sebagai nilai parameter pertanyaan code.

Untuk menambah URI pengalihan baharu, lakukan yang berikut:

1. Buka halaman Aplikasi dalam portal Open API.

2. Pilih butang Edit dalam baris dengan aplikasi yang anda ingin tambahkan URL pengalihan.

3. Dalam skrin yang muncul, tatal ke bawah ke bahagian URI Pengalihan.

4. Tambah URL pengalihan dalam medan input teks kosong yang tersedia. Jika tiada medan tersedia dipaparkan, pilih butang Tambah URI pengalihan.

5. Pilih butang Simpan di bahagian bawah halaman untuk mengaplikasikan perubahan anda.

Dapatkan kod pengesahan ¶

Untuk menerima kod pengesahan untuk cTID tertentu, aplikasi anda perlu menghantar pengguna ke URI berikut.

https://id.ctrader.com/my/settings/openapi/grantingaccess/?client_id={clientId}&redirect_uri={your_redirectURI}&scope={scope}&product=web

URI ini mempunyai parameter pertanyaan berikut.

Untuk melihat client_id anda, pergi ke halaman Aplikasi dan pilih butang Lihat dalam lajur Kelayakan.

Selepas pengguna dihantar ke URI di atas (dan selagi kedua-dua parameter adalah sah), mereka akan melihat skrin log masuk/mendaftar yang meminta mereka untuk mengesahkan di bawah cTID mereka. Selepas itu, pengguna akan ditunjukkan dialog di mana mereka boleh membenarkan aplikasi untuk mendapatkan akses kepada satu atau lebih akaun yang dipautkan dengan cTID mereka.

Apabila pengguna memilih butang Benarkan akses, mereka akan dialihkan ke redirect_uri yang anda tentukan pada asalnya. Seperti yang ditunjukkan dalam contoh di bawah, kod pengesahan akan ditambahkan ke URI ini sebagai parameter pertanyaan.

https://my-redirect-uri.com/?code=123ASDASffdg_as234_GCllkoq14adRB7_tvN

Pada ketika ini, aplikasi anda perlu mengakses dan menyimpan nilai parameter code. Ia mesti ditukar dengan cepat dengan token akses sebelum kod pengesahan luput.

Dapatkan token akses ¶

Untuk mendapatkan token akses, lakukan panggilan API REST berikut.

Permintaan ini termasuk parameter pertanyaan berikut.

Contoh permintaan boleh didapati di bawah.

curl -X GET 'https://openapi.ctrader.com/apps/token?grant_type=authorization_code&code=0ssdgds98as9_QSF56FVC_22dfdf&redirect_uri=https://spotware.com&client_id=5430012&client_secret=012sds23dlkjQsd' -H 'Accept: application/json' -H 'Content-Type: application/json'

Untuk melihat client_secret anda, kembali ke halaman Aplikasi dan pilih butang Lihat dalam lajur Kelayakan.

Apabila permintaan berjaya, anda sepatutnya menerima respons dengan kunci berikut.

Untuk contoh respons yang berjaya, lihat coretan di bawah.

{
    "accessToken":"mos8Bw3D4EG0fRPd4Eqq0JxaFT4zjd8e4YijNezh_ag",
    "tokenType":"bearer",
    "expiresIn":2628000,
    "refreshToken":"VCuafFhy81AFZjsWkbuEzdOhhRj5YTWz8fWUwHam7KM",
    "errorCode":null,
    "description":null,
}

Hantar mesej ProtoBuf yang diperlukan ¶

Selepas menerima kod akses yang sah, aplikasi anda perlu menghantar mesej ProtoOAApplicationAuthReq, ProtoOAGetAccountListByAccessTokenReq dan ProtoOAAccountAuthReq. Ini boleh dilakukan seperti berikut.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

private static RepeatedField<ProtoOACtidTraderAccount> _ctidTraderAccounts;

List<IDisposable> _disposables = new();
_disposables.Add(_client.OfType<ProtoOAGetAccountListByAccessTokenRes>().Subscribe(OnAccountIdReceived));

private static void OnAccountIdReceived(ProtoOAGetAccountListByAccessTokenRes response)
{

    Console.WriteLine($"\nMessage Received:\n{response}");

    _ctidTraderAccounts = response.CtidTraderAccount;

    var accountAuthReq = new ProtoOAAccountAuthReq
    {
        CtidTraderAccountId = (long)_ctidTraderAccounts[0].CtidTraderAccountId,
        AccessToken = _token.AccessToken,
    };

    _client.SendMessage(accountAuthReq);

}

var _client = new OpenClient(host, ApiInfo.Port, TimeSpan.FromSeconds(10), useWebSocket: false);
var applicationAuthReq = new ProtoOAApplicationAuthReq
{
    ClientId = {your_client_id}, // Add your client ID here
    ClientSecret = {your_app_secret}, // Add your app secret here
};
await _client.SendMessage(applicationAuthReq);
await Task.Delay(5000);
var getAccountListByAccessToken = new ProtoOAGetAccountListByAccessTokenReq 
{
    AccessToken = {access_token} // Add your access token here
}
var accountAuthReq = new ProtoOAAccountAuthReq 
{
    ctidTraderAccountId = {account_id}, // Add the ctidTraderAccountId of the account you want to authorize here
    AccessToken = {access_token} // Add your access token here
};
await _client.SendMessage(accountAuthReq);

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

currentAccountId = None
client = Client(EndPoints.PROTOBUF_LIVE_HOST if hostType.lower() == "live" else EndPoints.PROTOBUF_DEMO_HOST, EndPoints.PROTOBUF_PORT, TcpProtocol)

def connected(client): # Callback for client connection
    print("\nConnected")
    request = ProtoOAApplicationAuthReq()
    request.clientId = appClientId
    request.clientSecret = appClientSecret
    deferred = client.send(request)



def disconnected(client, reason): # Callback for client disconnection
    print("\nDisconnected: ", reason)

def onMessageReceived(client, message): # Callback for receiving all messages
    global currentAccountId
    if message.payloadType in [ProtoOASubscribeSpotsRes().payloadType, ProtoOAAccountLogoutRes().payloadType, ProtoHeartbeatEvent().payloadType]:
        return
    elif message.payloadType == ProtoOAApplicationAuthRes().payloadType:
        print("API Application authorized\n")
        if currentAccountId is not None:
            sendProtoOAAccountAuthReq()
            return
        accountListReq = ProtoOAGetAccountListByAccessTokenReq()
        accountListReq.accessToken = accessToken
        deferred = client.send(accountListReq)
    elif message.payloadType == ProtoOAGetAccountListByAccessTokenRes().payloadType:
        protoOAGetAccountListByAccessTokenRes = Protobuf.extract(message)
        currentAccountId = int(protoOAGetAccountListByAccessTokenRes.ctidTraderAccount[0].ctidTraderAccountId)
        accountAuthReq = ProtoOAAccountAuthReq()
        accountAuthReq.ctidTraderAccountId = currentAccountId
        accountAuthReq.accessToken = accessToken
        deferred = client.send(accountAuthReq)
    elif message.payloadType == ProtoOAAccountAuthRes().payloadType:
        protoOAAccountAuthRes = Protobuf.extract(message)
        print(f"Account {protoOAAccountAuthRes.ctidTraderAccountId} has been authorized\n")
        print("This acccount will be used for all future requests\n")
    else:
        print("Message received: \n", Protobuf.extract(message))
    reactor.callLater(3, callable=executeUserCommand)

def onError(failure): # Call back for errors
    print("Message Error: ", failure)
    reactor.callLater(3, callable=executeUserCommand)

Segarkan token akses ¶

Selepas token akses tamat tempoh, anda perlu memperbaharuinya menggunakan refreshToken yang anda terima sebelumnya. Anda boleh melakukan tindakan ini melalui dua kaedah yang berbeza.

Hantar permintaan HTTP¶

Untuk mendapatkan token akses baharu (dan, seterusnya, token segar baharu), anda boleh melakukan permintaan HTTP yang sama dibincangkan di atas. Seperti yang ditunjukkan dalam contoh di bawah, anda perlu menetapkan parameter pertanyaan grant_type kepada refresh_token.

curl -X POST 'https://openapi.ctrader.com/apps/token?grant_type=refresh_token&refresh_token=asdXCVCVAS_218kjashf_asdasd2ASD_223x&client_id=5430012&client_secret=012sds23dlkjQsd' -H 'Accept: application/json' -H 'Content-Type: application/json'

Anda akan menerima respons yang mengandungi nilai baharu bagi kunci accessToken dan refreshToken. Anda boleh menggunakan nilai baharu ini dengan selamat manakala nilai lama bagi kunci yang sama akan secara automatik tidak sah.

Hantar mesej Protobuf¶

Sebagai alternatif, anda boleh menghantar mesej ProtoOARefreshTokenReq dan menerima mesej ProtoOARefreshTokenRes yang mengandungi token baharu yang sah.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

_disposables.Add(_client.OfType<ProtoOARefreshTokenRes>().Subscribe(OnRefreshTokenResponse));
private static void OnRefreshTokenResponse(ProtoOARefreshTokenRes response) 
{
    _token = new Token 
    {
        AccessToken = response.AccessToken,
        RefreshToken = response.RefreshToken,
        ExpiresIn = DateTimeOffset.FromUnixTimeMilliseconds(response.ExpiresIn),
        TokenType = response.TokenType,
    }
}
var refreshTokenReq = new ProtoOARefreshTokenReq
    {
        refreshToken = {your_refresh_token}, // Add your refresh token here
    };
await _client.SendMessage(applicationAuthReq);

1

newToken = auth.refreshToken("refresh_Token")

Gunakan Playground ¶

Playground menyediakan cara pantas untuk mendapatkan token akses untuk cTID anda sendiri, membolehkan anda membangunkan dan menguji aplikasi anda dengan cepat dan mudah sebelum mengedarkannya kepada khalayak sasaran.

Untuk mengakses Playground, pergi ke halaman Aplikasi dan pilih butang Playground. Dalam tetingkap yang baru muncul, pilih skop aplikasi dan klik butang Dapatkan token.

Selepas itu, anda sepatutnya melihat halaman berikut.

Anda boleh menggunakan token akses dan token segar untuk menghantar mesej ke API semasa diautentikasi di bawah cTID anda sendiri.