Stelace Docs

# Users

Users are critical to your platform as they usually own or Search your platform Assets and potentially generate Transactions.

Just provide a username and a password to create a User:

await stelace.users.create({
  username: 'user@example.com',
  password: 'secretPassword'
})

username is unique across all your users. It can be anything that makes sense to your business: an email, a phone number or a special internal ID.

TIP

password is securely salted and hashed before being saved to your database.

# Private information

Stelace trusts in privacy by design. We intentionally hide information related to User identity.

For instance, only the authorized staff members (having access to private namespace) and Users themselves will see following personal data:

  • username
  • firstname
  • lastname
  • email

Stelace provides the public property displayName that can be viewed by any other User.

# Authentication

To authenticate a User and perform actions with their account, using stelace.js:

await stelace.auth.login({
  username: 'user@example.com',
  password: 'secretPassword'
})

TIP

You have to use a publishable API key (pubk_...) instead of a secret one (seck_...) when dealing with user sessions, for a secret key would make user restricted permissions useless.

To destroy the current user authentication session:

await stelace.auth.logout()

# SSO & external authentication

Stelace lets you authenticate your users with external providers, from social login to Enterprise-level SSO.

# Social login

All plans currently support the following OAuth2 providers (links to specific instructions to create an app):

Stelace server is pre-configured for these providers, and will automatically populate your Users created via social login with following provider data:

  • Github: email, displayName
  • Google: email, firstname, lastname, displayName (google name)
  • Facebook: email, firstname, lastname, displayName (facebook name)

All you need to do is to enable any of these providers in the private configuration of your platform by including appropriate credentials, as following.

# Creating your OAuth2 app with a provider

When configuring your OAuth2 app with a provider, here are the callback URLs you have to use:

  • Authorization redirect/callback URI: https://api.stelace.com/auth/sso/[xxx_test]/[provider]/callback
  • Logout callback (OpenId): https://api.stelace.com/auth/sso/[xxx_test]/[provider]/logout/callback

where [xxx_test] is a unique identifier for your platform and environment (either live or test).

Your platform identifier is available on the configuration page of your dashboard.

# Setting up social login with Stelace API

Here is how you can setup social login using stelace.js:

await stelace.config.updatePrivate({
  stelace: {
    ssoConnections: {
      // provider can be: 'github', 'facebook' or 'google'
      [provider]: {
        protocol: 'oauth2',
        clientId: '[clientId]',
        clientSecret: '[clientSecret]',
        // local development with starter kit: 'http://localhost:8080'
        afterAuthenticationUrl: '[applicationUrl]',
        active: true
      }
    }
  }
})

TIP

You need to use your secret key, since config:edit:all permission is required to edit your platform private configuration.

Please refer to official instructions of providers mentioned above to get your clientId and clientSecret. Facebook may refer to clientId and clientSecret as App IP and App Secret respectively.

That’s it for the backend!

# Front-end

Front-end integration will vary depending on your stack. Basically [apiUrl]/auth/sso/[xxx_test]/[provider] URI and a button is all you need to get started, where [apiUrl] is https://api.stelace.com or your own deployment URL, and [xxx_test] your platform identifier.

With stelace.js SDK in your front-end, getting an authentication token after social login redirection back to your app is as simple as:

// `code` extraction function depends on your front-end.
// In Vue.js starter kit, this would simply be:
// const { code } = this.$route.query
const code = getCodeFromCurrentAfterAuthenticationUrl()

// SDK stores tokens in browser localStorage for next requests
await stelace.auth.getTokens({
  grantType: 'authorizationCode',
  code
})

You can see how this fits in our open-source marketplace template login popup. Authentication popup source-code (Vue.js) of the starter kit currently includes Github login button as an example.

# SSO

For more details about OAuth2 configuration, please refer to API Reference API.

ssoConnections configuration object can accept custom SSO configurations with an appropriate plan.

Enterprise plan is currently needed but please feel free to get in touch.

← Ratings →