API(GraphQL)

使用原生 GraphQL 与 Authing 服务器交互。

Authing 的 API 未使用 RESTful API,而是使用了 GraphQL。

本文档包含了 Authing 的 GraphQL 请求,可直接复制粘贴使用。

推荐使用:GraphQL 调试器

用来调试 Authing 所有 API 的浏览器

此调试器允许开发者直接在线上调试 Authing 的 API。

GraphQL 网关

  1. https://users.authing.cn/graphql

  2. https://oauth.authing.cn/graphql

如非特殊说明,以下 GraphQL 都使用 https://users.authing.cn/graphql 网关。

推荐使用 insomnia 调试 GraphQL 请求。

初始化

SDK 初始化时获取客户端信息和 accessToken 信息,后续的管理用户的操作请发送此 Token,在下文中,此 Token 命名为「OwnerToken」。

query getClientWhenSdkInit($secret: String, $clientId: String, $retUserId: Boolean, $timestamp: String, $signature: String, $nonce: Int){
    getClientWhenSdkInit(secret: $secret, clientId: $clientId, retUserId: $retUserId, timestamp: $timestamp, signature: $signature, nonce: $nonce){
      accessToken
      clientInfo {
        _id
        name
        descriptions
        jwtExpired
        createdAt
        isDeleted
        logo
        emailVerifiedDefault
        registerDisabled
        allowedOrigins
        clientType {
          _id
          name
          description
          image
          example
        }
      }
    }
}

注意事项

此接口不需要发送任何 Token

读取用户配置的社会化登录信息

此接口用来读取用户在 Authing 控制台中配置的 OAuth 信息,enabled 为是否启用。

此接口使用的网关为:https://oauth.authing.cn/graphql

query ReadOAuthList($clientId: String!) {
    ReadOauthList(clientId: $clientId) {
        _id
        name
        image
        description
        enabled
        client
        user
        url
    }
}

注意事项

此接口不需要发送任何 Token

登录

此接口用来执行用户登录的操作,登录成功后会返回 UserToken,建议单独维护此 Token。

mutation login($unionid: String, $email: String, $phone: String, $password: String, $lastIP: String, $registerInClient: String!, $verifyCode: String, $browser: String, $device: String) {
    login(unionid: $unionid, email: $email, phone: $phone, password: $password, lastIP: $lastIP, registerInClient: $registerInClient, verifyCode: $verifyCode, browser: $browser, device: $device) {
        _id
        email
        emailVerified
        username
        nickname
        company
        phone
        photo
        browser
        token
        tokenExpiredAt
        loginsCount
        lastLogin
        lastIP
        signedUp
        blocked
        isDeleted
    }
}

注意事项

  1. 此处(登录)的密码需要加密,Authing 使用了非对称加密算法,加密方式是 PKCS1v1.5。注意,个别语言,如 JavaScript(非 Node )和 Go 在加密之后还要使用 base64 包一层;

  2. 此接口不需要发送任何 Token

Public Key

-----BEGIN PUBLIC KEY-----
MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC4xKeUgQ+Aoz7TLfAfs9+paePb
5KIofVthEopwrXFkp8OCeocaTHt9ICjTT2QeJh6cZaDaArfZ873GPUn00eOIZ7Ae
+TiA2BKHbCvloW3w5Lnqm70iSsUi5Fmu9/2+68GZRH9L7Mlh8cFksCicW2Y2W2uM
GKl64GDcIq3au+aqJQIDAQAB
-----END PUBLIC KEY-----

使用手机验证码登录

使用手机验证码的方式登录,登录后返回的 Token 需要在客户端维护。

mutation login($phone: String, $phoneCode: Int, $registerInClient: String!, $browser: String, $device: String) {
          login(phone: $phone, phoneCode: $phoneCode, registerInClient: $registerInClient, browser: $browser, device: $device) {
            _id
            email
            emailVerified
            username
            nickname
            phone
            company
            photo
            browser
            token
            tokenExpiredAt
            loginsCount
            lastLogin
            lastIP
            signedUp
            blocked
            isDeleted
          }
      }

注意事项

此接口不用发送任何 Token

发送短信验证码

发送短信验证码是一个 rest 接口,接口声明如下:

发送短信验证码

GET https://users.authing.cn/send_smscode/:phone/:clientId

发送验证码给指定手机号

Query Parameters

NameTypeDescription

clientId

string

应用 ID

phone

string

手机号

{"code":200,"message":"发送成功"}

发送注册用短信验证码

GET https://users.authing.cn/notification/send_register_smscode/:phone/:clientId

发送验证码给指定手机号,与直接发送验证码不同的是,它会检测账号是否已经存在。

Query Parameters

NameTypeDescription

clientId

string

应用 ID

phone

string

手机号

通过 AD 登录

使用 Active Directory 登录,登录后返回的 Token 需要在客户端维护

mutation LoginByAd($adConnectorId: String!, $username: String!, $password: String!) {
  LoginByLDAP(adConnectorId: $adConnectorId, username: $username, password: $password) {
      _id
      email
      emailVerified
      unionid
      oauth
      registerMethod
      username
      nickname
      company
      photo
      browser
      token
      tokenExpiredAt
      loginsCount
      lastLogin
      lastIP
      signedUp
      blocked
  }
}

通过 LDAP 登录

使用 LDAP 登录,登录后返回的 Token 需要在客户端维护

mutation LoginByLDAP($username: String!, $password: String!, $clientId: String!, $browser: String, $device: String) {
      LoginByLDAP(username: $username, clientId: $clientId, password: $password, browser: $browser, device: $device) {
            _id
            email
            emailVerified
            unionid
            oauth
            registerMethod
            username
            nickname
            company
            photo
            browser
            token
            tokenExpiredAt
            loginsCount
            lastLogin
            lastIP
            signedUp
            blocked
          }
      }

注意事项

此接口不用发送任何 Token

刷新 Token

刷新用户 Token

mutation RefreshToken(
  $client: String!
  $user: String!
) {
  refreshToken(
    client: $client
    user: $user
  ) {
    token
    iat
    exp
  }
}

注意事项

此接口需发送 OwnerToken

通过 OIDC 登录

GET https://users.authing.cn/oauth/oidc/token

Path Parameters

NameTypeDescription

email

string

email

password

string

password

client_secret

string

OIDC secret

client_id

string

OIDC ID

Headers

NameTypeDescription

Content-Type

string

application/x-www-form-urlencoded

刷新 OIDC oken

GET https://users.authing.cn/oauth/oidc/token

Path Parameters

NameTypeDescription

refresh_token

string

Your refresh_token

client_secret

string

OIDC secret

client_id

string

OIDC ID

Headers

NameTypeDescription

Content-Type

string

application/x-www-form-urlencoded

Sign In

mutation SignIn($oidcAppId: String, $email: String, $userPoolId: String, $phone: String, $username: String, $unionid: String, $password: String) {
      signIn(oidcAppId: $oidcAppId,
      userPoolId: $userPoolId,
      email: $email,
      phone: $phone,
      password: $password,
      username: $username,
      unionid: $unionid) {
        sub
        birthdate
        family_name
        gender
        given_name
        locale
        middle_name
        name
        nickname
        picture
        preferred_username
        profile
        updated_at
        website
        zoneinfo
        username
        _id
        company
        browser
        device
        logins_count
        register_method
        blocked,
        last_ip
        register_in_userpool
        last_login
        signed_up
        email
        email_verified,
        phone_number
        phone_number_verified
        token
        access_token
        id_token
        refresh_token
        expires_in
        token_type
        scope
      }
    }

Refresh SignInToken

      mutation RefreshSignInToken(
        $oidcAppId: String,
        $userPoolId: String,
        $refreshToken: String!
      ) {
        refreshSignInToken(
          oidcAppId: $oidcAppId
          userPoolId: $userPoolId
          refreshToken: $refreshToken
        ) {
          id_token
          access_token
          refresh_token
          scope
          expires_in
        }
      }
    

注册

mutation register(
    $unionid: String,
    $email: String, 
    $password: String, 
    $lastIP: String, 
    $forceLogin: Boolean,
    $registerInClient: String!,
    $oauth: String,
    $username: String,
    $nickname: String,
    $registerMethod: String,
    $photo: String,
    $browser: String, 
    $phone: String,
    $device: String
) {
    register(userInfo: {
        unionid: $unionid,
        email: $email,
        password: $password,
        lastIP: $lastIP,
        forceLogin: $forceLogin,
        registerInClient: $registerInClient,
        oauth: $oauth,
        registerMethod: $registerMethod,
        photo: $photo,
        phone: $phone,
        username: $username,
        nickname: $nickname,
        device: $device,
        browser: $browser
    }) {
        _id,
        email,
        emailVerified,
        username,
        nickname,
        company,
        photo,
        phone,
        browser,
        password,
        token,
        group {
            name
        },
        blocked,
        device
    }
}

注意事项

  1. 此处(登录)的密码需要加密,Authing 使用了非对称加密算法,加密方式是 PKCS1v1.5。注意,个别语言,如 JavaScript(非 Node)和 Go 在加密之后还要使用 base64 包一层。

  2. 此接口不需要发送任何 Token

查询用户是否存在

此接口可以查询符合条件的用户是否存在,避免重复注册。

query userExist($userPoolId: String!,$phone: String,$username: String,$email: String){
  userExist(userPoolId: $userPoolId,phone: $phone,username: $username,email: $email)
}

Public Key

-----BEGIN PUBLIC KEY-----
MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC4xKeUgQ+Aoz7TLfAfs9+paePb
5KIofVthEopwrXFkp8OCeocaTHt9ICjTT2QeJh6cZaDaArfZ873GPUn00eOIZ7Ae
+TiA2BKHbCvloW3w5Lnqm70iSsUi5Fmu9/2+68GZRH9L7Mlh8cFksCicW2Y2W2uM
GKl64GDcIq3au+aqJQIDAQAB
-----END PUBLIC KEY-----

读取用户资料

此接口用来读取用户资料,建议使用 OwnerToken

query user($id: String!, $registerInClient: String!){
    user(id: $id, registerInClient: $registerInClient) {
        _id
        email
        emailVerified
        username
        nickname
        company
        photo
        browser
        registerInClient
        registerMethod
        oauth
        token
        tokenExpiredAt
        loginsCount
        lastLogin
        lastIP
        signedUp
        blocked
        isDeleted
        userLocation {
          _id
          when
          where
        }
        userLoginHistory {
          totalCount
          list {
            _id
            when
            success
            ip
            result
          }
        }
    }
}

注意事项

此接口需要发送 Token,建议直接使用 OwnerToken

批量查询用户信息

批量查询用户,ids 是一个字符串,用逗号分隔 id。

query userPatch($ids: String){
    userPatch(ids: $ids){
      list {
        _id
        unionid
        email
        emailVerified
        username
        nickname
        company
        photo
        browser
        registerInClient
        registerMethod
        oauth
        token
        tokenExpiredAt
        loginsCount
        lastLogin
        lastIP
        signedUp
        blocked
        isDeleted
        userLocation {
          _id
          when
          where
        }
        userLoginHistory {
          totalCount
          list {
            _id
            when
            success
            ip
            result
          }
        }
      }
      totalCount
    }
}

注意事项

此接口需要OwnerToken

读取用户列表

此接口用来读取用户列表,建议使用 OwnerToken

query users($registerInClient: String, $page: Int, $count: Int){
  users(registerInClient: $registerInClient, page: $page, count: $count) {
    totalCount
    list {
      _id
      email
      emailVerified
      username
      nickname
      company
      photo
      browser
      password
      registerInClient
      token
      tokenExpiredAt
      loginsCount
      lastLogin
      lastIP
      signedUp
      blocked
      isDeleted
      group {
        _id
        name
        descriptions
        createdAt
      }
      clientType {
        _id
        name
        description
        image
        example
      }
      userLocation {
        _id
        when
        where
      }
      userLoginHistory {
        totalCount
        list{
          _id
          when
          success
          ip
          result
        }
      }
      systemApplicationType {
        _id
        name
        descriptions
        price
      }
    }
  }
}

注意事项

此接口需要发送 Token,建议直接使用 OwnerToken

检查用户登录状态

此接口检查用户登录状态,请使用 UserToken

query checkLoginStatus {
    checkLoginStatus {
        status
        code
        message
    }
}

注意事项

此接口需要发送 Token,请使用 UserToken

删除用户数据

此接口用来删除用户数据,建议使用 OwnerToken

mutation removeUsers($ids: [String], $registerInClient: String, $operator: String){
  removeUsers(ids: $ids, registerInClient: $registerInClient, operator: $operator) {
    _id
  }
}

注意事项

此接口需要发送 Token,建议直接使用 OwnerToken

更新用户资料

此接口用来更新用户资料,建议使用 OwnerToken

mutation UpdateUser(
    $_id: String!,
    $email: String,
    $emailVerified: Boolean,
    $username: String,
    $nickname: String,
    $company: String,
    $photo: String,
    $browser: String,
    $password: String,
    $oldPassword: String,
    $registerInClient: String!,
    $token: String,
    $tokenExpiredAt: String,
    $loginsCount: Int,
    $lastLogin: String,
    $lastIP: String,
    $signedUp: String,
    $blocked: Boolean,
    $isDeleted: Boolean
){
  updateUser(options: {
    _id: $_id,
    email: $email,
    emailVerified: $emailVerified,
    username: $username,
    nickname: $nickname,
    company: $company,
    photo: $photo,
    browser: $browser,
    password: $password,
    oldPassword: $oldPassword,
    registerInClient: $registerInClient,
    token: $token,
    tokenExpiredAt: $tokenExpiredAt,
    loginsCount: $loginsCount,
    lastLogin: $lastLogin,
    lastIP: $lastIP,
    signedUp: $signedUp,
    blocked: $blocked,
    isDeleted: $isDeleted
  }) {
    _id
    email
    emailVerified
    username
    nickname
    company
    photo
    browser
    registerInClient
    registerMethod
    oauth
    token
    tokenExpiredAt
    loginsCount
    lastLogin
    lastIP
    signedUp
    blocked
    isDeleted
  }
}

注意事项

此接口需要发送 Token,建议直接使用 OwnerToken

重置密码流程

  1. sendResetPasswordEmail 发送重置密码邮件给用户

  2. verifyResetPasswordVerifyCode 检查验证码是否正确

  3. changePassword 使用新的密码和验证码来修改密码

注意事项

以下三个修改密码的 Token 可以不发送任何Token

发送重置密码邮件

mutation sendResetPasswordEmail(
    $email: String!,
    $client: String!
){
    sendResetPasswordEmail(
        email: $email,
        client: $client
    ) {
          message
          code
          status
    }
}

验证重置密码验证码

mutation verifyResetPasswordVerifyCode(
    $email: String!,
    $client: String!,
    $verifyCode: String!
) {
    verifyResetPasswordVerifyCode(
        email: $email,
        client: $client,
        verifyCode: $verifyCode
    ) {
          message
          code
          status
    }
}

修改密码

此接口用来更改忘记密码后的新密码,需要携带 verifyCode,不用发送 Token,正常的密码修正请使用上面的 update 接口。

mutation changePassword(
    $email: String!,
    $client: String!,
    $password: String!,
    $verifyCode: String!
){
    changePassword(
        email: $email,
        client: $client,
        password: $password,
        verifyCode: $verifyCode
    ) {
        _id
        email
        emailVerified
        username
        nickname
        company
        photo
        browser
        registerInClient
        registerMethod
        oauth
        token
        tokenExpiredAt
        loginsCount
        lastLogin
        lastIP
        signedUp
        blocked
        isDeleted
    }
}

发送验证邮件

mutation sendVerifyEmail(
    $email: String!,
    $client: String!
){
    sendVerifyEmail(
        email: $email,
        client: $client
    ) {
        message,
        code,
        status
    }
}

注意事项

此接口不用发送任何 Token

解析 JWT Token

解析 JWT Token

query decodeJwtToken($token: String){
    decodeJwtToken(token: $token){
        data{
            email
            id
            clientId
            unionid
        }
        status{
            message
            code
            status
        }
        iat
        exp
    }
}

注意事项

此接口不用发送任何 Token

读取用户绑定的社会化登录

读取用户绑定的社会化登录

此接口使用的网关为:https://oauth.authing.cn/graphql

query notBindOAuthList($user: String, $client: String) {
        notBindOAuthList(user: $user, client: $client) {
          type
          oAuthUrl
          image
          name
          binded
        }
}

注意事项

此接口发送 OwnerToken

绑定社会化登录

用户绑定第三方登录方式

mutation bindOtherOAuth($user: String, $client: String, $type: String!, $unionid: String!, $userInfo: String!){
    bindOtherOAuth(user: $user, client: $client, type: $type, unionid: $unionid, userInfo: $userInfo){
        _id
        user
        client
        type
        unionid
        userInfo
        createdAt
    }
}

注意事项

此接口发送 UserToken

取消绑定社会化登录

用户解绑第三方登录方式

mutation unbindOtherOAuth($user: String, $client: String, $type: String!){
    unbindOtherOAuth(user: $user, client: $client, type: $type){
        _id
        user
        client
        type
        unionid
        userInfo
        createdAt
    }
}

注意事项

此接口发送 UserToken

解绑邮箱

用户解绑 Email

mutation unbindEmail($user: String, $client: String){
    unbindEmail(user: $user, client: $client){
      _id
      email
      emailVerified
      username
      nickname
      company
      photo
      browser
      registerInClient
      registerMethod
      oauth
      token
      tokenExpiredAt
      loginsCount
      lastLogin
      lastIP
      signedUp
      blocked
      isDeleted
    }
}

注意事项

此接口发送 UserToken

开启/关闭手机号注册白名单限制

开启或关闭手机号注册时的白名单限制

mutation setInvitationState($client: String!, $enableQrCode: Boolean){
  setInvitationState(
    client: $client,
    enableQrCode: $enableQrCode,    
  ) {
    client,
    enableQrCode,
    createdAt,
    updatedAt
  }
}

注意事项

此接口需要发送 Token,建议直接使用 OwnerToken

查看用户池的手机号白名单开启状态

query queryInvitationState($client: String!){
  queryInvitationState(
    client: $client,
  ) {
	client,
 	enableQrCode
  }
}

注意事项

此接口需要发送 Token,建议直接使用 OwnerToken

增加手机号到白名单

mutation addToInvitation($client: String!, $qrCodPhone: String){
  addToInvitation(
    client: $client,
    qrCodePhone: $qrCodPhone,    
  ) {
    client,
    qrCodePhone,
  }
}

注意事项

此接口需要发送 Token,建议直接使用 OwnerToken

从白名单中删除手机号

mutation removeFromInvitation($client: String!, $qrCodePhone: String){
  removeFromInvitation(
    client: $client,
    qrCodePhone: $qrCodePhone,    
  ) {
    client,
    qrCodePhone,
  }
}

注意事项

此接口需要发送 Token,建议直接使用 OwnerToken

查看白名单中的手机号

query queryInvitation($client: String!){
  queryInvitation(
  client: $client,
  ) {
	client,
 	qrCodePhone
  }
}

注意事项

此接口需要发送 Token,建议直接使用 OwnerToken

查询 MFA 信息

query queryMFA($_id: String, $userId: String, $userPoolId: String, $page: Int, $count: Int) {
  queryMFA(_id: $_id, userId: $userId, userPoolId: $userPoolId, page: $page, count: $count) {
    _id
    userId
    userPoolId
    enable
    shareKey
  }
}

参数

  • _id {String},MFA 主体的 id

  • userPoolId {String},用户池 id

  • userId {String},用户 id

  • page {Int},分页页码

  • count {Int},每页数目

传参说明

  1. 通过用户 id用户池 id 参数来查询一个用户的 MFA 信息,此时 userIduserPoolId 两个参数必填。

  2. 也可以通过 MFA 主体的 id 来查询 MFA 的信息,此时只需传入 _id 参数,userId 和 userPoolId 参数可以不传。

注意事项

此接口需要发送 Token,可以使用 OwnerTokenUserToken

修改 MFA 信息

mutation changeMFA($_id: String,$userId: String,$userPoolId: String,$enable: Boolean!, $refreshKey: Boolean) {
  changeMFA(_id: $_id, userId: $userId, userPoolId: $userPoolId, enable: $enable, refreshKey: $refreshKey) {
    _id
    userId
    userPoolId
    shareKey
    enable
  }
}

参数

  • _id {String},MFA 主体的 id

  • userPoolId {String},用户池 id

  • userId {String},用户 id

  • enable {Boolean},打开或关闭 MFA

  • refreshKey {Boolean},是否刷新 MFA secret

传参说明

  1. 通过用户 id用户池 id 参数来指定一个用户的 MFA 状态,此时 userIduserPoolId 两个参数必填。

  2. 也可以通过 MFA 主体的 id 来修改 MFA 的状态,此时只需传入 _id 参数,userId 和 userPoolId 参数可以不传。

注意事项

此接口需要发送 Token,必须使用 UserToken

查询用户授权过的 SSO 应用列表

此接口用于查询一个用户池内,用户授权过的 SSO 应用列表。

query GetUserAuthorizedApps($clientId: String, $userId: String, $page: Int, $count: Int) {
    GetUserAuthorizedApps(clientId: $clientId, userId: $userId, page: $page, count: $count) {
        OAuthApps {
            _id
            name
            domain
            clientId
            description
            isDeleted
            grants
            redirectUris
            when
        }
        OIDCApps {
            _id
            name
            client_id
            domain
            description
            authorization_code_expire
            when
            isDeleted
            id_token_signed_response_alg
            response_types
            grant_types
            token_endpoint_auth_method
            redirect_uris
            image
            access_token_expire
            id_token_expire
            cas_expire

        }
        totalCount
    }
}

参数

  • clientId {String},必须,用户池 id

  • userId {String},必须,用户 id

  • page {Number},可选,页数,默认 1

  • count {Number},可选,每页数目,默认 10

返回示例

{
    "OAuthApps": [
        {
            "_id": "5d5a8a7bbc7275af2cb71920",
            "name": "test1",
            "domain": "test123",
            "clientId": "5d5921ffaa016518f658498d",
            "description": "",
            "isDeleted": false,
            "grants": [
                "authorization_code",
                "implicit",
                "refresh_token"
            ],
            "redirectUris": [
                "http://qq.com"
            ],
            "when": "Mon Aug 19 2019 19:39:39 GMT+0800 (CST)"
        },
        {
            "_id": "5d5e2e8b026f9d145bf89203",
            "name": "oauth1",
            "domain": "oauth1",
            "clientId": "5d5921ffaa016518f658498d",
            "description": "",
            "isDeleted": false,
            "grants": [
                "authorization_code",
                "implicit",
                "refresh_token"
            ],
            "redirectUris": [
                "http://qq.com"
            ],
            "when": "Thu Aug 22 2019 13:56:27 GMT+0800 (CST)"
        }
    ],
    "OIDCApps": [
        {
            "_id": "5d5a85e258375a32d1133d45",
            "name": "test1",
            "client_id": "5d5a85e258375a32d1133d45",
            "domain": "test1",
            "description": "test1",
            "authorization_code_expire": "600",
            "when": "Mon Aug 19 2019 19:20:02 GMT+0800 (CST)",
            "isDeleted": false,
            "id_token_signed_response_alg": "HS256",
            "response_types": [
                "code"
            ],
            "grant_types": [
                "authorization_code",
                "refresh_token"
            ],
            "token_endpoint_auth_method": "client_secret_post",
            "redirect_uris": [
                "http://qq.com"
            ],
            "image": "https://usercontents.authing.cn/client/logo@2.png",
            "access_token_expire": "3600",
            "id_token_expire": "3600",
            "cas_expire": "3600"
        }
    ],
    "totalCount": 3
}

注意事项

此接口需要发送 Token,可以使用 UserTokenOwnerToken

撤回用户对 SSO 应用的授权

此接口用于撤回一个用户池内,某个用户对该用户池下的某个 SSO 应用的授权。撤回授权后,用户在 SSO 登录页面登录时,会再次显示确权页面。

mutation RevokeUserAuthorizedApp($userPoolId: String, $userId: String, $appId: String) {
  RevokeUserAuthorizedApp(userPoolId: $userPoolId, userId: $userId, appId: $appId) {
    isRevoked
    _id
    scope
  }
}

参数

  • userPoolId {String},必须,用户池 id

  • userId {String},必须,用户 id

  • appId {String},必须,SSO 应用 id

返回示例

{
  "isRevoked": "true",
  "_id": "5d7661e17a9f981da5fa8098",
  "scope": "profile"
}

注意事项

此接口需要发送 Token,可以使用 UserTokenOwnerToken

Last updated