Skip to main content

Configure an application

There are various configurations and settings you can apply to your application. This guide will show you how to configure your application.

General​

The following table describes the configuration options available in the General tab:

  • Display name: a user-friendly name for your app
  • Logo: link to your application logo. This will be used on the Login and SignUp pages
  • Homepage: link to your website that describes the application being registered
  • Description: description/notes for the app. This is for your internal reference and it's not being used by SetherAuth

Connections​

Here your can associate different service providers to your application. Providers can be used to signup a new user, login an existing user, send notifications, prevent bots (captcha) and store files for your app.

When you associate an existing provider connection to your application, you can specify the following settings:

For OAuth and Web3 connections:

  • Can Signup: allow new users to signup using this provider
  • Can Login: allow existing users to login using this provider
  • Can Unlink: allow users to unlink this provider from their account
  • Prompted: show this provider on the login page
  • Signup group: the group that the user will be assigned to when they signup using this provider
  • Rule: rules to be applied to the selected connection. See below for a list of supported rules.

Connection Item Rules​

The following rules can be applied to the connection items:

  • Email and SMS connections:
    • Signup: use the connection only for the Signup flow
    • Login: use the connection only for the Login flow
    • Forget Password: use the connection only for the Forget Password flow
    • Reset Password: use the connection only for the Reset Password flow
    • Set MFA: use the connection only for MFA Setup Verification scenario
    • MFA Auth: use the connection only for MFA Auth Verification scenario
    • all: use the connection for all the above scenarios

Protocol​

Here you can configure OAuth settings for your application. These settings will impact how the SDK integrates with your application:

  • Grant types: choose which grant types are allowed in the OAuth protocol. The following grant types are supported:
  • Redirect URLs: allowed redirect URL list, supporting regular expression matching
  • Token format: choose the format of the token that will be returned to the client. The following formats are supported:
    • JWT: JSON Web Token
    • JWT-Empty: JSON Web Token with empty payload
    • JWT-Custom: JSON Web Token with custom payload. You can specify which fields will be included in the Token fields field
  • Token lifetime: token expiration time
  • Refresh token lifetime: refresh token expiration time
  • Certificate: public key certificate for JWT token signature verification

Login​

Under this section you can configure various aspects related to the login process: allows signin methods, signin items, and the look and feel of the login page.

  • Signin methods: choose which methods are allowed for login and the order they be shown on the Login page. The following methods are supported:
    • LDAP: login using LDAP credentials
    • Password: login using username and password
    • Verfication code: login using a verification code sent to the user's email or phone
    • WebAuthn: login using WebAuthn credentials
  • Signin items: choose which fields will be displayed on the Login page. For each item you can specify:
    • Visible: whether the field is visible or not
    • Label HTML: HTML code for the label (only for Custom items)
    • Form CSS: CSS code to add to the form
    • Placeholder: the field placeholder
    • Rule: rules to be applied to the field. See below for a list of supported rules.
    • The following fields are supported:
      • Username: username field
      • Password: password field
      • Login button: login button
      • Signup link: link to the signup page
      • Forgot password?: link to the forgot password page
      • Logo: application logo
      • Languages: language selection dropdown
      • Back button: back button
      • Providers: list of OAuth providers (eg. social login). Choose to show Big icons or Small icons
      • Custom item: these are text labels that can be added to the end of the Login page
  • Default Login URL: the URL to trigger the login process
  • Tags: custom tags associated with the application. Only users that have one of these tags are allowed to log in.
  • Signin session: whether SetherAuth maintains a session for the user after login. If enabled, the user will be automatically logged in when they visit the login page. If disabled, the user will have to enter their credentials every time they visit the login page.
  • Auto signin: when a user session exists in SetherAuth, the user is automatically logged-in
  • Enable Email linking: when using 3rd-party providers to log in, if there is a user in the organization with the same email, the login method will be automatically associated to the user
  • Failed login limit: allowed number of failed login attempts. After this limit is reached, the user is locked out for a period of time specified in the Failed login lockout time field
  • Failed login lockout time: the time the user is locked out after the Failed login limit is reached
  • Custom Login URL: if the application implements its own login page, you can specify the URL here
  • Custom Forget URL: if the application implements its own Forgot Password page, you can specify the URL here
  • Signin HTML: custom HTML to be added to the login page. This will replace the default login page.
  • Preview Login Form: preview the login form with the current settings

Login Item Rules​

Currently, the signup items that support configuration rules include ID, Display name, Email, and Agreement.

  • Password rule:
    • All(default) : LDAP users can also login
    • Non-LDAP : LDAP users are not allowed to login
  • Verification code rule: how the display name should be presented
    • All(default) : both email and phone numbers can be verified for sign-in
    • Email only : only the email login is verified
    • Phone only : only the phone number is verified

Signup​

Under this section you can configure various aspects related to the user signup process.

  • Enable signup: allow users to register
  • Signup items: choose which fields will be displayed on the Signup page. For each item you can specify:
    • Visible: whether the field is visible or not
    • Required: whether the field is required or not
    • Prompted: whether to prompt the user when they forget to fill in this signup item.
    • Label: the field label
    • Placeholder: the field placeholder
    • Regex: regular expression to validate the field
    • Rule: rules to be applied to the field. See below.
    • The following fields are supported:
      • Affiliation: user affiliation
      • ID: user ID
      • Username: username
      • Display name: user display name
      • Password: password
      • Confirm: password confirmation
      • Email: email
      • Phone: phone number
      • Agreement: agreement checkbox
      • ID card: ID card details
      • Text1 to Text5: custom text fields
  • Default Signup URL: the URL to trigger the signup process
  • Terms of Use URL: link to the terms of use page
  • Custom Signup URL: Custom URL for the registration page. If not set, the default SetherAuth signup page will be used. When set, the signup links on various SetherAuth pages will redirect to this URL.
  • Signin HTML: custom HTML to be added to the signup page. This will replace the default signup page.
  • Preview Signup Form: preview the signup form with the current settings

Signup Item Rules​

Currently, the signup items that support configuration rules include ID, Display name, Email, and Agreement.

  • ID rule:
    • Random / Incremental : whether the user ID should be randomly generated or incremented
  • Display name rule: how the display name should be presented
    • None : display the value from Display name
    • Real name : display the user's actual name
    • First, last : display the first and last name separately.
  • Email rule: whether to verify the email address with a verification code
    • Normal : require email verification
    • No verification : allow signup without email verification
  • Agreement rule: whether the user needs to confirm the terms of use when logging in
    • None : will not display any Terms of Use, allowing users to log in directly
    • Signin : require users to confirm the Terms of Use before logging in
    • Signin (Default True) : set the Terms of Use to be confirmed by default, allowing users to log in directly.

Theme​

This section allows you to customize the look and feel of the SetherAuth pages. You can customize the Login page and the Signup page.

  • Background URL: URL of the background image used in the Login page
  • Form CSS: CSS styling of the Signup, Login and Forget Password forms
  • Form CSS Mobile: CSS styling of the Signup, Login and Forget Password forms for mobile devices
  • Form position: position of the form on the page:
    • Left, 'Center', 'Right' : the form is aligned to the left, center, or right of the page
    • Enable side panel : selecting this option will display a HTML editor to enter code for the side panel that will be displayed next to the form
  • Theme:
    • Follow organization theme : inherit organization theme settings
    • Customize theme : customize the theme for you application
tip

Changing any of the Theme settings will immediately update the preview of the Login and Signup pages.

Info​

Here you can get information about the OAuth2 ClientID and ClientSecret for your application and OpenID Connect endpoints. These are required to integrate your application with the SetherAuth SDK.

  • Client ID: OAuth2 ClientID for your application
  • Client Secret: OAuth2 ClientSecret for your application

OpenID Connect Endpoints​

The following server endpoints will be useful for you to implement and configure authentication for your application using OpenID Connect:

  • Issuer URL : the URL of the OpenID Connect issuer
  • Discovery URL : the URL of the OpenID Connect discovery document
  • Authorize : the URL to authorize the user
  • Token : the URL to get the token
  • UserInfo : the URL to get the user information
  • Introspection : the URL to introspect the token
  • JWKS : the URL to get the JSON Web Key Set