База знаний FAM/MFA+ : Интеграция посредством GraphQL API

Общие сведения

GraphQL API предоставляет сторонним приложениям гибкий интерфейс для запроса информации, содержащейся в Системе.

Данный API позволяет запрашивать ровно тот набор информации, который необходим, уменьшая число запросов к API и уменьшая сложность фильтрации и последующей обработки данных. Также GraphQL позволяет упростить подключение API к приложениям за счёт строго типизированной схемы.

Выполнение запроса

Чтобы получить данные необходимо выполнить HTTP GET-запрос на URL:

http://{host}/graphql?query={query}

где:

  • host - хост;
  • query - текст запроса.

Токен необходимо передавать в header: bearer_token

Пример запроса:

https://localhost:44382/graphql?query=query {users{edges{node{id username}}}}

Пример ответа:

{
    "data": {
        "users": {
            "edges": [
                {
                    "node": {
                        "id": "2eac9e38-f0cd-4ce0-9b72-d61c9a1389dd",
                        "username": "test"
                    }
                },
                {
                    "node": {
                        "id": "9d806522-5492-4dbb-8d96-f77e04f6c0dd",
                        "username": "avanpost"
                    }
                }
            ]
        }
    }
}

Аутентификация

Аутентификация осуществляется посредством Access Token, передаваемого в запросе.

Для получения Access Token следует использовать один из двух методов:

  • Аутентификацию посредством OAuth 2.0 Client Credentials Flow;
  • Аутентификацию посредством OAuth 2.0 Password Flow.

Получение схемы

При развёртывании API на стандартном URI /graphql на том же хосте, что и веб-интерфейс аутентификации Системы, актуальную схему можно получить запросом:

curl -H "Authorization: bearer token" https://host/graphql

где:

  • token - актуальный OAuth Access Token.;
  • host - хост, на котором размещается сервис.

Более подробно способы получения и работы со схемой описаны в https://graphql.org/learn/introspection/ .

Структура данных

AccessObject { # объект доступа
	id
	code
	name
	type
	category
	appId
	accessObjectPrivileges {
		...
	}
}

AccessobjectPrivilege { # право в объекте доступа
	id
	code
	name
}

Application { # приложение
	id
	name
	enabled
	visible
	type
    … # еще много всего
	accessObjects {
		...
	}
}

Group { # группа 
	id
	name
	description
	…
	groupApplications {
		...
	}
}

Role { # роль
	id
	name
	type
	description
	accessRolePrivileges { # = AccessobjectPrivilege  
		...
	}
}

UserPinnedToken { # смарт карты
	id
	tokenType
	serialNumber
	vendor
	model
	tokenLabel
	pinRequired
}

UserCustomAttribute { # доп.атрибут
	id
	value
	userId
	attrId
}

User { # пользователь
	id
	username
	email
	firstname
	lastname
	middlename
	isLocked
	active
	…
	userCustomAttributes {
		...
	}
	userRoles {
		...
	}
	userGroups {
		...
	}
	userPinnedTokens {
		...
	}
}

Примеры запросов

Роли (AccessRole)

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

query {
  roles {
    edges {
      node {
        id
        name
        type
        description
        accessRolePrivileges {
          privilege {
            id
            code
            name
		  }
        }
      }
    }
  }
}


Группы (Groups)

Запрос для получения списка групп:

query {
  groups {
    edges {
      node {
        id
        name
        groupApplications {
          id
          name
          accessObjects {
            id
            name
            accessObjectPrivileges {
              id
              code
              name
            }
          }
        }
      }
    }
  }
}

Приложения (Applications)

Запрос для получения списка приложений:

query {
  applications {
    edges {
      node {
        id
        name
        type
        enabled
        visible
        accessObjects {
          id
          name
          type
          category
          code
          accessObjectPrivileges {
            id
            code
            name
          }
        }
      }
    }
  }
}

Пользователи (Users)

Запрос для получения списка пользователей:

query {
  users {
    edges {
      node {
        id
        username
        email
        firstname
        lastname
        middlename
        isLocked
        phoneNumberConfirmed
        phoneNumberUnconfirmed
        preferredLanguage
        userPinnedTokens {
          id
          serialNumber
          vendor
          tokenLabel
          pinRequired
          tokenType
        }
        userCustomAttributes {
          id
          attrId
          userId
          value
        }
        userGroups {
          id
          name
          description
          groupApplications {
            id
            name
            type
            accessObjects {
              id
              name
              accessObjectPrivileges {
                privilege {
                  id
                  code
                  name
                }
              }
            }
          }
        }
        userRoles {
          id
          name
          accessRolePrivileges {
            privilege {
              id
              code
              name
            }
          }
        }
      }
    }
  }
}

Запрос поиска пользователя по уникальному идентификатору:

query {
  users (where: {id: {eq: "9d806522-5492-4dbb-8d96-f77e04f6c0dd"}}) {
    edges {
      node {
        id
        username
        email
        firstname
        lastname
        middlename
        isLocked
        phoneNumberConfirmed
        phoneNumberUnconfirmed
        preferredLanguage
      }
    }
  }
}

Запрос поиска пользователя по имени пользователя:

query {
  users (where: {username: {eq: "avanpost"}}) {
    edges {
      node {
        id
        username
        email
        firstname
        lastname
        middlename
        isLocked
        phoneNumberConfirmed
        phoneNumberUnconfirmed
        preferredLanguage
      }
    }
  }
}

Запрос поиска пользователей-членов определённой группы:

query {
  users (where: {userGroups: {some: {id: {eq: "f782c15d-cf73-4dd4-b923-7331765a2fb8"}}}}) {
    edges {
      node {
        id
        username
        email
        firstname
        lastname
        middlename
        isLocked
        phoneNumberConfirmed
        phoneNumberUnconfirmed
        preferredLanguage
      }
    }
  }
}

Запрос поиска пользователей по роли:

query {
  users (where: {userRoles: {some: {id: {eq: "edb7e968-547d-4773-80e1-8712998e62da"}}}}) {
    edges {
      node {
        id
        username
        email
        firstname
        lastname
        middlename
        isLocked
        phoneNumberConfirmed
        phoneNumberUnconfirmed
        preferredLanguage
        userRoles {
          id
          name
        }
      }
    }
  }
}

Запрос  поиска пользователей, у которых есть доступ к приложению:

query {
  users (where: {userGroups: {some: {groupApplications: {some: {id: {eq: "21aa4df5-74ea-4176-acf0-53b84aa164d1"}}}}}}) {
    edges {
      node {
        id
        username
        email
        firstname
        lastname
        middlename
        isLocked
        phoneNumberConfirmed
        phoneNumberUnconfirmed
        preferredLanguage
        userRoles {
          id
          name
        }
      }
    }
  }
}


Запрос на получение дополнительных атрибутов пользователя по его идентификатору:

query {
  userCustomAttributes (uid:"9d806522-5492-4dbb-8d96-f77e04f6c0dd") {
    id
    value
  }
}

Запрос на получение ролей пользователя по его идентификатору:

query {
  userRoles (uid:"9d806522-5492-4dbb-8d96-f77e04f6c0dd") {
    id
    name
  }
}

Запрос на получение групп пользователя по его идентификатору:

query {
  userGroups (uid:"9d806522-5492-4dbb-8d96-f77e04f6c0dd") {
    id
    name
  }
}

Запрос на получение перечня приложений пользователя по его идентификатору:

query {
  userApplications (uid:"9d806522-5492-4dbb-8d96-f77e04f6c0dd") {
    id
    name
    accessObjects {
      id
      accessObjectPrivileges {
        id
      }
    }
  }
}