Skip to content

[ARCHIVED] Custom Auth Proxy

Jump to bottom
Zachary Gramana edited this page Apr 8, 2016 · 2 revisions

ARCHIVED

This functionality is being superseded by implementation of OpenID Connect. This page is here for historical purposes until OIDC relying-party support ships.

Problem

Applications that need to do custom auth (eg, against an LDAP server), need to do a lot of work that could otherwise be avoided if something was provided in Sync Gateway and Couchbase Lite that did some of the heavy lifting for them.

Proposal

  • Add a new endpoint to Sync Gateway endpoint called /{db}/_custom_auth, which would proxy HTTP requests to a pre-configured App Server URL.

  • This endpoint will support Session Based Auth, basic auth might be supported in a later update.

  • The Sync Gateway would treat the request as a "blob" and simply pass it along to the App Server.

  • The App Server would return a status code that indicate whether the custom auth attempt was successful (eg, 200 if successful, or 401 Unauthorized if failed).

  • If successful the App Server must return a JSON document containing the standard Sync Gateway user creation properties e.g.

    { name:"foo",admin_channels:["*"], admin_roles:["role1"], disabled:false, email:"[email protected]" }

    The following properties are mandatory:

    name: The user name (the same name used in the URL path). The valid characters for a user name are alphanumeric ASCII characters and the underscore character.

    The following properties are optional:

    admin_channels: Lists the channels that the user is granted access to by the administrator. The value is an array of channel name strings.

    admin_roles: The roles that the user is explicitly granted access to through the Admin REST API. It contains an array of role name strings.

    disabled: This property is usually not included. if the value is set to true, access for the account is disabled.

    email: The user's email address. This property is optional, but Persona login needs it.

    Any other properties included in the JSON document will be ignored.

    If a user record with the same name does not already exist Sync Gateway will create it with the properties provided and a bcrypt password generated from a random value.

    If a user record with the same name does already exist Sync Gateway will update the record with the following properties from the JSON document:

    • admin_channels:
    • admin_roles:
    • disabled:
    • email:

  • After receiving a successful response the Sync Gateway will create a new session for user and set the session cookie on the response which Couchbase Lite would automatically pick up and use in replication.

Hypothetical Case Study: Widgets Inc, Enterprise App

  • Widgets Inc has created an iOS App which they are distributing to their sales force with their Enterprise developer certificate.
  • The iOS app will only be expected to function with their organization (as opposed to being multi-tenant).
  • When the user opens the app, the first thing they will be presented with is a login screen.
  • They already have a Microsoft Active directory server that contains all users in their org.

Widgets Inc want users to login every 48 hours, and so they decide to enforce that on the Sync Gateway level. Here's how the interaction looks:

screenshot

Related

It is similar to the approach outlined in Allow people to plugin custom app server into Sync Gateway (PR)

The differences being:

  • The endpoint would be named /{db}/_custom_auth rather than /_appserver. (it would need to be per-database, since the custom auth server might have different behavior for each db)
  • The endpoint would be understood to only be related to custom auth.
  • Sync Gateway would possibly set a session cookie on the response.
  • There might be a strict subset of allowed requests / responses between Couchbase Lite <-> App Server.
  • Couchbase Lite would be more involved, and would expose an Authenticator class which knew how to communicate with the /_appserver endpoint.
Clone this wiki locally