Микросервис auth

В статье описываются логика работы, функции, конфигурация и методы микросервиса auth.

Микросервис предоставляет функциональные возможности по аутентификации и авторизации пользователя.

Доступ к микросервису предоставляется по запросу.

Логика работы микросервиса

В работе микросервиса участвуют следующие сущности:

Зарегистрированный клиент OAuth2 - содержит информацию в виде ключей доступа и конфигурации для клиента (ID, секрет и имя клиента, дата регистрации, допустимые методы аутентификации клиента, типы предоставления доступа, разрешенные области действия, настройки клиента и токена)
Авторизация OAuth2 - содержит информацию о предоставлении доступа пользователю или организации (ID клиента, тип предоставления авторизации, разрешенные области действия, текущее состояние, данные о токенах - тип, разрешенные области действия, значение, время выдачи, истечение срока действия, метаданные)
User Identity - содержит информацию о сущности пользователя с точки зрения аутентифкации (id, телефон, поддерживаемые типы аутентификации)

Аутентификация и авторизация

К сервису подключен механизм авторизации, доступ можно получить используя креды клиента (Basic Authorization).

Для того чтобы сгенерировать ключи доступа, нужно вызвать эндпоинт POST /api/auth/oauth2/v1/tokens. Для отправки необходимы:

креды клиента в загаловке Authorization, тип Basic, постоянное значение для приложения;
указать каким способом пользователь получит ключ доступа (возможные значения: phone_otp, password, refresh_token);
данные в зависимосмости от того, какой выбран способ.

Service context path

/api/auth/

Настройки и параметры конфигурации микросервиса

Параметры конфигурации указываются в Vault.

Vault используется на нашей платформе в качестве хранилища всех конфигураций развертывания.

По умолчанию


      {
"env": {
    "DB_HOST": "хост для подключения к БД",
    "DB_PASSWORD": "пароль для обычного пользователя БД",
    "DB_PASSWORD_MIGRATION": "пароль пользователя БД, выполняющего миграцию",
    "ENABLE_DEBUG": "возможность отладки ("YES"/"NO")",
    "JAVA_XMS": "XXm",
    "JAVA_XMX": "YYYm",
    "KAFKA_BROKER_ADDRESS": "адрес брокера Kafka",
    "OTP_VERIFICATION_TOKEN_ISSUER": "otp-verifier",
    "OTP_VERIFICATION_TOKEN_PUBLIC_KEY": "публичный ключ otp",
    "REDIS_HOST": "хост для подключения к Redis",
    "REDIS_PORT": "порт для подключения к Redis",
    "SPRING_OAUTH_SERVER_CLIENTS": "клиенты SPRING",
    "SPRING_OAUTH_SERVER_JWKS_PRIVATE_KEY": "закрытый ключ JWKS для SPRING",
    "SPRING_OAUTH_SERVER_JWKS_PUBLIC_KEY": "открытый ключ JWKS для SPRING",
    "SPRING_OAUTH_SERVER_JWKS_RSA_KEY_ID": "RSA_KEY_ID JWKS для SPRING"
  }
}

Указываемые на каждом отдельном стенде


      // пример для тестового стенда 
{
  "env": {

    "KAFKA_BROKER_ADDRESS": "сокет_для_брокера_kafka",
    "POSTGRES_HOST": "адрес_хоста",
    "POSTGRES_MIGRATION_PASSWORD": "пароль",
    "POSTGRES_PASSWORD": "пароль",
    "REDIS_HOST": "хост_redis",
    "REDIS_PORT": "порт_redis",
    "SPRING_OAUTH_SERVER_INTERNAL_CLIENT_ID": "client_id",
    "SPRING_OAUTH_SERVER_INTERNAL_CLIENT_SECRET": "client_secret"
  }
}


// пример для мастер стенда 
{
  "env": {
    "POSTGRES_HOST": "адрес_хоста",
    "POSTGRES_MIGRATION_PASSWORD": "пароль",
    "POSTGRES_PASSWORD": "пароль",
    "SPRING_OAUTH_SERVER_INTERNAL_CLIENT_ID": "client_id",
    "SPRING_OAUTH_SERVER_INTERNAL_CLIENT_SECRET": "client_secret",
    "SPRING_OAUTH_SERVER_ISSUER": "поставщик_OAuth-сервера"
  }
}

Методы микросервиса

Создание пользователя (если к указанному им на форме регистрации/авторизации номеру телефона не привязан существующий в системе аккаунт) - POST запрос, /v1/identities

Request parameters

id - параметр тела запроса, обязательный: уникальный идентификатор для идентичности пользователя, сгенерированный Auth Orchestration Service;
phone - параметр тела запроса, обязательный: номер телефона;
email - параметр тела запроса, необязательный: адрес электронной почты, связанный с идентичностью;
metadata - параметр тела запроса, необязательный: метаданные.

Request body sample


      {
  "id": "2376e78g232109",
  "phone": "+7657765422",
  "email": "pochta@pochta.ru",
  "metadata": {
    "additionalProp1": {},
    "additionalProp2": {},
    "additionalProp3": {}
  }
}

Response sample


      {
  "id": "2376e78g232109",
  "phone": "+7657765422",
  "email": "pochta@pochta.ru",
  "metadata": {
    "additionalProp1": {},
    "additionalProp2": {},
    "additionalProp3": {}
  }
}

Response codes

200 - операция выполнена успешно, создана новая идентичность пользователя
400 - ошибка, невалидные данные (например, отсутствует обязательный параметр или он имеет неправильный формат)
409 - ошибка, идентичность с указанным номером телефона или email уже существует
500 - ошибка, Internal Server Error

Поиск пользователя в системе по номеру телефона, который был указан на форме регистрации/авторизации - GET запрос, /v1/identities/find-by-phone

Request parameters

phone - параметр тела запроса, обязательный: номер телефона, указанный на форме регистрации/авторизации

Response sample


      

{
  "id": "2376e78g232109",
  "phone": "+7657765422",
  "email": "pochta@pochta.ru"
}

Response codes

200 - операция выполнена успешно, получены данные пользователя
404 - ошибка, пользователь с таким номером телефона не найден
500 - ошибка, Internal Server Error

Получение информации об идентичности по переданному ID - GET запрос, /v1/identities/{id}

Request parameters

Отсутствуют

Response sample


      {
  "id": "2e84ec2fbf0ddb17954853e25f0301cd6d7d4b559cbb5daa411494942a490dd5",
  "phone": "+375252313132",
  "email": "string",
  "metadata": {
    "additionalProp1": {},
    "additionalProp2": {},
    "additionalProp3": {}
  }
}

Response codes

200 - операция выполнена успешно, идентичность найдена, получен JSON с данными
404 - ошибка, идентичность не найдена, возвращен JSON с ошибкой
500 - ошибка, Internal Server Error

Обновление идентичности по переданному ID - PUT запрос, /v1/identities/{id}

Request parameters

id - path-параметр, обязательный: идентификационный номер идентичности

Request body sample


      {
  "id": "2e84ec2fbf0ddb17954853e25f0301cd6d7d4b559cbb5daa411494942a490dd5",
  "phone": "+375252313132",
  "email": "string",
  "metadata": {
    "additionalProp1": {},
    "additionalProp2": {},
    "additionalProp3": {}
  }
}

Response codes

204 - операция выполнена успешно, идентичность обновлена, тело отсутствует
404 - ошибка, идентичность не найдена, возвращен JSON с ошибкой
409 - ошибка, идентичность с указанным номером телефона или email уже существует
500 - ошибка, Internal Server Error

Удаление идентичности по переданному ID - DELETE запрос, /v1/identities/{id}

Request parameters

id - path-параметр, обязательный: идентификационный номер идентичности

Request body sample

Отсутствует. В ответе приходит только код операции, например, 204.

Response codes

204 - операция выполнена успешно, операция выполнена успешно, идентичность удалена
404 - ошибка, идентичность не найдена, возвращен JSON с ошибкой
500 - ошибка, Internal Server Error

Генерация пары токенов - POST запрос, /oauth2/v1/tokens

Request parameters

grant_type - параметр тела запроса, обязательный: тип запрашиваемого гранта: password (user credentials), refresh_token, phone_otp (phone one-time password), auth, phone_otp_token;
username - параметр тела запроса, необязательный: имя пользователя. Требуется только для grant_type=password;
password - параметр тела запроса, необязательный: токен обновления. Требуется только для grant_type=refresh_token;
refresh_token - параметр тела запроса, необязательный: токен обновления. Требуется только для grant_type=refresh_token;
phone - параметр тела запроса, необязательный: номер телефона. Требуется только для grant_type=phone_otpи grant_type=phone_otp_token;
auth_id - параметр тела запроса, необязательный: идентификатор пользователя на основе его номера телефона, сгенерированный Auth Orchestration Service. Требуется только для grant_type=auth;
otp_verification_token - параметр тела запроса, необязательный: JWT-токен, подтверждающий, что пользователь успешно прошел проверку OTP. Используется только в grant_type=phone_otp_token.

Request body sample


      {
  "grant_type": "phone_otp_token",
  "phone": "+375257568549",
  "otp_verification_token": "BHFDKFDJFD123JDSH3212F"
}

Response sample


      {
  "access_token": "access-token-value"     // Токен доступа для аутентификации запросов к защищенным ресурсам
   ,"refresh_token": "refresh-token-value" // Токен обновления для получения нового токена доступа
   ,"token_type": "Bearer"                 // Тип токена
   ,"expires_in": 1800                     // Время в секундах до истечения срока действия токена доступа
   ,"refresh_expires_in": 18600            // Время в секундах до истечения срока действия токена обновления
 }

Response codes

200 - операция выполнена успешно, создана новая пара токенов
400 - ошибка, невалидные данные (например, отсутствуют требуемые параметры для указанного grant_type, недопустимое или неподдерживаемое значение grant_type, недопустимые учетные данные клиента, недопустимый грант).
500 - ошибка, Internal Server Error

Проверка валидности токена доступа на основе входного параметра token, переданного от SAP Hybris, - POST запрос, /oauth2/v1/introspect

Request parameters

token - параметр тела запроса, обязательный: токен доступа, который необходимо проверить на валидность.

Request body sample


      // Формат: application/x-www-form-urlencoded
token=access-token-value

Response sample


      {
  "active": true         // Флаг, указывающий на валидность токена: true - валиден, false - недействителен
   ,"sub": "user-id"     // Идентификатор пользователя, на которого выдан токен (auth_id)
   ,"aud": [
    "client-id"          // Массив идентификаторов клиентов, для которых предназначен токен
   ],
  "userInfo": {
    "userId": "user-id"  // Объект, содержащий идентификатор пользователя, на которого выдан токен
   },
  "nbf": 1733127540                               // Время, с которого токен становится действительным
   ,"iss": "http://auth:8080/api/auth"            // URI, указывающий на издателя токена
   ,"exp": 1733135435                             // Время истечения срока действия токена
   ,"iat": 1733127540                             //Время последней активности токена
   ,"jti": "efaa761e-2ee7-4c6f-9ba6-f0d0890f80eb" // Уникальный идентификатор токена
   ,"clientId": "client-id"                       // Идентификатор клиента, который запрашивал токен
   ,"tokenType": "Bearer"                         // Тип токена (например, "Bearer")
 }

Response codes

200 - операция выполнена успешно, получена информация о валидности / недействительности токена
400 - ошибка, невалидные данные (например, отсутствует обязательный параметр token).
500 - ошибка, Internal Server Error

Проверка валидности токена доступа на основе входного параметра token, переданного от SAP Hybris, - gRPC, /oauth2/v1/introspect

Request parameters

token - параметр тела запроса, обязательный: токен доступа, который необходимо проверить на валидность.

Request body sample


      // Формат: application/x-www-form-urlencoded
token=access-token-value

Response sample


      {
    "aud": [
        "webshop-master.apps.digitalchief"
    ],
    "active": true,
    "sub": "7961989b-3898-44d9-a7f1-6da2fe3a5bd8",
    "userInfo": {
        "userId": "7961989b-3898-44d9-a7f1-6da2fe3a5bd8"
    },
    "nbf": "1735539714",
    "iss": "http://auth:8080/api/auth/",
    "exp": "1735550514",
    "iat": "1735539714",
    "jti": "e553d3c7-fc7e-4198-87ae-04f7f6cedda5",
    "clientId": "webshop-master.apps.digitalchief",
    "tokenType": "Bearer"
}

Response codes

0 OK - операция выполнена успешно, получена информация о валидности / недействительности токена
13 INTERNAL - ошибка, невалидные данные (например, отсутствует обязательный параметр token)

Отзыв токена доступа или обновления, - POST запрос, /oauth2/v1/revoke

Request parameters

token - параметр тела запроса, обязательный: токен доступа или обновления, который необходимо отменить

Request body sample


      // Формат: application/x-www-form-urlencoded
token=access-token-value

Response sample


      {
"message": "The token was successfully revoked."
}

Response codes

200 - операция выполнена успешно, токен отозван
400 - ошибка, невалидные данные (например, отсутствует обязательный параметр token или предоставленный токен имеет неправильный формат / недействителен)

Получение JSON Web Key Set (JWKS), содержащего открытые ключи, используемые для проверки подписей токенов, выданных сервером авторизации - GET запрос, /v1/jwks

Request parameters

Отсутствуют

Response sample


      {
  "keys": [
    {
      "kty": "RSA",
      "kid": "1",
      "n": "...",
      "e": "..."
    }
  ]
}

Response codes

200 - операция выполнена успешно, JWKS получены

Связанные статьи

Микросервисы