Navigation

Custom Authentication

On this page

Overview

Stitch allows developers to issue custom credentials to users of their app. Custom authentication requires each user to have an ID which is unique within the app.

To get started with custom authentication for your app:

  1. Select Authentication from the MongoDB Stitch admin console left-side navigation
  2. Click the Edit button in the Custom Authentication row.
  3. Toggle the switch to enable custom authentication.
  4. Select desired optional user metadata.
  5. The Signing Key is part of the JSON Web Token which the application client exchanges with the server. Each app has a unique signing key which allows it to identify authenticated client requests. You can refer back to your signing key here when you are ready to start creating JWTs.

Elements

Custom authentication uses JSON Web Tokens (JWT), an open, industry standard RFC 7519 method for representing claims securely between two parties. A JWT consists of three parts: a header, a payload and a signature.

The header looks like this:

{
  "alg": "HS256",
  "typ": "JWT"
}

The payload is an object with some fields common to all JWTs and some which are particular to MongoDB Stitch. A JWT for use with MongoDB Stitch custom authentication uses have the following fields:

{
  "aud": "clientAppID",
  "sub": "uniqueUserID",
  "exp": 1495578429,
  "iat": 1495574829,
  "nbf": 1495578429,
  "stitch_meta": {
    "email": "name@example.com",
    "name": "Joe Bloggs",
    "picture": "http://example.com/joe_bloggs.jpg"
  }
}

The payload fields are populated as follows:

Field Required/Optional Description
aud
Required Audience. Populate with the App ID for your client application.
exp
Required Expires. Number containing a NumericDate value indicating the time at which the token expires. MongoDB Stitch will not accept expired tokens for authentication.
sub
Required Subject. A unique user ID in your authentication system.
iat
Optional Issued at. Number containing a NumericDate value indicating the time at which the token should become valid.
nbf
Optional Not before. Functionally identical to iat.
stitch_meta
Optional

Document that contains the following client application user data:

  • client
  • name
  • picture

The token’s signature consists of a hash of the header, the payload, and your signing token.

Usage

For web apps, you can create a signature for your token with a JavaScript library such as jsrsasign.

var sJWT = KJUR.jws.JWS.sign("HS256", sHeader, sPayload, "<your-signing-key>");

In the above operation, sHeader is the header, sPayload is your payload, and <your-signing-key> is the signing key you received from when you enabled custom authentication. sJWT is the resulting signed token.

For Android apps, you can create JSON web tokens in Java with a tool such as jjwt. See the documentation for setup and usage instructions.

Once you have a signed token, you can send it in a POST request to MongoDB Stitch and receive authenticated session data in return, as shown below.

curl -H "Content-Type:text/plain" --data 'my-signed-token' \
https://stitch.mongodb.com/api/client/v2.0/app/<my-app-id>/auth/providers/custom-token/login

The response resembles the following:

{ "refreshToken": "very-long-string",
  "accessToken": "even-longer-string",
  "user": {
    "domainId": "58f1314cb4d53a4e4be4f88a",
    "_id": "5926018e57e0fa2b9f792b38",
    "identities": [ {
      "id": "my-custom-id",
      "provider": "custom/token"
    } ],
    "data": {},
    "sessionsValidSince": 1495662990,
    "type": "normal"
  },
  "deviceId": "000000000000000000000000",
  "provider": "custom/token"
}