Uygulama ve hesap kimlik doğrulaması¶

cTrader Open API kimlik doğrulama süreci OAuth 2.0 standardına dayanmaktadır.

Bu çerçeve, üçüncü taraf uygulamaların bir hizmete sınırlı erişim elde etmesini sağlar; bu erişim, kaynak sahibinin adına, kaynak sahibi ile hizmet arasında bir onay etkileşimi düzenleyerek veya üçüncü taraf uygulamanın kendi adına erişim elde etmesine izin vererek gerçekleşebilir.

Kimlik doğrulama akışı ¶

OAuth 2.0 standardına göre, hesap kimlik doğrulaması hem bir yetkilendirme kodu hem de bir erişim belirteci gerektirir.

Tipik olarak, uygulamanızı ilk kez kullanmaya başlayan yeni birinin süreci aşağıdaki gibidir:

1. Belirli bir cTID'ye sahip bir kullanıcı, uygulamanızın dağıtıldığı her yerden erişir; kullanıcı bir eylem düğmesi veya eşdeğeri ile etkileşime girer.

2. Uygulama, kullanıcıyı gerekli izinleri vereceği belirli bir URI'ye yönlendirmek için yerleşik bir tarayıcı (veya başka uygun bir yöntem) kullanır.

3. Kullanıcı önceden tanımlanmış bir yönlendirme URL'sine aktarılır. Bu URL, code sorgu parametresinin değeri olarak erişim belirtecini içerir.

4. Kullanıcı, kendi isteğiyle veya otomatik olarak uygulamaya geri aktarılır. Uygulama, code parametresinin değeri hakkında bilgilendirilir.

5. Uygulama, yetkilendirme kodunu bir erişim belirteci ile değiştirmek için belirli bir uç noktaya bir istek gönderir.

6. Uygulama, accessToken anahtarının değeri olarak erişim belirtecini içeren bir yanıt alır.

7. Uygulama, clientId ve clientSecret alanlarını içeren ProtoOAApplicationAuthReq mesajını gönderir.

8. Uygulama, accessToken alanını içeren ProtoOAGetAccountListByAccessTokenReq mesajını gönderir. Yanıt (ProtoOAGetAccountListByAccessTokenRes), tekrarlanan ctidTraderAccountId alanını içerir.

9. Bir yanıt aldıktan sonra, uygulama ctidTraderAccountId ve accessToken alanlarını içeren ProtoOAAccountAuthReq mesajını gönderir.

Daha sonra, kullanıcı, ctidTraderAccountId'si 8. adımda sağlanan ctidTraderAccountId ile eşleşen hesap altında kimlik doğrulaması yapmalıdır.

Aşağıdaki diyagram, temel kimlik doğrulama akışının Open API uygulamanızın bakış açısından nasıl çalıştığını açıklamaktadır.

graph TB
  A([Kullanıcıyı belirli bir <br/> URI'ye yönlendirin]) ==> B([Yetkilendirme kodunu <br/> alın]);
  B ==> C([Erişim kodu <br/> almak için <br/> istek gönderin]);
  C ==> D([ProOAApplicationAuthReq <br/> mesajını <br/> gönderin]);
  D ==> E([ProtoOAAccountAuthReq <br/> mesajını <br/> gönderin]);

Aşağıdaki alt bölümlerde, kimlik doğrulama akışının temel adımlarını ayrıntılı olarak açıklıyoruz.

Bir yönlendirme URI'si ekleme ¶

Daha önce gösterildiği gibi, uygulamanızın bir kullanıcı belirli bir yönlendirme URI'sine gönderildikten sonra bir yetkilendirme kodu alması gerekir. Bu URI, code sorgu parametresinin değeri olarak yetkilendirme kodunu içerecektir.

Yeni bir yönlendirme URI'si eklemek için aşağıdakileri yapın:

1. Open API portalında Uygulamalar sayfasını açın.

2. Yönlendirme URL'si eklemek istediğiniz uygulamanın bulunduğu satırdaki Düzenle düğmesini seçin.

3. Yeni açılan ekranda, Yönlendirme URI'leri bölümüne ilerleyin.

4. Mevcut boş bir metin giriş alanına bir yönlendirme URL'si ekleyin. Mevcut alanlar gösterilmiyorsa, Yönlendirme URI'si Ekle düğmesini seçin.

5. Değişikliklerinizi uygulamak için sayfanın altındaki Kaydet düğmesini seçin.

Yetkilendirme kodunu elde edin ¶

Belirli bir cTID için yetkilendirme kodu almak üzere uygulamanızın bir kullanıcıyı aşağıdaki URI'ye göndermesi gerekecektir.

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

Bu URI aşağıdaki sorgu parametrelerine sahiptir.

client_id'nizi görüntülemek için Uygulamalar sayfasına gidin ve Kimlik Bilgileri sütunundaki Görüntüle düğmesini seçin.

Bir kullanıcı yukarıdaki URI'ye gönderildikten sonra (ve her iki parametre de geçerli olduğu sürece), onları cTID'leri altında yetkilendirmeye yönlendiren bir giriş/kayıt ekranı görmelidirler. Bunun ardından, bir kullanıcıya, cTID'lerine bağlı bir veya daha fazla hesaba erişim sağlaması için uygulamaya izin verebilecekleri bir iletişim kutusu gösterilecektir.

Kullanıcı Erişime izin ver düğmesini seçtiğinde, başlangıçta belirttiğiniz redirect_uri'ye yönlendirileceklerdir. Aşağıdaki örnekte gösterildiği gibi, yetkilendirme kodu bu URI'ye bir sorgu parametresi olarak eklenecektir.

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

Bu noktada, uygulamanızın code parametresinin değerine erişmesi ve onu depolaması gerekecektir. Yetkilendirme kodu süresi dolmadan önce hızlı bir şekilde bir erişim belirteciyle değiştirilmelidir.

Erişim belirtecini elde edin ¶

Bir erişim belirteci almak için aşağıdaki REST API çağrısını gerçekleştirin.

Bu istek aşağıdaki sorgu parametrelerini içerir.

İstek örneği aşağıda bulunabilir.

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'

client_secret'nizi görüntülemek için Uygulamalar sayfasına geri dönün ve Kimlik Bilgileri sütunundaki Görüntüle düğmesini seçin.

Başarılı bir istek üzerine, aşağıdaki anahtarları içeren bir yanıt almalısınız.

Başarılı bir yanıt örneği için aşağıdaki kod parçacığına bakın.

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

Gerekli ProtoBuf mesajlarını gönderin ¶

Geçerli bir erişim kodu aldıktan sonra, uygulamanızın ProtoOAApplicationAuthReq, ProtoOAGetAccountListByAccessTokenReq ve ProtoOAAccountAuthReq mesajlarını göndermesi gerekecektir. Bu işlem aşağıdaki gibi yapılabilir.

 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)

Erişim belirtecini yenileyin ¶

Bir erişim belirtecinin süresi dolduktan sonra, daha önce aldığınız refreshToken'ı kullanarak onu yenilemeniz gerekecektir. Bu eylemi iki farklı yöntemle gerçekleştirebilirsiniz.

Bir HTTP isteği gönderin¶

Yeni bir erişim belirteci (ve ardından yeni bir yenileme belirteci) elde etmek için yukarıda ele alınan aynı HTTP isteğini gerçekleştirebilirsiniz. Aşağıdaki örnekte gösterildiği gibi, grant_type sorgu parametresini refresh_token olarak ayarlamanız gerekir.

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'

accessToken ve refreshToken anahtarlarının yeni değerlerini içeren bir yanıt alacaksınız. Bu yeni değerleri güvenle kullanabilirsiniz; aynı anahtarların eski değerleri otomatik olarak geçersiz kılınır.

Bir Protobuf mesajı gönderin¶

Alternatif olarak, ProtoOARefreshTokenReq mesajını gönderebilir ve yeni geçerli belirteçleri içeren ProtoOARefreshTokenRes mesajını alabilirsiniz.

 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")

Playground'u kullanın ¶

Playground, kendi cTID'niz için bir erişim belirteci elde etmenin hızlı bir yolunu sunar, uygulamanızı hedef kitlenize dağıtmadan önce hızlı ve kolay bir şekilde geliştirmenize ve test etmenize olanak tanır.

Playground'a erişmek için Uygulamalar sayfasına gidin ve Playground düğmesini seçin. Yeni açılan pencerede, uygulamanın kapsamını seçin ve Belirteç al düğmesine tıklayın.

Ardından, aşağıdaki sayfayı görmelisiniz.

Kendi cTID'niz altında kimliği doğrulanmışken API'ye mesaj göndermek için erişim belirtecini ve yenileme belirtecini kullanabilirsiniz.