Библиотеки
QAuthModule

QAuthModule

QAuthModule позволяет использовать авторизацию в приложении.

С чего начать

Для начала, убедитесь в том, что конфигурация приложения содержит заполненное поле конфигурацииauth. Пример конфигурации для стандартного режима авторизации:

{
  "auth": {
    "service": "default",
    "options": {
      "excludeUrlsFromAuthorization": [
        "assets/*"
      ],
      "authDataServiceConfig": {
        "urls": {
          "base": "/api"
        }
      }
    }
  }
}

Установите модуль командой:

npm i @diasoft/qpalette-auth

Далее подключите модуль вAppModuleвашего приложения, передав вforRoot()необходимую конфигурацию:

import { QCoreService } from '@diasoft/qpalette-core';
import { QAuthModule } from '@diasoft/qpalette-auth';
 
@NgModule({
  ...
  imports: [
    QAuthModule.forRoot(QCoreService.config.auth),
  ]
})
export class AppModule {
  ...
}

В данном случае вforRoot()передаётся конфигурация из рутового приложения (см. конфигурацию выше).

В случае, если есть необходимость протестировать работу веб-компонента без рутового приложения, передайте вforRoot()непосредственно сам объект конфигурации.

Структура объекта конфигурации приведена ниже (см. полеauthконфигурации):

{
  "service": "default",
  "options": {
    "authDataServiceConfig": {
      "urls": {
        "base": "https://wow",
        "login": "/oauth/login",
        "refreshToken": "/oauth/refresh"
      }
    }
  }
}

При этом полный URL формируется согласно правилу:<базовый URL>/<url запроса>. Например, для примера выше будет сформированы следующие URL:

  • login: https://wow/oauth/login.
  • refreshToken: https://wow/oauth/refresh.

Базовый URL формируется на основе параметра конфигурацииurls -> base, который представляет из себя шаблонную строку в формате, описанном в статье: QUrlService

Все поляauthDataServiceConfigнеобязательные. ПараметрыloginиrefreshTokenпо умолчанию принимают следующие значения:

  • login: /mdpauth/mdpauth/oauth/token
  • refreshToken: /mdpauth/mdpauth/oauth/token

Подстановка заголовков авторизации

В результате подключения модуля по инструкции выше любые HTTP-запросы к сервисам будут снабжаться заголовкамиAuthorization: Bearer ..., где вместо...будет подставлен access-токен, полученный в результате аутентификации.

Алгоритм работы:

  • Если access-токен действителен, он подставляется в заголовки запросов.
  • В случае ошибки 401, если refresh-токен действителен, делается запрос на обновление ключей доступа.
    • В случае успеха делается повторный HTTP-запрос к сервису, который ранее был отклонён с ошибкой 401, но уже с новым заголовком авторизации.
    • В случае ошибки в результате запроса на обновление ключей выполняется выход пользователя из системы.
  • В случае, если access-токен и refresh-токен устарели, выполняется выход пользователя из системы.

Отключение авторизации для заданных URL-адресов

В настройках модуля присутствует параметрexcludeUrlsFromAuthorization, который принимает на вход список (абсолютных) URL, для которых не нужно включать авторизацию. Можно использовать маску, например:/service/*(все адреса, начинающиеся на/service/, будут исключены из процесса авторизации).

Пример использования:

{
  "service": "default",
  "options": {
    "excludeUrlsFromAuthorization": [
      "*/service/*"
    ]
  }
}

В данном случае будут проигнорированы все URL, имеющие в своём составе/service/, например:

http://localhost/service/
domain.name/service/
/some/long/service/url

Режим отладки

Если наблюдаются проблемы с авторизацией - можно включить режим подробного логирования, установив параметрoptions.logLevelв значениеdebug:

{
  "options": {
    "logLevel": "debug"
  }
}

После этого вы сможете увидеть детализацию всех действий модуля авторизации в консоли браузера.

Работа с KeyCloak

При работе с KeyCloak нужно определить следующую конфигурацию:

{
  "service": "KeyCloak",
  "options": {
    "excludeUrlsFromAuthorization": [
      "assets/*"
    ],
    "refreshTokenPeriodically": true,
    "keycloak": {
      "config": {
        "url": "https://login.diasoft.ru/auth",
        "realm": "your-realm",
        "clientId": "your-client-id"
      }
    }
  }
}

При этом определив параметрыurl,realmиclientIdв соответствии с настройками, выданными вам администратором сервера Keycloak.

Если флагrefreshTokenPeriodicallyустановлен в значениеtrue, приложение будет выполнять регулярное обновление токенов доступа при истечении срока их жизни. По умолчанию, функция выключена.

Работа с Flexterra

Для работы с платформой Flexterra нужно определить следующую конфигурацию:

{
  "service": "flexterra",
  "options": {
    "excludeUrlsFromAuthorization": [
      "assets/*"
    ]
  }
}

Если необходимо переопределить адреса API-сервисов платформы Flexterra, можно это сделать с помощью параметраoptions.api(в качестве примера приведены адреса по умолчанию):

{
  "options": {
    "api": {
      "urls": {
        "base": "/webmvc",
        "login": "/api/auth",
        "logout": "/api/logout",
        "getUserSettings": "/api/pageflow/systemFAB/userSettings",
        "dsCall": "/api/dscall"
      }
    }
  }
}

Поляoptions.logLevelиoptions.excludeUrlsFromAuthorizationработают так же, как и во всех других режимах в авторизации.

QAuthService

Сервис авторизации позволяет получить информацию о вошедшем в систему пользователе или вызвать события авторизации вручную.

Вы можете подключить сервис в любом месте приложения (для этого выполните инструкции по подключения модуляQAuthModule, приведённые выше):

import { QAuthService } from '@diasoft/qpalette-auth';
 
constructor(private readonly authService: QAuthService) {}

Далее приводится список методов сервиса, которыми вы можете воспользоваться.

isAuthenticated(): boolean

Возвращает true, если пользователь авторизован в системе.

getUserInfo(): QUserInfo | null

Возвращает информацию о текущем пользователе, либоnull, если пользователь не авторизован. СтруктураQUserInfoприведена ниже:

{
  userName?: string;
  roles?: string[];
}