API 文档

API 文档默认已经集成在代码里面, 部署完成后可以通过下面的方式进行访问

API 访问

VersionAccess methodexample
< 2.0.0http://<url>/docshttp://192.168.244.144/docs
>=2.0.0http://<url>/api/docs/http://192.168.244.144/api/docs/
>=2.6.0http://<url>/api/docs/http://192.168.244.144/api/docs/

版本小于 v2.6 需要打开 debug 模式

  1. vi config.yml
  1. ...
  2. # 如果版本更低的话，配置文件是 config.py
  3. # Debug = true
  4. DEBUG: true

api_swagger

API 认证

JumpServer API 支持的认证有以下几种方式

  1. Session         登录后可以直接使用 session_id 作为认证方式  
  2. Token           获取一次性 Token，该 Token 有有效期, 过期作废  
  3. Private Token   永久 Token  
  4. Access Key      对 Http Header 进行签名

Session

用户通过页面后登录，cookie 中会存在 sessionid, 请求时同样把 sessionid 放到 cookie 中

Token

  1. curl -X POST http://localhost/api/v1/authentication/auth/ \
  2.      -H 'Content-Type: application/json' \
  3.      -d '{"username": "admin", "password": "admin"}'
  1. # pip install requests
  2. import requests, json
  4. jms_url  = 'https://demo.jumpserver.org'
  5. username = 'admin'
  6. password = 'admin'
  8. def get_token():
  9.     url        = jms_url + '/api/v1/authentication/auth/'
  10.     query_args = {
  11.         "username": username,
  12.         "password": password
  13.     }
  14.     response = requests.post(url, data=query_args)
  15.     return json.loads(response.text)['token']
  17. def get_user_info():
  18.     url      = jms_url + '/api/v1/users/users/'
  19.     token    = get_token()
  20.     headers  = { "Authorization": 'Bearer ' + token }
  21.     response = requests.get(url, headers=headers)
  22.     print(json.loads(response.text))
  24. get_user_info()

Private Token

  1. docker exec -it jms_core /bin/bash
  2. cd /opt/jumpserver/apps
  3. python manage.py shell
  4. from users.models import User
  5. u = User.objects.get(username='admin')
  6. u.create_private_token()

已经存在 private_token, 可以直接获取即可

  1. u.private_token

以 PrivateToken: 937b38011acf499eb474e2fecb424ab3 为例:

  1. curl -H 'Authorization: Token 937b38011acf499eb474e2fecb424ab3' \
  2.      -H "Content-Type:application/json" http://demo.jumpserver.org/api/v1/users/users/
  1. # pip install requests
  2. import requests, json
  4. jms_url   = 'https://demo.jumpserver.org'
  5. jms_token = '937b38011acf499eb474e2fecb424ab3'
  7. def get_user_info():
  8.     url      = jms_url + '/api/v1/users/users/'
  9.     headers  = { "Authorization": 'Token ' + jms_token }
  10.     response = requests.get(url, headers=headers)
  11.     print(json.loads(response.text))
  13. get_user_info()

Access Key

在 Web 页面 API Key 列表创建或获取 AccessKeyID AccessKeySecret

  1. # pip install requests drf-httpsig
  2. import requests, datetime, json
  3. from httpsig.requests_auth import HTTPSignatureAuth
  5. jms_url         = 'https://demo.jumpserver.org'
  6. AccessKeyID     = 'AccessKeyID'
  7. AccessKeySecret = 'AccessKeySecret'
  8. GMT_FORMAT      = '%a, %d %b %Y %H:%M:%S GMT'
  10. def get_auth():
  11.     signature_headers = ['(request-target)', 'accept', 'date']
  12.     auth              = HTTPSignatureAuth(key_id=AccessKeyID, secret=AccessKeySecret, algorithm='hmac-sha256', headers=signature_headers)
  13.     return auth
  15. def get_user_info():
  16.     url     = jms_url + '/api/v1/users/users/'
  17.     auth    = get_auth()
  18.     headers = {
  19.         'Accept': 'application/json',
  20.         'Date': datetime.datetime.utcnow().strftime(GMT_FORMAT)
  21.     }
  23.     response = requests.get(url, auth=auth, headers=headers)
  24.     print(json.loads(response.text))
  26. get_user_info()

示例

Token

  1. #!/usr/bin/env python3
  2. # -*- coding:utf-8 -*-
  4. import sys, requests, time
  6. class HTTP:
  7.     server = None
  8.     token  = None
  10.     @classmethod
  11.     def get_token(cls, username, password):
  12.         data              = {'username': username, 'password': password}
  13.         url               = "/api/v1/authentication/auth/"
  14.         res               = requests.post(cls.server + url, data)
  15.         res_data          = res.json()
  16.         if res.status_code in [200, 201] and res_data:
  17.             token         = res_data.get('token')
  18.             cls.token     = token
  19.         else:
  20.             print("获取 token 错误, 请检查输入项是否正确")
  21.             sys.exit()
  23.     @classmethod
  24.     def get(cls, url, params=None, **kwargs):
  25.         url               = cls.server + url
  26.         headers           = {
  27.             'Authorization': "Bearer {}".format(cls.token)
  28.         }
  29.         kwargs['headers'] = headers
  30.         res               = requests.get(url, params, **kwargs)
  31.         return res
  33.     @classmethod
  34.     def post(cls, url, data=None, json=None, **kwargs):
  35.         url               = cls.server + url
  36.         headers           = {
  37.             'Authorization': "Bearer {}".format(cls.token)
  38.         }
  39.         kwargs['headers'] = headers
  40.         res               = requests.post(url, data, json, **kwargs)
  41.         return res
  43. class User(object):
  45.     def __init__(self):
  46.         self.id           = None
  47.         self.name         = user_name
  48.         self.username     = user_username
  49.         self.email        = user_email
  51.     def exist(self):
  52.         url               = '/api/v1/users/users/'
  53.         params            = {'username': self.username}
  54.         res               = HTTP.get(url, params=params)
  55.         res_data          = res.json()
  56.         if res.status_code in [200, 201] and res_data:
  57.             self.id       = res_data[0].get('id')
  58.         else:
  59.             self.create()
  61.     def create(self):
  62.         print("创建用户 {}".format(self.username))
  63.         url               = '/api/v1/users/users/'
  64.         data              = {
  65.             'name': self.name,
  66.             'username': self.username,
  67.             'email': self.email,
  68.             'is_active': True
  69.         }
  70.         res               = HTTP.post(url, json=data)
  71.         self.id           = res.json().get('id')
  73.     def perform(self):
  74.         self.exist()
  76. class Node(object):
  78.     def __init__(self):
  79.         self.id           = None
  80.         self.name         = asset_node_name
  82.     def exist(self):
  83.         url               = '/api/v1/assets/nodes/'
  84.         params            = {'value': self.name}
  85.         res               = HTTP.get(url, params=params)
  86.         res_data          = res.json()
  87.         if res.status_code in [200, 201] and res_data:
  88.             self.id       = res_data[0].get('id')
  89.         else:
  90.             self.create()
  92.     def create(self):
  93.         print("创建资产节点 {}".format(self.name))
  94.         url               = '/api/v1/assets/nodes/'
  95.         data              = {
  96.             'value': self.name
  97.         }
  98.         res               = HTTP.post(url, json=data)
  99.         self.id           = res.json().get('id')
  101.     def perform(self):
  102.         self.exist()
  104. class AdminUser(object):
  106.     def __init__(self):
  107.         self.id           = None
  108.         self.name         = assets_admin_name
  109.         self.username     = assets_admin_username
  110.         self.password     = assets_admin_password
  112.     def exist(self):
  113.         url               = '/api/v1/assets/admin-user/'
  114.         params            = {'username': self.name}
  115.         res               = HTTP.get(url, params=params)
  116.         res_data          = res.json()
  117.         if res.status_code in [200, 201] and res_data:
  118.             self.id       = res_data[0].get('id')
  119.         else:
  120.             self.create()
  122.     def create(self):
  123.         print("创建管理用户 {}".format(self.name))
  124.         url               = '/api/v1/assets/admin-users/'
  125.         data              = {
  126.             'name': self.name,
  127.             'username': self.username,
  128.             'password': self.password
  129.         }
  130.         res               = HTTP.post(url, json=data)
  131.         self.id           = res.json().get('id')
  133.     def perform(self):
  134.         self.exist()
  136. class Asset(object):
  138.     def __init__(self):
  139.         self.id           = None
  140.         self.name         = asset_name
  141.         self.ip           = asset_ip
  142.         self.platform     = asset_platform
  143.         self.protocols    = asset_protocols
  144.         self.admin_user   = AdminUser()
  145.         self.node         = Node()
  147.     def exist(self):
  148.         url               = '/api/v1/assets/assets/'
  149.         params            = {
  150.             'hostname': self.name
  151.         }
  152.         res               = HTTP.get(url, params)
  153.         res_data          = res.json()
  154.         if res.status_code in [200, 201] and res_data:
  155.             self.id       = res_data[0].get('id')
  156.         else:
  157.             self.create()
  159.     def create(self):
  160.         print("创建资产 {}".format(self.ip))
  161.         self.admin_user.perform()
  162.         self.node.perform()
  163.         url               = '/api/v1/assets/assets/'
  164.         data              = {
  165.             'hostname': self.ip,
  166.             'ip': self.ip,
  167.             'platform': self.platform,
  168.             'protocols': self.protocols,
  169.             'admin_user': self.admin_user.id,
  170.             'nodes': [self.node.id],
  171.             'is_active': True
  172.         }
  173.         res               = HTTP.post(url, json=data)
  174.         self.id           = res.json().get('id')
  176.     def perform(self):
  177.         self.exist()
  179. class SystemUser(object):
  181.     def __init__(self):
  182.         self.id           = None
  183.         self.name         = assets_system_name
  184.         self.username     = assets_system_username
  186.     def exist(self):
  187.         url               = '/api/v1/assets/system-users/'
  188.         params            = {'name': self.name}
  189.         res               = HTTP.get(url, params)
  190.         res_data          = res.json()
  191.         if res.status_code in [200, 201] and res_data:
  192.             self.id       = res_data[0].get('id')
  193.         else:
  194.             self.create()
  196.     def create(self):
  197.         print("创建系统用户 {}".format(self.name))
  198.         url               = '/api/v1/assets/system-users/'
  199.         data              = {
  200.             'name': self.name,
  201.             'username': self.username,
  202.             'login_mode': 'auto',
  203.             'protocol': 'ssh',
  204.             'auto_push': True,
  205.             'sudo': 'All',
  206.             'shell': '/bin/bash',
  207.             'auto_generate_key': True,
  208.             'is_active': True
  209.         }
  210.         res               = HTTP.post(url, json=data)
  211.         self.id           = res.json().get('id')
  213.     def perform(self):
  214.         self.exist()
  216. class AssetPermission(object):
  218.     def __init__(self):
  219.         self.name         = perm_name
  220.         self.user         = User()
  221.         self.asset        = Asset()
  222.         self.system_user  = SystemUser()
  224.     def create(self):
  225.         print("创建资产授权名称 {}".format(self.name))
  226.         url               = '/api/v1/perms/asset-permissions/'
  227.         data              = {
  228.             'name': self.name,
  229.             'users': [self.user.id],
  230.             'assets': [self.asset.id],
  231.             'system_users': [self.system_user.id],
  232.             'actions': ['all'],
  233.             'is_active': True,
  234.             'date_start': perm_date_start,
  235.             'date_expired': perm_date_expired
  236.         }
  237.         res               = HTTP.post(url, json=data)
  238.         res_data          = res.json()
  239.         if res.status_code in [200, 201] and res_data:
  240.             print("创建资产授权规则成功: ", res_data)
  241.         else:
  242.             print("创建授权规则失败: ", res_data)
  244.     def perform(self):
  245.         self.user.perform()
  246.         self.asset.perform()
  247.         self.system_user.perform()
  248.         self.create()
  250. class APICreateAssetPermission(object):
  252.     def __init__(self):
  253.         self.jms_url      = jms_url
  254.         self.username     = jms_username
  255.         self.password     = jms_password
  256.         self.token        = None
  257.         self.server       = None
  259.     def init_http(self):
  260.         HTTP.server       = self.jms_url
  261.         HTTP.get_token(self.username, self.password)
  263.     def perform(self):
  264.         self.init_http()
  265.         self.perm         = AssetPermission()
  266.         self.perm.perform()
  269. if __name__ == '__main__':
  271.     # jumpserver url 地址
  272.     jms_url                = 'http://192.168.100.244'
  274.     # 管理员账户
  275.     jms_username           = 'admin'
  276.     jms_password           = 'admin'
  278.     # 资产节点
  279.     asset_node_name        = 'test'
  281.     # 资产信息
  282.     asset_name             = '192.168.100.1'
  283.     asset_ip               = '192.168.100.1'
  284.     asset_platform         = 'Linux'
  285.     asset_protocols        = ['ssh/22']
  287.     # 资产管理用户
  288.     assets_admin_name      = 'test_root'
  289.     assets_admin_username  = 'root'
  290.     assets_admin_password  = 'test123456'
  292.     # 资产系统用户
  293.     assets_system_name     = 'test'
  294.     assets_system_username = 'test'
  296.     # 用户用户名
  297.     user_name              = '测试用户'
  298.     user_username          = 'test'
  299.     user_email             = 'test@jumpserver.org'
  301.     # 资产授权
  302.     perm_name              = 'AutoPerm' +'_'+ (time.strftime("%Y-%m-%d %H:%M:%S", time.localtime()))
  303.     perm_date_start        = '2021-05-01 14:25:47 +0800'
  304.     perm_date_expired      = '2021-06-01 14:25:47 +0800'
  306.     api = APICreateAssetPermission()
  307.     api.perform()

Access Key

  1. #!/usr/bin/env python3
  2. # -*- coding:utf-8 -*-
  4. import sys, requests, time, datetime
  5. from httpsig.requests_auth import HTTPSignatureAuth
  7. class HTTP:
  8.     server = None
  9.     auth   = None
  11.     @classmethod
  12.     def get_auth(cls, accesskeyid, accesskeysecret):
  13.         signature_headers = ['(request-target)', 'accept', 'date']
  14.         auth              = HTTPSignatureAuth(key_id=accesskeyid, secret=accesskeysecret, algorithm='hmac-sha256', headers=signature_headers)
  15.         cls.auth          = auth
  17.     @classmethod
  18.     def get(cls, url, params=None, **kwargs):
  19.         url               = cls.server + url
  20.         GMT_FORMAT        = '%a, %d %b %Y %H:%M:%S GMT'
  21.         headers           = {
  22.             'Accept': 'application/json',
  23.             'Date': datetime.datetime.utcnow().strftime(GMT_FORMAT)
  24.         }
  25.         kwargs['auth']    = cls.auth
  26.         kwargs['headers'] = headers
  27.         res               = requests.get(url, params, **kwargs)
  28.         return res
  30.     @classmethod
  31.     def post(cls, url, data=None, json=None, **kwargs):
  32.         url               = cls.server + url
  33.         GMT_FORMAT        = '%a, %d %b %Y %H:%M:%S GMT'
  34.         headers           = {
  35.             'Accept': 'application/json',
  36.             'Date': datetime.datetime.utcnow().strftime(GMT_FORMAT)
  37.         }
  38.         kwargs['auth']    = cls.auth
  39.         kwargs['headers'] = headers
  40.         res               = requests.post(url, data, json, **kwargs)
  41.         return res
  43. class User(object):
  45.     def __init__(self):
  46.         self.id           = None
  47.         self.name         = user_name
  48.         self.username     = user_username
  49.         self.email        = user_email
  51.     def exist(self):
  52.         url               = '/api/v1/users/users/'
  53.         params            = {'username': self.username}
  54.         res               = HTTP.get(url, params=params)
  55.         res_data          = res.json()
  56.         if res.status_code in [200, 201] and res_data:
  57.             self.id       = res_data[0].get('id')
  58.         else:
  59.             self.create()
  61.     def create(self):
  62.         print("创建用户 {}".format(self.username))
  63.         url               = '/api/v1/users/users/'
  64.         data              = {
  65.             'name': self.name,
  66.             'username': self.username,
  67.             'email': self.email,
  68.             'is_active': True
  69.         }
  70.         res               = HTTP.post(url, json=data)
  71.         self.id           = res.json().get('id')
  73.     def perform(self):
  74.         self.exist()
  76. class Node(object):
  78.     def __init__(self):
  79.         self.id           = None
  80.         self.name         = asset_node_name
  82.     def exist(self):
  83.         url               = '/api/v1/assets/nodes/'
  84.         params            = {'value': self.name}
  85.         res               = HTTP.get(url, params=params)
  86.         res_data          = res.json()
  87.         if res.status_code in [200, 201] and res_data:
  88.             self.id       = res_data[0].get('id')
  89.         else:
  90.             self.create()
  92.     def create(self):
  93.         print("创建资产节点 {}".format(self.name))
  94.         url               = '/api/v1/assets/nodes/'
  95.         data              = {
  96.             'value': self.name
  97.         }
  98.         res               = HTTP.post(url, json=data)
  99.         self.id           = res.json().get('id')
  101.     def perform(self):
  102.         self.exist()
  104. class AdminUser(object):
  106.     def __init__(self):
  107.         self.id           = None
  108.         self.name         = assets_admin_name
  109.         self.username     = assets_admin_username
  110.         self.password     = assets_admin_password
  112.     def exist(self):
  113.         url               = '/api/v1/assets/admin-user/'
  114.         params            = {'username': self.name}
  115.         res               = HTTP.get(url, params=params)
  116.         res_data          = res.json()
  117.         if res.status_code in [200, 201] and res_data:
  118.             self.id       = res_data[0].get('id')
  119.         else:
  120.             self.create()
  122.     def create(self):
  123.         print("创建管理用户 {}".format(self.name))
  124.         url               = '/api/v1/assets/admin-users/'
  125.         data              = {
  126.             'name': self.name,
  127.             'username': self.username,
  128.             'password': self.password
  129.         }
  130.         res               = HTTP.post(url, json=data)
  131.         self.id           = res.json().get('id')
  133.     def perform(self):
  134.         self.exist()
  136. class Asset(object):
  138.     def __init__(self):
  139.         self.id           = None
  140.         self.name         = asset_name
  141.         self.ip           = asset_ip
  142.         self.platform     = asset_platform
  143.         self.protocols    = asset_protocols
  144.         self.admin_user   = AdminUser()
  145.         self.node         = Node()
  147.     def exist(self):
  148.         url               = '/api/v1/assets/assets/'
  149.         params            = {
  150.             'hostname': self.name
  151.         }
  152.         res               = HTTP.get(url, params)
  153.         res_data          = res.json()
  154.         if res.status_code in [200, 201] and res_data:
  155.             self.id       = res_data[0].get('id')
  156.         else:
  157.             self.create()
  159.     def create(self):
  160.         print("创建资产 {}".format(self.ip))
  161.         self.admin_user.perform()
  162.         self.node.perform()
  163.         url               = '/api/v1/assets/assets/'
  164.         data              = {
  165.             'hostname': self.ip,
  166.             'ip': self.ip,
  167.             'platform': self.platform,
  168.             'protocols': self.protocols,
  169.             'admin_user': self.admin_user.id,
  170.             'nodes': [self.node.id],
  171.             'is_active': True
  172.         }
  173.         res               = HTTP.post(url, json=data)
  174.         self.id           = res.json().get('id')
  176.     def perform(self):
  177.         self.exist()
  179. class SystemUser(object):
  181.     def __init__(self):
  182.         self.id           = None
  183.         self.name         = assets_system_name
  184.         self.username     = assets_system_username
  186.     def exist(self):
  187.         url               = '/api/v1/assets/system-users/'
  188.         params            = {'name': self.name}
  189.         res               = HTTP.get(url, params)
  190.         res_data          = res.json()
  191.         if res.status_code in [200, 201] and res_data:
  192.             self.id       = res_data[0].get('id')
  193.         else:
  194.             self.create()
  196.     def create(self):
  197.         print("创建系统用户 {}".format(self.name))
  198.         url               = '/api/v1/assets/system-users/'
  199.         data              = {
  200.             'name': self.name,
  201.             'username': self.username,
  202.             'login_mode': 'auto',
  203.             'protocol': 'ssh',
  204.             'auto_push': True,
  205.             'sudo': 'All',
  206.             'shell': '/bin/bash',
  207.             'auto_generate_key': True,
  208.             'is_active': True
  209.         }
  210.         res               = HTTP.post(url, json=data)
  211.         self.id           = res.json().get('id')
  213.     def perform(self):
  214.         self.exist()
  216. class AssetPermission(object):
  218.     def __init__(self):
  219.         self.name         = perm_name
  220.         self.user         = User()
  221.         self.asset        = Asset()
  222.         self.system_user  = SystemUser()
  224.     def create(self):
  225.         print("创建资产授权名称 {}".format(self.name))
  226.         url               = '/api/v1/perms/asset-permissions/'
  227.         data              = {
  228.             'name': self.name,
  229.             'users': [self.user.id],
  230.             'assets': [self.asset.id],
  231.             'system_users': [self.system_user.id],
  232.             'actions': ['all'],
  233.             'is_active': True,
  234.             'date_start': perm_date_start,
  235.             'date_expired': perm_date_expired
  236.         }
  237.         res               = HTTP.post(url, json=data)
  238.         res_data          = res.json()
  239.         if res.status_code in [200, 201] and res_data:
  240.             print("创建资产授权规则成功: ", res_data)
  241.         else:
  242.             print("创建授权规则失败: ", res_data)
  244.     def perform(self):
  245.         self.user.perform()
  246.         self.asset.perform()
  247.         self.system_user.perform()
  248.         self.create()
  250. class APICreateAssetPermission(object):
  252.     def __init__(self):
  253.         self.jms_url         = jms_url
  254.         self.accesskeyid     = jms_accesskeyid
  255.         self.accesskeysecret = jms_accesskeysecret
  256.         self.auth            = None
  257.         self.server          = None
  259.     def init_http(self):
  260.         HTTP.server          = self.jms_url
  261.         HTTP.get_auth(self.accesskeyid, self.accesskeysecret)
  263.     def perform(self):
  264.         self.init_http()
  265.         self.perm            = AssetPermission()
  266.         self.perm.perform()
  269. if __name__ == '__main__':
  271.     # jumpserver url 地址
  272.     jms_url                = 'http://192.168.100.244'
  274.     # 管理员 AK SK
  275.     jms_accesskeyid        = ''
  276.     jms_accesskeysecret    = ''
  278.     # 资产节点
  279.     asset_node_name        = 'test'
  281.     # 资产信息
  282.     asset_name             = '192.168.100.1'
  283.     asset_ip               = '192.168.100.1'
  284.     asset_platform         = 'Linux'
  285.     asset_protocols        = ['ssh/22']
  287.     # 资产管理用户
  288.     assets_admin_name      = 'test_root'
  289.     assets_admin_username  = 'root'
  290.     assets_admin_password  = 'test123456'
  292.     # 资产系统用户
  293.     assets_system_name     = 'test'
  294.     assets_system_username = 'test'
  296.     # 用户用户名
  297.     user_name              = '测试用户'
  298.     user_username          = 'test'
  299.     user_email             = 'test@jumpserver.org'
  301.     # 资产授权
  302.     perm_name              = 'AutoPerm' +'_'+ (time.strftime("%Y-%m-%d %H:%M:%S", time.localtime()))
  303.     perm_date_start        = '2021-05-01 14:25:47 +0800'
  304.     perm_date_expired      = '2021-06-01 14:25:47 +0800'
  306.     api = APICreateAssetPermission()
  307.     api.perform()