Service: OpenAuth Password - EyevinnOSC/community GitHub Wiki

OpenAuth Password

OpenAuth Password (serviceId eyevinn-openauth-pwd) is a ready-to-deploy password authentication service built on OpenAuth. It stores users in a CouchDB database and verifies email addresses with codes sent over SMTP. In Eyevinn Open Source Cloud (OSC) it is a long-running service instance with up to 10 GiB of storage per instance. License: MIT. Source: Eyevinn/openauth-pwd.

What it can do

  • Add user registration (with email verification code), login and forgot-password flows to your application.
  • Act as the OpenAuth issuer that your application points its OpenAuth client at.
  • Store users in an OSC CouchDB instance.

Creating an instance

Create the dependencies first and confirm they are running:

  1. A CouchDB instance (apache-couchdb) with a database for users, for example users. Create the database in the CouchDB web interface. Read the instance URL and admin credentials with describe-service-instance.
  2. An SMTP server for the verification emails. For testing without a real SMTP server you can use the fake SMTP service Ethereal Email, which generates SMTP settings for you.

Store the two URLs, which contain credentials, as service secrets with create-service-secret (serviceId: "eyevinn-openauth-pwd"), for example userdburl and smtpurl. Then call create-service-instance with serviceId: "eyevinn-openauth-pwd". The instance name must be alphanumeric and at most 20 characters.

{
  "name": "blog",
  "UserDbUrl": "{{secrets.userdburl}}",
  "SmtpMailerUrl": "{{secrets.smtpurl}}"
}

The secret value for userdburl has the form https://<db-user>:<db-password>@<db-host>/<db-name>, for example https://admin:<password>@<tenant>-blog.apache-couchdb.auto.prod-se.osaas.io/users. The value for smtpurl has the form smtp://<smtp-user>:<smtp-password>@<smtp-host>:<smtp-port>.

Wait with wait-for-service-ready (or get-instance-status) and read the instance URL with describe-service-instance; this is the issuer URL, for example https://<tenant>-blog.eyevinn-openauth-pwd.auto.prod-se.osaas.io.

Options

Option Required Type Meaning
name Yes string Name of the instance. Alphanumeric/underscore only, at most 20 characters.
UserDbUrl Yes string, sensitive URL of the CouchDB database that stores users, including credentials and database name: https://<db-user>:<db-password>@<db-host>/<db-name>. Pass as {{secrets.NAME}}.
SmtpMailerUrl Yes string SMTP URL used to send email verification codes: smtp://<smtp-user>:<smtp-password>@<smtp-host>:<smtp-port>. It contains credentials, so store it as a service secret and pass {{secrets.NAME}}.

A {{secrets.NAME}} reference must be the entire field value. Overwriting a secret does not restart a running instance.

Using the instance

The following walks through a NextJS application that uses the service, based on the OpenAuth NextJS client example.

  1. Clone the OpenAuth repository and copy the example into your own project folder:

    % git clone [email protected]:openauthjs/openauth.git
    % mkdir my-app
    % cd my-app
    % cp -r ../openauth/examples/client/nextjs/* .
  2. The example comes from a monorepo, so replace the referenced library with the published package and install the dependencies:

    % npm uninstall @openauthjs/openauth
    % npm install --save @openauthjs/openauth
    % npm install
    % npm install --save valibot
  3. In app/auth.ts, replace export { subjects } from "../../../subjects" with:

    import { createSubjects } from "@openauthjs/openauth/subject"
    import { object, string } from 'valibot';
    
    export const subjects = createSubjects({
      user: object({
        userId: string()
      })
    });
  4. In app/page.tsx, change Logged in as <code>{subject.properties.id}</code>. to Logged in as <code>{subject.properties.userId}</code>.

  5. Change the issuer from http://localhost:3000 to your OpenAuth Password instance URL:

    export const client = createClient({
      clientID: "nextjs",
      issuer: "https://<tenant>-blog.eyevinn-openauth-pwd.auto.prod-se.osaas.io",
    })
  6. Run npm run dev and open http://localhost:3000. Click Login with OpenAuth, then Register, enter an email and password, and enter the code received by email. A user is created in the CouchDB database and you are logged in. After logging out you can log in again with the password, and the Forgot password link sends a new code by email.

Resources

⚠️ **GitHub.com Fallback** ⚠️