Autenticação de aplicação e conta¶

O processo de autenticação do Open API da cTrader baseia-se no padrão OAuth 2.0.

Esta estrutura permite que aplicações de terceiros obtenham acesso limitado a um serviço, seja em nome do proprietário do recurso, orquestrando uma interação de aprovação entre o proprietário do recurso e o serviço, seja permitindo que uma aplicação de terceiros obtenha acesso em seu próprio nome.

Fluxo de autenticação ¶

De acordo com o padrão OAuth 2.0, a autenticação da conta requer tanto um código de autorização como um token de acesso.

Normalmente, o processo de alguém novo começar a usar a sua aplicação pela primeira vez é o seguinte:

1. Um utilizador com um determinado cTID acede à sua aplicação onde quer que esteja implementada; o utilizador interage com um botão de ação ou equivalente.

2. A aplicação usa um navegador incorporado (ou qualquer outro meio adequado) para redirecionar o utilizador para um URI específico onde concederá à aplicação as permissões necessárias.

3. O utilizador é transferido para um URL de redirecionamento predefinido. Este URL contém o token de acesso como o valor do parâmetro de consulta code.

4. O utilizador é transferido de volta para a aplicação por vontade própria ou automaticamente. A aplicação é informada do valor do parâmetro code.

5. A aplicação envia um pedido para trocar o código de autorização por um token de acesso para um endpoint específico.

6. A aplicação recebe uma resposta contendo o token de acesso como o valor da chave accessToken.

7. A aplicação envia a mensagem ProtoOAApplicationAuthReq contendo os campos clientId e clientSecret.

8. A aplicação envia a mensagem ProtoOAGetAccountListByAccessTokenReq contendo o campo accessToken. A resposta (ProtoOAGetAccountListByAccessTokenRes) contém o campo repetido ctidTraderAccountId.

9. Após receber uma resposta, a aplicação envia a mensagem ProtoOAAccountAuthReq contendo os campos ctidTraderAccountId e accessToken.

Posteriormente, o utilizador deve ser autenticado na conta cujo ctidTraderAccountId corresponde ao ctidTraderAccountId fornecido durante o passo 8.

O diagrama abaixo explica como o fluxo de autenticação básico funciona na perspetiva da sua aplicação Open API.

graph TB
  A([Redirecionar o utilizador <br/> para um URI específico]) ==> B([Receber o código de <br/>autorização]);
  B ==> C([Enviar um pedido para obter <br/> um código de acesso]);
  C ==> D([Enviar a mensagem <br/> ProOAApplicationAuthReq <br/>]);
  D ==> E([Enviar a mensagem <br/> ProtoOAAccountAuthReq <br/>]);

Nas subsecções abaixo, explicamos os passos principais do fluxo de autenticação em detalhe.

Adicionar um URI de redirecionamento ¶

Como mostrado anteriormente, a sua aplicação precisa de obter um código de autorização depois de um utilizador ser enviado para um determinado URI de redirecionamento. Este URI incluirá o código de autorização como o valor do parâmetro de consulta code.

Para adicionar um novo URI de redirecionamento, faça o seguinte:

1. Abra a página Aplicações no portal Open API.

2. Selecione o botão Editar na linha com a aplicação à qual pretende adicionar um URL de redirecionamento.

3. No ecrã que aparece, desloque para baixo até à secção URIs de Redirecionamento.

4. Adicione um URL de redirecionamento num campo de entrada de texto vazio disponível. Se não forem mostrados campos disponíveis, selecione o botão Adicionar URI de redirecionamento.

5. Selecione o botão Guardar na parte inferior da página para aplicar as suas alterações.

Obter o código de autorização ¶

Para receber um código de autorização para um cTID específico, a sua aplicação precisará de enviar um utilizador para o seguinte URI.

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

Este URI tem os seguintes parâmetros de consulta.

Para ver o seu client_id, aceda à página Aplicações e selecione o botão Ver na coluna Credenciais.

Depois de um utilizador ser enviado para o URI acima (e desde que ambos os parâmetros sejam válidos), deverá ver um ecrã de início de sessão/registo a solicitar autorização com o seu cTID. Em seguida, será apresentada uma caixa de diálogo ao utilizador onde poderá permitir que a aplicação obtenha acesso a uma ou mais contas associadas ao seu cTID.

Quando o utilizador selecionar o botão Permitir acesso, será redirecionado para o redirect_uri que especificou originalmente. Como mostrado no exemplo abaixo, o código de autorização será adicionado a este URI como um parâmetro de consulta.

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

Neste momento, a sua aplicação precisará de aceder e armazenar o valor do parâmetro code. Deve ser rapidamente trocado por um token de acesso antes que o código de autorização expire.

Obter um token de acesso ¶

Para obter um token de acesso, execute a seguinte chamada da API REST.

Este pedido inclui os seguintes parâmetros de consulta.

O exemplo do pedido pode ser encontrado abaixo.

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'

Para ver o seu client_secret, volte à página Aplicações e selecione o botão Ver na coluna Credenciais.

Após um pedido bem-sucedido, deverá receber uma resposta com as seguintes chaves.

Para um exemplo de uma resposta bem-sucedida, consulte o excerto abaixo.

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

Enviar as mensagens ProtoBuf necessárias ¶

Após receber um código de acesso válido, a sua aplicação terá de enviar as mensagens ProtoOAApplicationAuthReq, ProtoOAGetAccountListByAccessTokenReq e ProtoOAAccountAuthReq. Isto pode ser feito da seguinte forma.

 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)

Atualizar o token de acesso ¶

Depois de um token de acesso expirar, terá de o renovar utilizando o refreshToken que recebeu anteriormente. Pode efetuar esta ação através de dois métodos diferentes.

Enviar um pedido HTTP¶

Para obter um novo token de acesso (e, subsequentemente, um novo token de atualização), pode efetuar o mesmo pedido HTTP abordado acima. Como mostrado no exemplo abaixo, terá de definir o parâmetro de consulta grant_type como 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'

Receberá uma resposta contendo os novos valores das chaves accessToken e refreshToken. Pode utilizar com segurança estes novos valores enquanto os valores antigos das mesmas chaves são automaticamente invalidados.

Enviar uma mensagem Protobuf¶

Em alternativa, pode enviar o ProtoOARefreshTokenReq e receber a mensagem ProtoOARefreshTokenRes contendo novos tokens válidos.

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

Utilizar o Playground ¶

O Playground fornece um meio rápido para obter um token de acesso para o seu próprio cTID, permitindo-lhe desenvolver e testar a sua aplicação de forma rápida e fácil antes de a distribuir entre o seu público-alvo.

Para aceder ao Playground, aceda à página Applications e selecione o botão Playground. Na janela que aparece, selecione o âmbito da aplicação e clique no botão Get token.

Depois, deverá ver a seguinte página.

Pode utilizar o token de acesso e o token de atualização para enviar mensagens para a API enquanto autenticado com o seu próprio cTID.