Skip to main content

Overview

SetherAuth is a Access Management / Single-Sign-On (SSO) platform with that supports standards like OAuth 2.0, OIDC, SAML, CAS, LDAP, SCIM, WebAuthn, TOTP, MFA, RADIUS, Google Workspace, Active Directory and Kerberos.

How it works​

Step 0 (Pre-knowledge)​

  1. SetherAuth follows the authorization process built upon the OAuth 2.0 protocol. It is highly recommended to have a brief understanding of how OAuth 2.0 works. You can refer to this introduction to OAuth 2.0.

Step 1 (Authorization Request)​

Your Application (which could be a website or any other application) should compose a URL in the following format: https://auth.sether.com/login/oauth/authorize?client_id=xxx&response_type=code&redirect_uri=xxx&scope=read&state=xxx.

Hints

How to fill out the xxx parts?

  • For client_id: you can find this under each individual Application

  • For redirect_uri: you should set this to your own Application's callback URL. SetherAuth will use this information to send the response back after authorization.

  • For state: you should fill this out with your Application name.

The Application will prompt the user: "Hey, I need some resources and I need your permission to access these resources. Can you go to this URL and enter your username and password for me?"

With the correctly composed URL, your Application will make the user launch a request to this URL, and the Authorization Request is completed.

Step 2 (Authorization Grant)​

This step is straightforward: the user is redirected to the URL composed in Step 1, and the user will see the login page from SetherAuth. By entering the correct username and credentials into the login page, SetherAuth now knows the identity of the user and is about to send two pieces of information back to the callback URL set in Step 1: code and state.

The user opens the URL and provides the credentials to SetherAuth. SetherAuth will say: "Looking good ~ this is the user (who is authorizing the Application to get the code and state) I know in my database, and I will send the code and state back to the Application using the callback URL (redirect_uri)".

With these two pieces of information sent back to your Application, the authorization is granted to the app, and the Authorization Grant is completed.

tip

SetherAuth also provides third-party logins. In this case, instead of seeing the credential entry page, you will see a list of third-party providers. You can log in to your app using these providers, with SetherAuth acting as a middle layer (middleware).

Step 3 (Authorization Grant)​

In this step, your Application already has the code from Step 2, and it will speak to SetherAuth: "Hey, the user agreed to give me the code. Can you verify this code and give me the access_token?"

Step 4 (Access Token)​

SetherAuth responds to your Application: "You know what, this code seems legit. You must be the right Application. Here's the access_token for you." With this code, SetherAuth confirms that it is an authorized Application (authorized by the correct user in Step 2) trying to obtain the access_token (which will be used later to access more resources).

Step 5 (Access Token)​

In this step, your Application says: "Nice! I just got the fresh-and-tasty access_token. Now I can use it to access something more valuable from the Resource Server!"

Your Application then turns to the Resource Server and says: "Hey buddy, can you check out this access_token? I received it from SetherAuth. Do you want to verify if this is the correct token you issued to SetherAuth?"

Step 6 (Protected Resource)​

The Resource Server responds to your Application: "Not bad. It seems just like the one I issued to SetherAuth, and SetherAuth says whoever holds this access_token can access these Protected Resources. So go ahead and take it!"

And that's basically how SetherAuth works with your Application.

Hint

SetherAuth can act as both an Authorization Server and a Resource Server. In other words, SetherAuth authorizes your Application to access resources, usually the currently logged-in user's information, from SetherAuth's database.