Pular para o conteúdo principal

Casdoor SDKs

Overview​

Casdoor SDKs extend standard OIDC with user management, resource uploads, and other features. They take a bit more setup than a generic OIDC client but give you the full Casdoor API.

Frontend SDKs — For web (JavaScript, React, Vue, etc.) and mobile (Android, iOS, React Native, Flutter).
Backend SDKs — For Go, Java, Node.js, Python, PHP, .NET, Rust, C++, and more.

dica

For a frontend/backend split, use a frontend SDK (e.g. casdoor-js-sdk, casdoor-react-sdk, casdoor-vue-sdk) in the UI and a backend SDK for token validation and API calls. For a traditional server-rendered app (JSP, PHP), a backend SDK may be enough. Example: casdoor-python-vue-sdk-example.

SDK MóvelDescriçãoCódigo SDKCódigo de exemplo
SDK AndroidPara aplicativos Androidcasdoor-android-sdkcasdoor-android-example
SDK iOSPara aplicativos iOScasdoor-ios-sdkcasdoor-ios-example
SDK para React NativePara aplicativos React Nativecasdoor-react-native-sdkcasdoor-react-native-example
SDK FlutterPara aplicativos Fluttercasdoor-flutter-sdkcasdoor-flutter-example
SDK para FirebasePara aplicativos Google Firebasecasdoor-firebase-example
SDK para Jogos UnityPara jogos Unity 2D/3D PC/Mobilecasdoor-dotnet-sdkcasdoor-unity-example
SDK para uni-appPara aplicativos uni-appcasdoor-uniapp-sdkcasdoor-uniapp-example
SDK para DesktopDescriçãoCódigo SDKCódigo de exemplo
SDK para ElectronPara aplicativos Electroncasdoor-js-sdkcasdoor-electron-example
SDK para .NET DesktopPara aplicativos de desktop .NETcasdoor-dotnet-sdkWPF: casdoor-dotnet-desktop-example
WinForms: casdoor-dotnet-winform-example
Avalonia UI: casdoor-dotnet-avalonia-example
SDK para C/C++Para aplicativos de desktop C/C++casdoor-cpp-sdkcasdoor-cpp-qt-example
SDK para frontend WebDescriçãoCódigo do SDKCódigo de exemplo
SDK para JavascriptPara sites tradicionais não-SPAcasdoor-js-sdkBackend Nodejs: casdoor-raw-js-example
Backend Go: casdoor-go-react-sdk-example
SDK apenas para FrontendPara sites SPA apenas de frontendcasdoor-js-sdkcasdoor-react-only-example
SDK para ReactPara sites Reactcasdoor-react-sdkBackend Nodejs: casdoor-nodejs-react-example
Backend Java: casdoor-spring-security-react-example
SDK para Next.jsPara sites Next.jsnextjs-auth
SDK para NuxtPara sites Nuxtnuxt-auth
Vue SDKFor Vue websitescasdoor-vue-sdkcasdoor-python-vue-sdk-example
Angular SDKFor Angular websitescasdoor-angular-sdkcasdoor-nodejs-angular-example
Flutter SDKFor Flutter Web websitescasdoor-flutter-sdkcasdoor-flutter-example
ASP.NET SDKFor ASP.NET Blazor WASM websitesBlazor.BFF.OpenIDConnect.Templatecasdoor-dotnet-blazorwasm-oidc-example
Firebase SDKFor Google Firebase appscasdoor-firebase-example

Pair the frontend with a backend SDK in your server’s language:

SDK para backend WebDescriçãoCódigo do SDKCódigo de exemplo
SDK para GoPara backends Gocasdoor-go-sdkcasdoor-go-react-sdk-example
SDK para JavaPara backends Javacasdoor-java-sdkcasdoor-spring-boot-starter, casdoor-spring-boot-example, casdoor-spring-security-react-example
SDK para Node.jsPara backends Node.jscasdoor-nodejs-sdkcasdoor-nodejs-react-example
SDK para PythonPara backends Pythoncasdoor-python-sdkFlask: casdoor-python-vue-sdk-example
Django: casdoor-django-js-sdk-example
FastAPI: casdoor-fastapi-js-sdk-example
SDK para PHPPara backends PHPcasdoor-php-sdkwordpress-casdoor-plugin
SDK para .NETPara backends ASP.NETcasdoor-dotnet-sdkcasdoor-dotnet-sdk-example
SDK para RustPara backends Rustcasdoor-rust-sdkcasdoor-rust-example
SDK para C/C++Para backends C/C++casdoor-cpp-sdkcasdoor-cpp-qt-example
SDK para DartPara backends Dartcasdoor-dart-sdk
SDK para RubyPara backends Rubycasdoor-ruby-sdk

All official SDKs: https://github.com/orgs/casdoor/repositories?q=sdk&type=all&language=&sort=.

Using the SDK​

1. Configuração do SDK de backend​

On startup, call the SDK’s init function with your Casdoor endpoint, client ID, client secret, and (for JWT validation) the public key. Example with casdoor-go-sdk: https://github.com/casbin/casnode/blob/6d4c55f5c9a3c4bd8c85f2493abad3553b9c7ac0/controllers/account.go#L51-L64

var CasdoorEndpoint = "https://door.casdoor.com"
var ClientId = "541738959670d221d59d"
var ClientSecret = "66863369a64a5863827cf949bab70ed560ba24bf"
var CasdoorOrganization = "casbin"
var CasdoorApplication = "app-casnode"

//go:embed token_jwt_key.pem
var JwtPublicKey string

func init() {
    auth.InitConfig(CasdoorEndpoint, ClientId, ClientSecret, JwtPublicKey, CasdoorOrganization, CasdoorApplication)
}

Todos os parâmetros para InitConfig() são explicados a seguir:

ParâmetroDeveDescrição
endpointSimURL do Servidor Casdoor, como https://door.casdoor.com ou http://localhost:8000
clientIdSimID do Cliente para a aplicação Casdoor
clientSecretSimSegredo do Cliente para a aplicação Casdoor
jwtPublicKeySimA chave pública para o certificado da aplicação Casdoor
organizationNameYesO nome da organização Casdoor
applicationNameNãoO nome da aplicação Casdoor
dica

O jwtPublicKey pode ser gerenciado na página Certs como abaixo.

Gerenciamento de Certificados

Copy or download the public key from the certificate edit page for use in the SDK.

Edição de Certificados

Then select the cert on the application edit page.

Seleção de Certificados

2. Configuração do frontend​

Primeiro, instale casdoor-js-sdk via NPM ou Yarn:

npm install casdoor-js-sdk

Ou:

yarn add casdoor-js-sdk

Em seguida, defina as seguintes funções utilitárias (melhor em um arquivo JS global como Setting.js):

import Sdk from "casdoor-js-sdk";

export function initCasdoorSdk(config) {
  CasdoorSdk = new Sdk(config);
}

export function getSignupUrl() {
  return CasdoorSdk.getSignupUrl();
}

export function getSigninUrl() {
  return CasdoorSdk.getSigninUrl();
}

export function getUserProfileUrl(userName, account) {
  return CasdoorSdk.getUserProfileUrl(userName, account);
}

export function getMyProfileUrl(account) {
  return CasdoorSdk.getMyProfileUrl(account);
}

export function getMyResourcesUrl(account) {
  return CasdoorSdk.getMyProfileUrl(account).replace("/account?", "/resources?");
}

export function signin() {
  return CasdoorSdk.signin(ServerUrl);
}

export function showMessage(type, text) {
  if (type === "") {
    return;
  } else if (type === "success") {
    message.success(text);
  } else if (type === "error") {
    message.error(text);
  }
}

export function goToLink(link) {
  window.location.href = link;
}

In your frontend entry file (e.g. index.js or app.js in React), initialize the casdoor-js-sdk by calling InitConfig() with the required parameters. Os primeiros 4 parâmetros devem usar o mesmo valor que o SDK de backend do Casdoor. O último parâmetro redirectPath é o caminho relativo para a URL redirecionada, retornada da página de login do Casdoor.

const config = {
  serverUrl: "https://door.casdoor.com",
  clientId: "014ae4bd048734ca2dea",
  organizationName: "casbin",
  appName: "app-casnode",
  redirectPath: "/callback",
};

xxx.initCasdoorSdk(config);

(Optional) This example uses React; the /callback route is handled by the component below, which forwards the call to the backend. Skip this if your callback goes directly to the backend (e.g. JSP or PHP).

import React from "react";
import {Button, Result, Spin} from "antd";
import {withRouter} from "react-router-dom";
import * as Setting from "./Setting";

class AuthCallback extends React.Component {
  constructor(props) {
    super(props);
    this.state = {
      classes: props,
      msg: null,
    };
  }

  componentWillMount() {
    this.login();
  }

  login() {
    Setting.signin().then((res) => {
      if (res.status === "ok") {
        Setting.showMessage("success", `Logged in successfully`);
        Setting.goToLink("/");
      } else {
        this.setState({
          msg: res.msg,
        });
      }
    });
  }

  render() {
    return (
      <div style={{textAlign: "center"}}>
        {this.state.msg === null ? (
          <Spin
            size="large"
            tip="Signing in..."
            style={{paddingTop: "10%"}}
          />
        ) : (
          <div style={{display: "inline"}}>
            <Result
              status="error"
              title="Login Error"
              subTitle={this.state.msg}
              extra={[
                <Button type="primary" key="details">
                  Details
                </Button>,
                <Button key="help">Help</Button>,
              ]}
            />
          </div>
        )}
      </div>
    );
  }
}

export default withRouter(AuthCallback);

3. Obter URLs de login​

Show "Sign up" and "Sign in" buttons or links to users; URLs can be obtained from the frontend or backend. See Login URLs.

4. Obter e verificar token de acesso​

Aqui estão os passos:

  1. O usuário clica na URL de login e é redirecionado para a página de login do Casdoor, como: https://door.casdoor.com/login/oauth/authorize?client_id=014ae4bd048734ca2dea&response_type=code&redirect_uri=https%3A%2F%2Fforum.casbin.com%2Fcallback&scope=read&state=app-casnode
  2. O usuário insere nome de usuário & senha e clica em Sign In (ou apenas clica no botão de login de terceiros como Sign in with GitHub).
  3. O usuário é redirecionado de volta para o seu aplicativo com o código de autorização emitido pelo Casdoor (como: https://forum.casbin.com?code=xxx&state=yyy), o backend do seu aplicativo precisa trocar o código de autorização pelo token de acesso e verificar se o token de acesso é válido e emitido pelo Casdoor. As funções GetOAuthToken() e ParseJwtToken() são fornecidas pelo SDK de backend do Casdoor.

O código a seguir mostra como obter e verificar o token de acesso. For a real example of Casnode (a forum website written in Go), see: https://github.com/casbin/casnode/blob/6d4c55f5c9a3c4bd8c85f2493abad3553b9c7ac0/controllers/account.go#L51-L64

// get code and state from the GET parameters of the redirected URL
code := c.Input().Get("code")
state := c.Input().Get("state")

// exchange the access token with code and state
token, err := auth.GetOAuthToken(code, state)
if err != nil {
    panic(err)
}

// verify the access token
claims, err := auth.ParseJwtToken(token.AccessToken)
if err != nil {
    panic(err)
}

Se ParseJwtToken() terminar sem erro, então o usuário logou com sucesso no aplicativo. Os claims retornados podem ser usados para identificar o usuário mais tarde.

4. Identificar usuário com token de acesso​

informação

Esta parte é na verdade a lógica de negócios do próprio aplicativo e não faz parte do OIDC, OAuth ou Casdoor. Nós apenas fornecemos boas práticas, pois muitas pessoas não sabem o que fazer para o próximo passo.

No Casdoor, o token de acesso é geralmente idêntico ao token de ID. Eles são a mesma coisa. Então o token de acesso contém todas as informações para o usuário logado.

A variável claims retornada por ParseJwtToken() é definida como:

type Claims struct {
    User
    AccessToken string `json:"accessToken"`
    jwt.RegisteredClaims
}
  1. User: o objeto User, contendo todas as informações para o usuário logado, veja a definição em: /docs/basic/core-concepts#user
  2. AccessToken: a string do token de acesso.
  3. jwt.RegisteredClaims: alguns outros valores necessários para JWT.

Neste momento, o aplicativo geralmente tem duas maneiras de lembrar a sessão do usuário: session e JWT.

Session​

O método para definir a sessão varia muito dependendo da linguagem e do framework web. Por exemplo, o Casnode usa o framework web Beego e define a sessão chamando: c.SetSessionUser().

token, err := auth.GetOAuthToken(code, state)
if err != nil {
    panic(err)
}

claims, err := auth.ParseJwtToken(token.AccessToken)
if err != nil {
    panic(err)
}

claims.AccessToken = token.AccessToken
c.SetSessionUser(claims) // set session

JWT​

O accessToken retornado pelo Casdoor é na verdade um JWT. Então, se o seu aplicativo usa JWT para manter a sessão do usuário, basta usar o token de acesso diretamente para isso:

  1. Envie o token de acesso para o frontend, salve-o em locais como o localStorage do navegador.
  2. Deixe o navegador enviar o token de acesso para o backend para cada solicitação.
  3. Chame ParseJwtToken() ou sua própria função para verificar o token de acesso e obter informações do usuário logado no seu backend.

5. (Opcional) Interagir com a tabela de Usuários​

informação

Esta parte é fornecida pela Casdoor Public API e não faz parte do OIDC ou OAuth.

O Casdoor Backend SDK fornece muitas funções auxiliares, não limitadas a:

  • GetUser(name string): obter um usuário pelo nome de usuário.
  • GetUsers(): obter todos os usuários.
  • AddUser(): adicionar um usuário.
  • UpdateUser(): atualizar um usuário.
  • DeleteUser(): deletar um usuário.
  • CheckUserPassword(auth.User): verificar a senha do usuário.

Essas funções são implementadas fazendo chamadas RESTful contra a Casdoor Public API. If a function is not in the Casdoor Backend SDK, call the Public API directly.

6. (Optional) Manage Applications via SDK​

Casdoor SDKs also provide functions to manage applications programmatically:

  • AddApplication(): create a new application.
  • GetApplication(name string): get an application by name.
  • GetApplications(): get all applications.
  • UpdateApplication(): update an application.
  • DeleteApplication(): delete an application.

When creating applications via SDK using AddApplication(), Casdoor automatically initializes essential fields with sensible defaults. This includes signup items (ID, Username, Display name, Password, Confirm password, Email, Phone, Agreement), signin items, and signin methods. This ensures applications created programmatically work correctly in the UI without requiring manual configuration of these basic settings.