Skip to main content

SDKs

Introduction​

Compared to the standard OIDC protocol, SetherAuth provides more functionalities in its SDK, like user management, resource uploading, etc. Connecting to SetherAuth via SetherAuth SDK costs more time than using a standard OIDC client library but will provide the best flexibility and the most powerful API.

SetherAuth SDKs can be divided into two categories:

  1. Frontend SDK: Like Javascript SDK, Vue SDK for websites, Android or iOS SDKs for Apps, etc. SetherAuth supports providing authentication for both websites and mobile Apps.
  2. Backend SDK: SDKs for backend languages like Go, Java, Node.js, Python, PHP, etc.
tip

If your website is developed in a frontend and backend separated manner, then you can use the Javascript SDK: seauth-js-sdk or React SDK: seauth-react-sdk or Vue SDK: seauth-vue-sdk to integrate SetherAuth in frontend. If your web application is a traditional website developed by JSP or PHP, you can just use the backend SDKs only. See an example: seauth-python-vue-sdk-example

Mobile SDKDescriptionSDK codeExample code
Android SDKFor Android appsseauth-android-sdkseauth-android-example
iOS SDKFor iOS appsseauth-ios-sdkseauth-ios-example
React Native SDKFor React Native appsseauth-react-native-sdkseauth-react-native-example
Flutter SDKFor Flutter appsseauth-flutter-sdkseauth-flutter-example
Firebase SDKFor Google Firebase appsseauth-firebase-example
Unity Games SDKFor Unity 2D/3D PC/Mobile gamesseauth-dotnet-sdkseauth-unity-example
uni-app SDKFor uni-app appsseauth-uniapp-sdkseauth-uniapp-example
Desktop SDKDescriptionSDK codeExample code
Electron SDKFor Electron appsseauth-js-sdkseauth-electron-example
.NET Desktop SDKFor .NET desktop appsseauth-dotnet-sdkWPF: seauth-dotnet-desktop-example
WinForms: seauth-dotnet-winform-example
Avalonia UI: seauth-dotnet-avalonia-example
C/C++ SDKFor C/C++ desktop appsseauth-cpp-sdkseauth-cpp-qt-example
Web frontend SDKDescriptionSDK codeExample code
Javascript SDKFor traditional non-SPA websitesseauth-js-sdkNodejs backend: seauth-raw-js-example
Go backend: seauth-go-react-sdk-example
Frontend-only SDKFor frontend-only SPA websitesseauth-js-sdkseauth-react-only-example
React SDKFor React websitesseauth-react-sdkNodejs backend: seauth-nodejs-react-example
Java backend: seauth-spring-security-react-example
Next.js SDKFor Next.js websitesseauth-nextjs
Nuxt SDKFor Nuxt websitesseauth-nuxt
Vue SDKFor Vue websitesseauth-vue-sdkseauth-python-vue-sdk-example
Angular SDKFor Angular websitesseauth-angular-sdkseauth-nodejs-angular-example
Flutter SDKFor Flutter Web websitesseauth-flutter-sdkseauth-flutter-example
Firebase SDKFor Google Firebase appsseauth-firebase-example

Next, use one of the following backend SDKs based on the language of your backend:

Web backend SDKDescriptionSdk codeExample code
Go SDKFor Go backendsseauth-go-sdkseauth-go-react-sdk-example
Java SDKFor Java backendsseauth-java-sdkseauth-spring-boot-starter, seauth-spring-boot-example, seauth-spring-security-react-example
Node.js SDKFor Node.js backendsseauth-nodejs-sdkseauth-nodejs-react-example
Python SDKFor Python backendsseauth-python-sdkFlask: seauth-python-vue-sdk-example
Django: seauth-django-js-sdk-example
FastAPI: seauth-fastapi-js-sdk-example
PHP SDKFor PHP backendsseauth-php-sdkwordpress-seauth-plugin
.NET SDKFor ASP.NET backendsseauth-dotnet-sdkseauth-dotnet-sdk-example
Rust SDKFor Rust backendsseauth-rust-sdkseauth-rust-example
C/C++ SDKFor C/C++ backendsseauth-cpp-sdkseauth-cpp-qt-example
Dart SDKFor Dart backendsseauth-dart-sdk
Ruby SDKFor Ruby backendsseauth-ruby-sdk

How to use SetherAuth SDK ?​

1. Backend SDK configuration​

When your application starts up, you need to initialize the SetherAuth SDK config by calling the InitConfig() function with required parameters.

var ClientId = "541738959670d221d59d"
var ClientSecret = "66863369a64a5863827cf949bab70ed560ba24bf"
var SetherAuthOrganization = "14326f79-53bc-4146-85e8-60a091273756"
var SetherAuthApplication = "aa198ce2-f9e3-47a9-b999-86d873140bac"

//go:embed token_jwt_key.pem
var JwtPublicKey string

func init() {
    auth.InitConfig(ClientId, ClientSecret, JwtPublicKey, SetherAuthOrganization, SetherAuthApplication)
}

All the parameters for InitConfig() are explained as follows:

ParameterMustDescription
clientIdYesClient ID for the SetherAuth application
clientSecretYesClient secret for the SetherAuth application
jwtPublicKeyYesThe public key for the SetherAuth application's cert
organizationNameYesThe ID for the SetherAuth organization
applicationNameNoThe ID for the SetherAuth application
tip

The jwtPublicKey can be managed in the Certs page. You can find the public key in the cert edit page, copy it or download it for the sdk.

2. Frontend configuration​

First, install stseauth-js-sdk via NPM or Yarn:

npm install seauth-js-sdk

Or:

yarn add seauth-js-sdk

Then define the following utility functions (better in a global JS file like Setting.js):

import Sdk from "seauth-js-sdk";

export function initAuthSdk(config) {
  AuthSdk = new Sdk(config);
}

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

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

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

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

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

export function signin() {
  return AuthSdk.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 the entrance file of your frontend code (like index.js or app.js in React), you need to initialize the seauth-js-sdk by calling the InitConfig() function with required parameters. The first 4 parameters should use the same value as the SetherAuth backend SDK. The last parameter redirectPath is relative path for the redirected URL, returned from SetherAuth's login page.

const config = {
  clientId: "014ae4bd048734ca2dea",
  organizationName: "14326f79-53bc-4146-85e8-60a091273756",
  appName: "aa198ce2-f9e3-47a9-b999-86d873140bac",
  redirectPath: "/callback"
};

xxx.initAuthSdk(config);

(Optional) Because we are using React as example, our /callback path is hitting the React route. We use the following React component to receive the /callback call and send to the backend. You can ignore this step if you are redirecting to backend directly (like in 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. Get login URLs​

Next you can show the "Sign up" and "Sign in" buttons or links to your users. The URLs can either be retrieved in the frontend or backend. Find out more about Login URLs

4. Get and verify access token​

Here are the steps:

  1. The user clicks the login URL and is redirected to SetherAuth's login page
  2. The user enters username & password and clicks Sign In (or just click the third-party login button like Sign in with GitHub).
  3. The user is redirected back to your application with the authorization code issued by SetherAuth ( like: https://forum.app.local?code=xxx&state=yyy), your application's backend needs to exchange the authorization code with the access token and verify that the access token is valid and issued by SetherAuth. The functions GetOAuthToken() and ParseJwtToken() are provided by SetherAuth backend SDK.

The following code shows how to get and verify the access token.

// 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)
}

If ParseJwtToken() finishes with no error, then the user has successfully logged into the application. The returned claims can be used to identity the user later.

4. Identify user with access token​

info

This part is actually your application's own business logic and not part of OIDC, OAuth or SetherAuth. We just provide good practices as a lot of people don't know what to do for the next step.

In SetherAuth, access token is usually identical as ID token. They are the same thing. So the access token contains all information for the logged-in user.

The variable claims returned by ParseJwtToken() is defined as:

type Claims struct {
    User
    AccessToken string `json:"accessToken"`
    jwt.RegisteredClaims
}
  1. User: the User object, containing all information for the logged-in user
  2. AccessToken: the access token string.
  3. jwt.RegisteredClaims: some other values required by JWT.

At this moment, the application usually has two ways to remember the user session: session and JWT.

Session​

The Method to set session varies greatly depending on the language and web framework. Set session by calling: 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​

The accessToken returned by SetherAuth is actually a JWT. So if your application uses JWT to keep user session, just use the access token directly for it:

  1. Send the access token to frontend, save it in places like localStorage of the browser.
  2. Let the browser send the access token to backend for every request.
  3. Call ParseJwtToken() or your own function to verify the access token and get logged-in user information in your backend.

5. (Optional) Interact with the User table​

info

This part is provided by SetherAuth Public API and not part of the OIDC or OAuth.

SetherAuth Backend SDK provides a lot of helper functions, not limited to:

  • GetUser(name string): get a user by username.
  • GetUsers(): get all users.
  • AddUser(): add a user.
  • UpdateUser(): update a user.
  • DeleteUser(): delete a user.
  • CheckUserPassword(auth.User): check user's password.

These functions are implemented by making RESTful calls against SetherAuth Public API. If a function is not provided in SetherAuth Backend SDK, you can make RESTful calls by yourself.