OAuth 2.0

La API de seven.io se puede utilizar para autenticación y autorización mediante el protocolo OAuth 2.0, para permitir a los usuarios de su software una integración fácil y directa de nuestro servicio.

Fundamentos

A través de OAuth 2.0, su aplicación puede obtener derechos de acceso a las cuentas de los clientes para enviar solicitudes de API directamente en su nombre.

Para ello, primero debe registrar su aplicación con nosotros. Actualmente, solo puede obtener esto de nuestro soporte. Por favor, proporcione su URL de redirección (redirect_uri). Recibirá client_id y client_secret como sus credenciales para nuestra API OAuth 2.0.

Todas las aplicaciones ahora siguen el siguiente patrón al acceder a nuestra API con OAuth 2.0:

  • Primero, debe obtener la autorización del cliente. Para ello, rediríjalo a una página especial en nuestro sitio, donde el cliente debe iniciar sesión y permitir el acceso a su aplicación.
  • Después de la confirmación o rechazo de la solicitud de autorización, el cliente será redirigido de nuevo a su aplicación. Si el cliente otorga el permiso, su aplicación recibirá un código de autorización.
  • Con este código de autorización, su aplicación puede obtener el token de acceso a través de nuestra API OAuth 2.0, lo que permite el acceso directo a nuestras APIs.

Los tokens de acceso tienen una vida útil limitada de una hora por defecto. Si su aplicación necesita acceso a nuestras APIs más allá de la vida útil de un solo token de acceso, puede obtener nuevos tokens de acceso mediante el token de actualización.

Proceso

  1. 1

    Configurar la aplicación

    Recibirá de nosotros las siguientes credenciales para la API OAuth 2.0:

    <Properties>
    <Property name="client_id" type="string">
        Su ID de acceso - por lo general, aquí establecemos el nombre de su aplicación. En el ejemplo aquí es
        _testclient_.
    </Property>
    <Property name="client_secret" type="string">
        Contraseña de acceso para la API OAuth2.0. En el ejemplo aquí es _testsecret_.
    </Property>
</Properties>

Adicionalmente, debe proporcionarnos un `redirect_uri` a la cual redirigiremos después de la autorización.
En nuestro ejemplo aquí, la URL es https://acme.inc/oauth_redirect


### Redirigir al cliente a la página de autorización de OAuth 2.0

Redirija a sus clientes a la siguiente URL:

https://oauth.seven.io/authorize?response_type=code&client_id=testclient&state=xyz&scope=sms%20analytics


<Properties>
    <Property name="state" type="string">
        Una cadena generada aleatoriamente para prevenir ataques de
        [CSRF](https://de.wikipedia.org/wiki/Cross-Site-Request-Forgery). Por favor, utilice un
        [generador de cadenas
        criptográficamente seguro](https://de.wikipedia.org/wiki/Kryptographisch_sicherer_Zufallszahlengenerator).
    </Property>
    <Property name="scope" type="string">
        El ámbito solicitado al que desea tener acceso del cliente; en este caso, el envío de SMS y la consulta de estadísticas.
        Se pueden pasar múltiples ámbitos separados por espacios.
    </Property>
</Properties>


### El cliente es redirigido de vuelta a su aplicación

Después de que el cliente otorga (o niega) la autorización, lo redirigimos automáticamente a su
`redirect_uri` con algunos parámetros GET adicionales.

**En caso de éxito:**

https://acme.inc/oauth_redirect?code=9ccb478a7cbe043c1df211f1d52a6437f8756cf8&state=xyz

**En caso de error:**

https://acme.inc/oauth_redirect?error=access_denied&error_description=The+user+denied+access+to+your+application&state=xyz

    Debe verificar aquí si state coincide con el valor que creó en el segundo paso, para evitar CSRF.

  2. 2

    Consultar el token de acceso

    Obtenga el token de acceso y el token de actualización a través de nuestra API OAuth 2.0.

POST/token

Obtener el token de acceso

Si todo ha funcionado hasta aquí, ahora puede obtener un token de acceso con el parámetro GET code del paso 3 de la siguiente manera:

Anfrage

curl -u testclient:testsecret https://oauth.seven.io/token \
  -d 'grant_type=authorization_code&code=9ccb478a7cbe043c1df211f1d52a6437f8756cf8'

En caso de éxito, recibirá datos en formato JSON como sigue:

Antwort

{
  "access_token":"b1a9391d0469cafe30258893ab6025d4ad94ecec",
  "expires_in":3600,
  "token_type":"Bearer",
  "scope":"sms",
  "refresh_token":"ffd8e622aa5dccc2905f2ac6a0999c785a803157"
}
POST/token

Actualizar el token de acceso

Para actualizar el token de acceso, llame a la API OAuth 2.0 de la siguiente manera:

Anfrage

curl -u testclient:testsecret https://oauth.seven.io/token \
  -d 'grant_type=refresh_token&refresh_token=ffd8e622aa5dccc2905f2ac6a0999c785a803157'

En caso de éxito, recibirá nuevos tokens en formato JSON como sigue:

Antwort

{
  "access_token":"worw5xlrl0sjwqkvmstibwn4pw0mdvpddljzkfi8",
  "expires_in":3600,
  "token_type":"Bearer",
  "scope":"sms",
  "refresh_token":"n94c2kyej8ycsjutmviuk8i6zebgsda0uzg2gbpn"
}

Acceso a nuestras APIs

Acceda a nuestras APIs de acuerdo con la documentación correspondiente y envíe el token de acceso en el Authorization Header sin codificación adicional (sin base64 u otros).

curl https://gateway.seven.io/api/sms -H 'Authorization: Bearer ACCESS_TOKEN'

Además, puede probar la conexión exitosa a través de OAuth 2.0 con la siguiente llamada:

Anfrage

curl https://oauth.seven.io/me -H 'Authorization: Bearer ACCESS_TOKEN'

Antwort

{
    "success": true,
    "user_id": 12345,
    "email": "john.doe@acme.inc",
    "company": "Acme Inc.",
    "alias": "acme_inc",
    "balance": "627.3615"
}

Alcances

Puede solicitar al cliente los siguientes alcances:

AlcanceSignificado
analyticsConsulta de estadísticas
balanceConsultar saldo
contactsConsultar y editar contactos
hooksPermite cambiar y ver webhooks
journalConsultar su libro de registro
lookupRealizar consultas por Lookup (HLR, MNP, etc.)
pricingConsultar precios de la cuenta
rcsEnvío de mensajes RCS
smsEnvío de mensajes SMS
statusConsultar informe de estado de SMS
subaccountsEditar y ver subcuentas
validate_for_voiceVerificar números como remitente para Voice
voiceEnviar mensajes de voz

Varios ámbitos pueden especificarse mediante un espacio codificado en URL. Si no se especifica el ámbito o está vacío, se aplicará el ámbito predeterminado.

Ejemplo de código PHP

Aquí hay un ejemplo sencillo en PHP. En el primer código se genera la URL de OAuth y el cliente es redirigido a ella:

Redirigir clientes a la página OAuth2.0

<?php

// Application credentials
$client_id = 'testclient';
$client_secret = 'testsecret';

session_start();

// Request authorization for sms, analytics and lookup endpoints. // Leave empty to allow all scopes
$requested_scopes = [
  'sms',
  'analytics',
  'lookup'
];

// Generate random string for state
$state = bin2hex(openssl_random_pseudo_bytes(10));

// Store state in session
$_SESSION['state'] = $state;

// Build authorization URI
$auth_uri = 'https://oauth.seven.io/authorize?' .
  http_build_query([
    'response_type' => 'code',
    'client_id' => $client_id,
    'state' => $state,
    'scope' => implode(' ', $requested_scopes),
  ]);

// Redirect User to OAuth authorization site
header('Location: ' . $auth_uri);

El segundo código corresponde a la página que se ejecuta bajo su redirect_uri. Aquí se verifica la autorización y se recuperan los tokens:

Verificación de la autorización y recuperación de tokens

<?php

// Application credentials $client_id = 'testclient'; 
$client_secret = 'testsecret'; 

session_start(); 

// CSRF check failed
if($_GET['state'] != $_SESSION['state']) {
  die('CSRF check failed');
}

// An error occured during authorization
elseif(isset($_GET['error'])) {
  die('Error: ' . $_GET['error']);
}

// We got a code, send it to OAuth 2.0 API to get the tokens...
elseif(isset($_GET['code'])) {
  $post_vars = http_build_query([
    'grant_type' => 'authorization_code',
    'code' => $_GET['code'],
  ]);

  $ch = curl_init();
  curl_setopt($ch, CURLOPT_USERPWD, $client_id . ":" . $client_secret);

  curl_setopt($ch, CURLOPT_URL, 'https://oauth.seven.io/token');
  curl_setopt($ch, CURLOPT_POST, 1);
  curl_setopt($ch, CURLOPT_POSTFIELDS, $post_vars);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

  $response = curl_exec($ch);

  curl_close ($ch);

  $token = json_decode($response);

  // You should store the tokens here in order to make API calls
  die("Access Token: " . $token->access_token);
}