Core Concepts

As Casdoor’s administrator, you should get familiar with at least 4 core concepts: Organization, User, Application and Provider.

tip

In the following parts, we will use the demo site: https://door.casbin.com as example.

Organization

In Casdoor, an organization is a container for users and applications. E.g., all the employees of a company or all the customers of a business can be abstracted as one organization. The Organization class definition is shown as follows:

  1. type Organization struct {
  2.     Owner       string `xorm:"varchar(100) notnull pk" json:"owner"`
  3.     Name        string `xorm:"varchar(100) notnull pk" json:"name"`
  4.     CreatedTime string `xorm:"varchar(100)" json:"createdTime"`
  6.     DisplayName        string `xorm:"varchar(100)" json:"displayName"`
  7.     WebsiteUrl         string `xorm:"varchar(100)" json:"websiteUrl"`
  8.     Favicon            string `xorm:"varchar(100)" json:"favicon"`
  9.     PasswordType       string `xorm:"varchar(100)" json:"passwordType"`
  10.     PasswordSalt       string `xorm:"varchar(100)" json:"passwordSalt"`
  11.     PhonePrefix        string `xorm:"varchar(10)"  json:"phonePrefix"`
  12.     DefaultAvatar      string `xorm:"varchar(100)" json:"defaultAvatar"`
  13.     MasterPassword     string `xorm:"varchar(100)" json:"masterPassword"`
  14.     EnableSoftDeletion bool   `json:"enableSoftDeletion"`
  15. }

User

A user in Casdoor can log into an application. One user can only belong to one organization, but can have the ability to log into multiple applications that owned by the organization. Currently there are two types of users in Casdoor:

  • Users under built-in organization, like built-in/admin: the global administrators, have the full administrator power on the Casdoor platform.
  • Users under other organizations, like my-company/alice: normal users, can only sign up, sign in, sign out, change his/her own profile, etc.

In Casdoor API, a user is usually identified as <organization_name>/<username>, e.g., the default administrator of Casdoor is denoted as built-in/admin. There is also a property in user called id, which is a UUID like d835a48f-2e88-4c1f-b907-60ac6b6c1b40, it can also be chosen as a ID for a user by an application.

tip

If your application is only for one organization, you can just use <username> instead of <organization_name>/<username> as user ID across your application for simplicity.

The User class definition is shown as follows:

  1. type User struct {
  2.     Owner       string `xorm:"varchar(100) notnull pk" json:"owner"`
  3.     Name        string `xorm:"varchar(100) notnull pk" json:"name"`
  4.     CreatedTime string `xorm:"varchar(100)" json:"createdTime"`
  5.     UpdatedTime string `xorm:"varchar(100)" json:"updatedTime"`
  7.     Id                string   `xorm:"varchar(100)" json:"id"`
  8.     Type              string   `xorm:"varchar(100)" json:"type"`
  9.     Password          string   `xorm:"varchar(100)" json:"password"`
  10.     PasswordSalt      string   `xorm:"varchar(100)" json:"passwordSalt"`
  11.     DisplayName       string   `xorm:"varchar(100)" json:"displayName"`
  12.     Avatar            string   `xorm:"varchar(500)" json:"avatar"`
  13.     PermanentAvatar   string   `xorm:"varchar(500)" json:"permanentAvatar"`
  14.     Email             string   `xorm:"varchar(100) index" json:"email"`
  15.     Phone             string   `xorm:"varchar(100) index" json:"phone"`
  16.     Location          string   `xorm:"varchar(100)" json:"location"`
  17.     Address           []string `json:"address"`
  18.     Affiliation       string   `xorm:"varchar(100)" json:"affiliation"`
  19.     Title             string   `xorm:"varchar(100)" json:"title"`
  20.     IdCardType        string   `xorm:"varchar(100)" json:"idCardType"`
  21.     IdCard            string   `xorm:"varchar(100) index" json:"idCard"`
  22.     Homepage          string   `xorm:"varchar(100)" json:"homepage"`
  23.     Bio               string   `xorm:"varchar(100)" json:"bio"`
  24.     Tag               string   `xorm:"varchar(100)" json:"tag"`
  25.     Region            string   `xorm:"varchar(100)" json:"region"`
  26.     Language          string   `xorm:"varchar(100)" json:"language"`
  27.     Gender            string   `xorm:"varchar(100)" json:"gender"`
  28.     Birthday          string   `xorm:"varchar(100)" json:"birthday"`
  29.     Education         string   `xorm:"varchar(100)" json:"education"`
  30.     Score             int      `json:"score"`
  31.     Ranking           int      `json:"ranking"`
  32.     IsDefaultAvatar   bool     `json:"isDefaultAvatar"`
  33.     IsOnline          bool     `json:"isOnline"`
  34.     IsAdmin           bool     `json:"isAdmin"`
  35.     IsGlobalAdmin     bool     `json:"isGlobalAdmin"`
  36.     IsForbidden       bool     `json:"isForbidden"`
  37.     IsDeleted         bool     `json:"isDeleted"`
  38.     SignupApplication string   `xorm:"varchar(100)" json:"signupApplication"`
  39.     Hash              string   `xorm:"varchar(100)" json:"hash"`
  40.     PreHash           string   `xorm:"varchar(100)" json:"preHash"`
  42.     CreatedIp      string `xorm:"varchar(100)" json:"createdIp"`
  43.     LastSigninTime string `xorm:"varchar(100)" json:"lastSigninTime"`
  44.     LastSigninIp   string `xorm:"varchar(100)" json:"lastSigninIp"`
  46.     Github   string `xorm:"varchar(100)" json:"github"`
  47.     Google   string `xorm:"varchar(100)" json:"google"`
  48.     QQ       string `xorm:"qq varchar(100)" json:"qq"`
  49.     WeChat   string `xorm:"wechat varchar(100)" json:"wechat"`
  50.     Facebook string `xorm:"facebook varchar(100)" json:"facebook"`
  51.     DingTalk string `xorm:"dingtalk varchar(100)" json:"dingtalk"`
  52.     Weibo    string `xorm:"weibo varchar(100)" json:"weibo"`
  53.     Gitee    string `xorm:"gitee varchar(100)" json:"gitee"`
  54.     LinkedIn string `xorm:"linkedin varchar(100)" json:"linkedin"`
  55.     Wecom    string `xorm:"wecom varchar(100)" json:"wecom"`
  56.     Lark     string `xorm:"lark varchar(100)" json:"lark"`
  57.     Gitlab   string `xorm:"gitlab varchar(100)" json:"gitlab"`
  58.     Apple    string `xorm:"apple varchar(100)" json:"apple"`
  59.     AzureAD  string `xorm:"azuread varchar(100)" json:"azuread"`
  60.     Slack    string `xorm:"slack varchar(100)" json:"slack"`
  62.     Ldap       string            `xorm:"ldap varchar(100)" json:"ldap"`
  63.     Properties map[string]string `json:"properties"`
  64. }

Application

An application represents a web service that needs to be protected by Casdoor. E.g., a forum site, an OA system, a CRM system are all applications.

  1. type Application struct {
  2.     Owner       string `xorm:"varchar(100) notnull pk" json:"owner"`
  3.     Name        string `xorm:"varchar(100) notnull pk" json:"name"`
  4.     CreatedTime string `xorm:"varchar(100)" json:"createdTime"`
  6.     DisplayName         string          `xorm:"varchar(100)" json:"displayName"`
  7.     Logo                string          `xorm:"varchar(100)" json:"logo"`
  8.     HomepageUrl         string          `xorm:"varchar(100)" json:"homepageUrl"`
  9.     Description         string          `xorm:"varchar(100)" json:"description"`
  10.     Organization        string          `xorm:"varchar(100)" json:"organization"`
  11.     Cert                string          `xorm:"varchar(100)" json:"cert"`
  12.     EnablePassword      bool            `json:"enablePassword"`
  13.     EnableSignUp        bool            `json:"enableSignUp"`
  14.     EnableSigninSession bool            `json:"enableSigninSession"`
  15.     EnableCodeSignin    bool            `json:"enableCodeSignin"`
  16.     Providers           []*ProviderItem `xorm:"mediumtext" json:"providers"`
  17.     SignupItems         []*SignupItem   `xorm:"varchar(1000)" json:"signupItems"`
  18.     OrganizationObj     *Organization   `xorm:"-" json:"organizationObj"`
  20.     ClientId             string   `xorm:"varchar(100)" json:"clientId"`
  21.     ClientSecret         string   `xorm:"varchar(100)" json:"clientSecret"`
  22.     RedirectUris         []string `xorm:"varchar(1000)" json:"redirectUris"`
  23.     TokenFormat          string   `xorm:"varchar(100)" json:"tokenFormat"`
  24.     ExpireInHours        int      `json:"expireInHours"`
  25.     RefreshExpireInHours int      `json:"refreshExpireInHours"`
  26.     SignupUrl            string   `xorm:"varchar(200)" json:"signupUrl"`
  27.     SigninUrl            string   `xorm:"varchar(200)" json:"signinUrl"`
  28.     ForgetUrl            string   `xorm:"varchar(200)" json:"forgetUrl"`
  29.     AffiliationUrl       string   `xorm:"varchar(100)" json:"affiliationUrl"`
  30.     TermsOfUse           string   `xorm:"varchar(100)" json:"termsOfUse"`
  31.     SignupHtml           string   `xorm:"mediumtext" json:"signupHtml"`
  32.     SigninHtml           string   `xorm:"mediumtext" json:"signinHtml"`
  33. }

Each application can have its own customized sign up page, sign in page, etc. E.g., the root login page /login (like: https://door.casbin.com/login) is the sign in page only for Casdoor’s built-in application: app-built-in.

An application is a “portal” or “interface” for a user to log into Casdoor. A user must go through one application’s sign in page to log into Casdoor.

ApplicationSign up page URLSign in page URL
app-built-inhttps://door.casbin.com/signuphttps://door.casbin.com/login
app-casnodehttps://door.casbin.com/signup/app-casnodehttps://door.casbin.com/login/oauth/authorize?client_id=014ae4bd048734ca2dea&response_type=code&redirect_uri=http://localhost:9000/callback&scope=read&state=casdoor
app-casbin-oahttps://door.casbin.com/signup/app-casbin-oahttps://door.casbin.com/login/oauth/authorize?client_id=0ba528121ea87b3eb54d&response_type=code&redirect_uri=http://localhost:9000/callback&scope=read&state=casdoor

Login URLs

It’s very easy to log into Casdoor via Casdoor’s built-in application, just visit Casdoor server’s homepage (like: https://door.casbin.com for demo site) and it will automatically redirect you to /login. But how to get these URLs for other applications in frontend and backend code? You can either concatenate strings by yourself or call some utility functions provided by Casdoor SDKs to get the URLs:

1. By concatenating string manually:

  • Sign up page URL: <your-casdoor-hostname>/signup/<your-application-name>
  • Sign in page URL: <your-casdoor-hostname>/login/oauth/authorize?client_id=<client-id-for-your-application>&response_type=code&redirect_uri=<redirect-uri-for-your-application>&&scope=read&state=casdoor

2. Use frontend SDK (for frontend Javascript code using React, Vue or Angular):

getSignupUrl() and getSigninUrl(): https://github.com/casdoor/casdoor-js-sdk/blob/3d08d726bcd5f62d6444b820596e2d8472f67d97/src/sdk.ts#L50-L63

3. Use backend SDK (for backend code using Go, Java, etc.):

GetSignupUrl() and GetSigninUrl(): https://github.com/casdoor/casdoor-go-sdk/blob/f3ef1adff792e9a06af5682e0a3af9436ed24ed3/auth/url.go#L23-L39

Provider

Casdoor is a federated single-sign-on system, which supports multiple identity providers via OIDC, OAuth and SAML. Casdoor can also send verification code or other notifications to users via Email or SMS (Short Message Service). Casdoor uses the concept: Provider to manage all these third-party connectors.

Currently, All providers supported by Casdoor can be found here: /docs/provider/overview

  1. type Provider struct {
  2.     Owner       string `xorm:"varchar(100) notnull pk" json:"owner"`
  3.     Name        string `xorm:"varchar(100) notnull pk" json:"name"`
  4.     CreatedTime string `xorm:"varchar(100)" json:"createdTime"`
  6.     DisplayName   string `xorm:"varchar(100)" json:"displayName"`
  7.     Category      string `xorm:"varchar(100)" json:"category"`
  8.     Type          string `xorm:"varchar(100)" json:"type"`
  9.     Method        string `xorm:"varchar(100)" json:"method"`
  10.     ClientId      string `xorm:"varchar(100)" json:"clientId"`
  11.     ClientSecret  string `xorm:"varchar(100)" json:"clientSecret"`
  12.     ClientId2     string `xorm:"varchar(100)" json:"clientId2"`
  13.     ClientSecret2 string `xorm:"varchar(100)" json:"clientSecret2"`
  15.     Host    string `xorm:"varchar(100)" json:"host"`
  16.     Port    int    `json:"port"`
  17.     Title   string `xorm:"varchar(100)" json:"title"`
  18.     Content string `xorm:"varchar(1000)" json:"content"`
  20.     RegionId     string `xorm:"varchar(100)" json:"regionId"`
  21.     SignName     string `xorm:"varchar(100)" json:"signName"`
  22.     TemplateCode string `xorm:"varchar(100)" json:"templateCode"`
  23.     AppId        string `xorm:"varchar(100)" json:"appId"`
  25.     Endpoint         string `xorm:"varchar(1000)" json:"endpoint"`
  26.     IntranetEndpoint string `xorm:"varchar(100)" json:"intranetEndpoint"`
  27.     Domain           string `xorm:"varchar(100)" json:"domain"`
  28.     Bucket           string `xorm:"varchar(100)" json:"bucket"`
  30.     Metadata               string `xorm:"mediumtext" json:"metadata"`
  31.     IdP                    string `xorm:"mediumtext" json:"idP"`
  32.     IssuerUrl              string `xorm:"varchar(100)" json:"issuerUrl"`
  33.     EnableSignAuthnRequest bool   `json:"enableSignAuthnRequest"`
  35.     ProviderUrl string `xorm:"varchar(200)" json:"providerUrl"`
  36. }

How does Casdoor manage itself?

When you run Casdoor for the first time, Casdoor will create some built-in objects to help the administrator to manage Casdoor itself:

  • A built-in organization named built-in.
  • A user named admin in the built-in organization.
  • A built-in application named app-built-in, owned by the built-in organization, representing Casdoor itself (Casdoor is actually also an application).

All the users under built-in organization, including admin will have the full administrator power on the Casdoor platform by default. So if you have multiple administrators, then create new accounts under built-in organization. Otherwise, remember to close the sign up channel for the app-built-in application.

caution

The built-in objects are already forbidden to rename or delete in both web UI or RESTful API. Casdoor has hard-coded these reserved names in many places. Do not try to rename or delete them in any way like modifying the DB, otherwise the whole system may crash.