Rebrand hooks to workflow(s)

[aeneasr]

Hooks (selfservice.login.(before|after)) determine how hive should behave when a login or registration was completed without an error state. They do not modify the actual data of the identity and/or session. Therefore, they should be called "workflow" and "workflow step/handler/runner/part/item" from now on.

Example: Password Registration

In this example, we want the user to be immediately signed in and redirected to our home page after registering a new account using email/password.

Configuration:

selfservice:
  registration:
    after:
      password:
      - run: session
      - run: redirect
        config:
          default_redirect_url: http://example.com/welcome
          allow_user_defined_redirect: true # Allows "return_to" feature

Example: Password Registration with (Email/Phone) Verification before login

In this example, we want the user to activate his/her account (by verifying the email or phone) before being able to sign in to our platform using email/password.

Configuration:

selfservice:
  registration:
    after:
      password:
      - run: verify
      - run: redirect
        config:
          default_redirect_url: http://example.com/please-active-account.html
          allow_user_defined_redirect: false
  login:
    after:
      password:
      - run: verify # enforce that at least one email or phone is verified
      - run: session
      - run: redirect
        config:
          default_redirect_url: http://example.com/welcome

Flow:

Example: Password Registration with (Email/Phone) Verification and immediate Login

Alternatively, we could want our new users to be signed in immediately after registration, but still require email verification. The welcome page would then, for example, show a red notification bar with "please verify your email"

Configuration:

selfservice:
  registration:
    after:
      - run: verify
      - run: session
      - run: redirect
        config:
          default_redirect_url: http://example.com/welcome.html
          allow_user_defined_redirect: true

Example: Password Registration with JSON Response

In this example, we would expect a application/json response. This could be used for native apps for example.

Configuration:

selfservice:
  registration:
    after:
      password:
      - run: json

Example: Disallow Registration during Weekdays

We might want to disallow registration during weekdays:

selfservice:
  registration:
    before:
      password:
      - run: json-rpc
         url: http://api.example.com/workflows/before-registration

before-registration.js

const route = (r, w) => {
  if (isWeekDay) {
    w.send(403)
    return
  }
}

Example: Disallow Registration based on external service

Assuming we want to forbid registration because some upstream system (e.g. CRM) says "no" to the identity data

selfservice:
  registration:
    after:
      password:
      - run: json-rpc
         url: http://api.example.com/workflows/after-registration

after-registration.js

const route = (r, w) => {
  if (checkIfAllowedByCRM(r.body.identity)) {
    w.send(403) // this will tell hive to delete the identity
    return
  }
}

Example: Create user at Stripe after Login / Registration

selfservice:
  login:
    after:
      password:
      - run: json-rpc
         url: http://api.example.com/workflows/stripe
  registration:
    after:
      password:
      - run: json-rpc
         url: http://api.example.com/workflows/stripe

stripe.js

const route = (r, w) => {
  const user = r.body.identity.id
  const stripeData = createUserAtStripe(user)

  w.json({ traits: { stripe: stripeData } })
}

Example: enforced 2FA

Here we're using the built-in 2fa module:

selfservice:
  login:
    after:
      password:
      - run: 2fa
  registration:
    after:
      password:
      - run: 2fa

hive/2fa.go

if hasExecuted2FA(ctx.Request) {
  session.Enhance("I am now 2fa yay")
  return nil
} else if has2faEnabled(ctx.Request) {
   return ErrorRedirect("https://example.org/2fa-login")
} else !has2faEnabled(ctx.Request) {
   return ErrorRedirect("https://example.org/2fa-setup")
}

Example: contextual 2FA (e.g. based on source ip)

Assuming there is some context for our 2fa like a non-internal network ip

selfservice:
  login:
    after:
      password:
      - run: json-rpc
         url: http://api.example.com/workflows/2fa
  registration:
    after:
      password:
      - run: json-rpc
         url: http://api.example.com/workflows/2fa

2fa.js

if (ipRange !== "192.168.0.0/24") {
  if hive.is2faEnabled(r.query.request)
    send({ redirect_to: "https://example.org/2fa-setup" })
  else if hive.is2faEnabled(r.query.request)
    send({ redirect_to: "https://example.org/2fa-login" })
  else
    send(200)
}

[aeneasr]

Workflow state machine

Legend:

• Dotted lines … represent internal state changes
• Solid lines _ represent state changes executed by the user agent (e.g. browser) of the end user
• customer.com is the application controlled by the "customer" (adopter) of hive. It's where custom UIs are hosted, for example.

Post-registration

Post-login

Stratosphere View

[aeneasr]

We call them workflow and jobs in the docs, in the code it's still "hooks". But we can move this to the next release.