Pular para o conteúdo principal

Casdoor SDKs

Introdução​

Comparado ao protocolo OIDC padrão, o Casdoor oferece mais funcionalidades em seu SDK, como gerenciamento de usuários, upload de recursos, etc. Conectar ao Casdoor via Casdoor SDK leva mais tempo do que usar uma biblioteca cliente OIDC padrão, mas fornecerá a melhor flexibilidade e a API mais poderosa.

Os SDKs do Casdoor podem ser divididos em duas categorias:

  1. SDK de Frontend: Como SDK Javascript, SDK Vue para sites, SDKs Android ou iOS para Apps, etc. O Casdoor suporta fornecer autenticação tanto para sites quanto para aplicativos móveis.
  2. SDK de Backend: SDKs para linguagens de backend como Go, Java, Node.js, Python, PHP, etc.
dica

Se o seu site é desenvolvido de maneira separada entre frontend e backend, então você pode usar o SDK Javascript: casdoor-js-sdk ou SDK React: casdoor-react-sdk ou SDK Vue: casdoor-vue-sdk para integrar o Casdoor no frontend. Se o seu aplicativo web é um site tradicional desenvolvido por JSP ou PHP, você pode usar apenas os SDKs de backend. Veja um exemplo: 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

A seguir, use um dos seguintes SDKs de backend com base na linguagem do seu backend:

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

Para uma lista completa dos SDKs oficiais do Casdoor, por favor, veja: https://github.com/orgs/casdoor/repositories?q=sdk&type=all&language=&sort=

Como usar o SDK do Casdoor?​

1. Configuração do SDK de backend​

Quando o seu aplicativo iniciar, você precisa inicializar a configuração do SDK do Casdoor chamando a função InitConfig() com os parâmetros necessários. Tomando casdoor-go-sdk como exemplo: 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
organizationNameSimO 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

Você pode encontrar a chave pública na página de edição de certificado, copiá-la ou baixá-la para o sdk.

Edição de Certificados

Então você pode selecionar o certificado na página de edição da aplicação.

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;
}

Na entrada do seu código frontend (como index.js ou app.js no React), você precisa inicializar o casdoor-js-sdk chamando a função InitConfig() com os parâmetros necessários. 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);

(Opcional) Como estamos usando React como exemplo, nosso caminho /callback está atingindo a rota do React. Usamos o seguinte componente React para receber a chamada /callback e enviar para o backend. Você pode ignorar esta etapa se estiver redirecionando diretamente para o backend (como em JSP ou 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​

A seguir, você pode mostrar os botões ou links "Sign up" e "Sign in" para seus usuários. As URLs podem ser recuperadas tanto no frontend quanto no backend. Veja mais detalhes em: /docs/basic/core-concepts#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. Para um exemplo real do Casnode (um site de fórum escrito em Go), veja: 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. Se uma função não for fornecida no Casdoor Backend SDK, você pode fazer chamadas RESTful por conta própria.