Авторизация в сервисах Райффайзен Банка

Варианты

• Паблик

Операции API

{
  "operationId": "authorize",
  "summary": "Запрос на авторизацию (Code Flow)",
  "tags": [
    "Аутентификация"
  ],
  "description": "Запрос инициирует процесс аутентификации пользователя \n(формируется клиентским приложением).",
  "parameters": [
    {
      "name": "response_type",
      "in": "query",
      "required": true,
      "description": "Тип ответа, для Code Flow необходимо передавать `code`.",
      "schema": {
        "type": "string",
        "enum": [
          "code"
        ],
        "example": "code"
      }
    },
    {
      "name": "client_id",
      "in": "query",
      "required": true,
      "description": "Идентификатор клиента (выдается Райффайзен Банком).",
      "schema": {
        "type": "string",
        "example": "a12b123b-0a12-3b4c-123a-12a3456789b1"
      }
    },
    {
      "name": "redirect_uri",
      "in": "query",
      "required": true,
      "description": "URI, на который будет перенаправлен пользователь после успешной авторизации.\nДолжен быть зарегистрирован в сервисе аутентификации Райффайзен Банка для вашего `client_id`.",
      "schema": {
        "type": "string",
        "format": "uri",
        "example": "https://example.ru/callback"
      }
    },
    {
      "name": "scope",
      "in": "query",
      "required": true,
      "description": "Запрашиваемые привилегии доступа. \nЗначения указываются через пробел, обязательно должно быть указано значение openid.",
      "schema": {
        "type": "string",
        "example": "openid profile email phone"
      }
    },
    {
      "name": "state",
      "in": "query",
      "required": true,
      "description": "Строка для защиты от CSRF-атак, генерируется клиентом.\nВозвращается в неизменном виде после авторизации.",
      "schema": {
        "type": "string",
        "example": "random-state-123"
      }
    },
    {
      "name": "nonce",
      "in": "query",
      "required": true,
      "description": "Строка для защиты от replay-атак, генерируется клиентом.\nДобавляется в ID-токен.",
      "schema": {
        "type": "string",
        "example": "random-nonce-456"
      }
    },
    {
      "name": "code_challenge",
      "in": "query",
      "required": true,
      "description": "Хэш значения `code_verifier` по стандарту PKCE (RFC 7636):\n`BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))`.",
      "schema": {
        "type": "string",
        "example": "ewliMz7SBtJdHLlNuuJLdzu-gRs2olJQ24AQ8GTS6Qo"
      }
    },
    {
      "name": "code_challenge_method",
      "in": "query",
      "required": true,
      "description": "Метод хэширования `code_verifier`. Поддерживается только `S256`.",
      "schema": {
        "type": "string",
        "enum": [
          "S256"
        ],
        "example": "S256"
      }
    }
  ],
  "responses": {
    "303": {
      "description": "Редирект для продолжения аутентификации пользователя.",
      "headers": {
        "Location": {
          "description": "URI страницы для ввода аутентификационных данных пользователя (/signin)",
          "schema": {
            "type": "string",
            "example": "/signin"
          }
        },
        "Set-Cookie": {
          "description": "Куки (например, SESSION, FLASH, Prefer-Auth-Type, Raiff-Device-Id), \nкоторые сервис аутентификации отправляет клиенту для корректного отображения форм аутентификации.",
          "schema": {
            "type": "string"
          }
        }
      }
    },
    "400": {
      "description": "Запрос некорректен.",
      "content": {
        "text/plain": {
          "schema": {
            "type": "string"
          },
          "examples": {
            "MissingClientId": {
              "summary": "не указан client_id",
              "value": "missing client id"
            },
            "MissingRedirectionUri": {
              "summary": "не указан redirect_uri",
              "value": "missing redirection URI"
            },
            "MismatchingRedirectionUri": {
              "summary": "указанный redirect_uri не зарегистрирован для данного client_id",
              "value": "mismatching redirection URI for given client"
            }
          }
        }
      }
    }
  }
}

{
  "operationId": "signin",
  "summary": "Форма аутентификации",
  "tags": [
    "Аутентификация"
  ],
  "description": "Запрос html-страницы с формой для ввода \nаутентификационных данных пользователя (логина и пароля или номера телефона),\nотправляется браузером автоматически в результате выполнения запроса GET /authorize.",
  "parameters": [
    {
      "name": "SESSION",
      "in": "cookie",
      "required": true,
      "description": "Служебная кука сервиса аутентификации, \nзадается сервисом аутентификации в результате выполнения запроса GET /authorize.",
      "schema": {
        "type": "string"
      }
    },
    {
      "name": "FLASH",
      "in": "cookie",
      "required": false,
      "description": "Служебная кука сервиса аутентификации, \nзадается сервисом аутентификации в результате взаимодействия с пользователем.",
      "schema": {
        "type": "string"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Форма ввода аутентификационных данных.",
      "headers": {
        "Set-Cookie": {
          "description": "Куки (SESSION, FLASH, csrfToken), \nкоторые сервис аутентификации отправляет клиенту для корректного отображения форм аутентификации.",
          "schema": {
            "type": "string"
          }
        }
      }
    },
    "303": {
      "description": "Редирект для продолжения аутентификации пользователя.",
      "headers": {
        "Location": {
          "description": "URI клиентского приложения для перезапуска процесса аутентификации \n(в случае длительного бездействия пользователя или при передаче некорректных параметров в куках).",
          "schema": {
            "type": "string",
            "example": "https://example.ru/callback"
          }
        }
      }
    }
  }
}

{
  "operationId": "login",
  "summary": "Проверка логина и пароля",
  "tags": [
    "Аутентификация"
  ],
  "description": "Запрос на проверку введенных пользователем логина и пароля.",
  "requestBody": {
    "content": {
      "application/x-www-form-urlencoded": {
        "schema": {
          "type": "object",
          "properties": {
            "login": {
              "description": "Логин пользователя \n(в качестве логина также может использоваться email или номер телефона).",
              "type": "string"
            },
            "password": {
              "description": "Пароль пользователя.",
              "type": "string"
            },
            "locale": {
              "description": "Локаль выбранная пользователем на форме аутентификации.",
              "type": "string",
              "enum": [
                "ru",
                "en"
              ],
              "example": "ru"
            },
            "g-recaptcha-response": {
              "description": "Решение Google reCAPTCHA на форме аутентификации.\nКапча требуется (и отображается на форме аутентификации) в том случае, \nкогда сервис аутентификации фиксирует большое количество неудачных попыток входа \n(по одному логину или с одного IP-адреса).",
              "type": "string"
            }
          },
          "required": [
            "login",
            "password"
          ]
        }
      }
    }
  },
  "parameters": [
    {
      "name": "csrfToken",
      "in": "query",
      "required": true,
      "description": "CSRF-токен, который был указан на форме аутентификации \n(возвращается в результате выполнения запроса GET /signin).",
      "schema": {
        "type": "string"
      }
    },
    {
      "name": "SESSION",
      "in": "cookie",
      "required": true,
      "description": "Служебная кука сервиса аутентификации, \nзадается сервисом аутентификации в результате выполнения запроса GET /signin.",
      "schema": {
        "type": "string"
      }
    },
    {
      "name": "FLASH",
      "in": "cookie",
      "required": false,
      "description": "Служебная кука сервиса аутентификации, \nзадается сервисом аутентификации в результате взаимодействия с пользователем.",
      "schema": {
        "type": "string"
      }
    }
  ],
  "responses": {
    "303": {
      "description": "Редирект для завершения аутентификации пользователя.",
      "headers": {
        "Location": {
          "description": "В зависимости от результата проверки пароля возвращается разный URI с разными параметрами.\n\nЕсли пользователь успешно аутентифицирован, то возвращается\nURI клиентского приложения (указанный в параметре `redirect_uri` запроса GET /authorize)\nс параметрами для завершения процесса аутентификации:\n\n- `code` (Authorization Code для обмена на токены)\n- `state` (должен совпадать с тем значением, что было указано в запросе GET /authorize).\n\nВ случае ошибки возвращается URI на форму аутентификации (/signin) для повторной попытки.",
          "schema": {
            "type": "string",
            "example": "https://example.ru/callback?code=yl4jA9kJFj5qQSRdoCRlYId9yAxfBDZy-MhfKI4bpeI&state=random-state-123"
          }
        },
        "Set-Cookie": {
          "description": "Куки (например, SESSION, FLASH, csrfToken), \nкоторые сервис аутентификации отправляет клиенту для корректного отображения форм аутентификации.",
          "schema": {
            "type": "string"
          }
        }
      }
    }
  }
}

{
  "operationId": "token",
  "summary": "Получение и обновление токенов",
  "tags": [
    "Аутентификация"
  ],
  "description": "Получение токенов по Authorization Code (`grant_type=authorization_code`) \nили обновление токенов по Refresh Token (`grant_type=refresh_token`).\n\nТребуется Basic Authentication для клиентского приложения: Authorization: Basic Base64(client_id:client_secret).",
  "security": [
    {
      "basicAuth": []
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/x-www-form-urlencoded": {
        "schema": {
          "type": "object",
          "properties": {
            "grant_type": {
              "type": "string",
              "description": "Тип взаимодействия, в рамках которого происходит получение токенов:\nauthorization_code для получения токенов по Authorization Code (Code Flow)\nrefresh_token для получения новых токенов по Refresh токену",
              "enum": [
                "authorization_code",
                "refresh_token"
              ],
              "example": "authorization_code"
            },
            "code": {
              "type": "string",
              "description": "Authorization Code (обязательный параметр для grant_type=authorization_code), \nзначение переданное в параметре code после успешной аутентификации пользователя и \nперенаправлении на redirect_uri клиентского приложения.",
              "example": "yl4jA9kJFj5qQSRdoCRlYId9yAxfBDZy"
            },
            "redirect_uri": {
              "type": "string",
              "description": "URI клиентского приложения (обязательный параметр для grant_type=authorization_code).\nДолжен совпадать со значением redirect_uri из запроса GET /authorize.",
              "format": "uri"
            },
            "code_verifier": {
              "type": "string",
              "description": "Случайная строка (обязательный параметр для grant_type=authorization_code), \nкоторая согласно стандарту PKCE (RFC 7636) использовалась для генерации \nзначения code_challenge из запроса GET /authorize."
            },
            "refresh_token": {
              "type": "string",
              "description": "Refresh Token (обязательный параметр для grant_type=refresh_token)."
            }
          },
          "required": [
            "grant_type"
          ]
        },
        "examples": {
          "AuthorizationCode": {
            "summary": "Получение токенов по Authorization Code",
            "value": {
              "grant_type": "authorization_code",
              "code": "yl4jA9kJFj5qQSRdoCRlYId9yAxfBDZy",
              "code_verifier": "ACbrszxo9MTPRDHBej_Hyjftt9jc2r2aQZurfomS_ct",
              "redirect_uri": "https://example.ru/callback"
            }
          },
          "RefreshToken": {
            "summary": "Обновление токенов по Refresh Token",
            "value": {
              "grant_type": "refresh_token",
              "refresh_token": "your_refresh_token"
            }
          }
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Успешно выданы токены",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "access_token": {
                "type": "string",
                "description": "Access Token в формате JWT."
              },
              "token_type": {
                "type": "string",
                "enum": [
                  "Bearer"
                ],
                "description": "Тип токена (всегда `Bearer`).",
                "example": "Bearer"
              },
              "refresh_token": {
                "type": "string",
                "description": "Refresh Token для обновления токенов.\nПри обновлении токенов по Refresh Token будет выдан новый Refresh Token с таким же сроком действия."
              },
              "id_token": {
                "type": "string",
                "description": "ID Token в формате JWT с информацией о пользователе."
              }
            }
          },
          "example": {
            "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
            "token_type": "Bearer",
            "refresh_token": "d8f7a6b5c4e3f2a1b0c9d8e7f6a5b4c3",
            "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
          }
        }
      }
    },
    "400": {
      "description": "Некорректный запрос",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ErrorWithDescriptionResponseDTO"
          },
          "examples": {
            "InvalidRequest": {
              "summary": "Некорректный запрос",
              "value": {
                "error": "invalid_request",
                "error_description": "Invalid request"
              }
            }
          }
        }
      }
    },
    "401": {
      "description": "Ошибка авторизации",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ErrorWithDescriptionResponseDTO"
          },
          "examples": {
            "InvalidRequest": {
              "summary": "Некорректный Refresh токен или запрос выполняется слишком часто",
              "value": {
                "error": "invalid_request",
                "error_description": "Invalid request"
              }
            },
            "InvalidClient": {
              "summary": "Некорректны авторизационные данные клиента (в заголовке Authorization)",
              "value": {
                "error": "invalid_client",
                "error_description": "Client authentication failed"
              }
            }
          }
        }
      }
    }
  }
}

Схемы и примеры

{
  "securitySchemes": {
    "basicAuth": {
      "type": "http",
      "scheme": "basic",
      "description": "Basic Authentication: `Authorization: Basic Base64(client_id:client_secret)`.\n\nПример генерации:\n```\nclient_id = a12b123b-0a12-3b4c-123a-12a3456789b1\nclient_secret = clientsecret7Fjfp0ZBr1KtDRbnfV\nBase64(client_id:client_secret) = YTEyYjEyM2ItMGExMi0zYjRjLTEyM2EtMTJhMzQ1Njc4OWIxOmNsaWVudHNlY3JldDdGamZwMFpCcjFLdERSYm5mVg\n```"
    }
  },
  "schemas": {
    "ErrorWithDescriptionResponseDTO": {
      "type": "object",
      "properties": {
        "error": {
          "type": "string"
        },
        "error_description": {
          "type": "string"
        }
      },
      "required": [
        "error",
        "error_description"
      ]
    }
  }
}