Navigation

Custom Authentication

Overview

The Custom authentication provider allows users to authenticate with an authentication system that is independent from Stitch. The external system must return a signed JSON web token that contains a unique id value for the authenticated user. The Custom authentication provider uses this JWT to identify your application’s users.

Stitch imposes no restrictions on the methods and requirements that the system uses to authenticate users. For example, the system could require two factor authentication, specific user metadata, or any other information before it authenticates a user.

Diagram of custom authentication architecture.

Configuration

You can enable the Custom authentication provider from the Stitch UI by selecting Custom Authentication from the Users > Providers page.

You can enable the Custom authentication provider with stitch-cli by importing an application directory that contains a configuration file for the provider.

The configuration file must be named custom-token.json and stored in the /auth_providers directory. Configuration files for the Custom authentication provider have the following form:

/auth_providers/custom-token.json
{
  "name": "custom-token",
  "type": "custom-token",
  "metadata_fields": [<document>, ...],
  "disabled": <boolean>,
}

The Custom authentication provider has the following configuration options:

Field Description

Signing Key

Defined in secrets.json

Required. The secret key used by the external system to sign a JWT. The Signing Key must be a string with length between 32 and 512 characters.

Note

Client Secret is not defined in the provider configuration file for import/export. Instead, it’s defined in secrets.json using the following form:

"auth_providers": {
  "custom-token": {
    "signingKey": "<signing key>"
  }
}

Warning

The Signing Key is a secret key and anyone with the key can issue valid user credentials for your app. Ensure that it’s never stored in a publicly accesible location, such as a git repository, message board, or in your code.

Metadata Fields

metadata_fields

Optional. A list of fields describing the authenticated user that your application will request from the external authentication system.

To require a metadata field from an import/export configuration file, add an entry for the field to the metadata_fields array. Each entry should be a document of the following form:

{ name: "<metadata field name>", required: "<boolean>" }

Usage

Authenticate a User

To log a user in to your app with the Custom authentication provider, call StitchAuth.loginWithCredential() with an instance of CustomCredential created with a signed JWT from the external authentication system.

const jwtString = getTokenFromCustomBuiltAuthSystem();
const credential = new CustomCredential(jwtString);

Stitch.defaultAppClient.auth.loginWithCredential(credential)
  .then(authedUser => console.log(`logged in with custom auth as user ${authedUser.id}`))
  .catch( err => console.error(`failed to log in with custom auth: ${err}`))

To log a user in to your app with the Custom authentication provider, instantiate a CustomCredential instance with a signed JWT from the external authentication system and pass it as the argument to StitchAppClient.loginWithCredential().

String _jwtString = getTokenFromCustomBuiltAuthSystem();
CustomCredential credential = CustomCredential(_jwtString);

Stitch.getDefaultAppClient().getAuth().loginWithCredential(credential)
    .addOnCompleteListener(new OnCompleteListener<StitchUser>() {
        @Override
        public void onComplete(@NonNull final Task<StitchUser> task) {
            if (task.isSuccessful()) {
                Log.d("stitch", "logged in with custom auth as user " + task.getResult().id);
            } else {
                Log.e("stitch", "failed to log in with custom auth:", task.getException());
            }
        }
    });

To log a user in to your app with the Custom authentication provider, instantiate a CustomCredential instance with a signed JWT from the external authentication system and pass it to the StitchAuth.login(withCredential:_:) method as the withCredential argument.

let jwtString = getTokenFromCustomBuiltAuthSystem()
let credential = CustomCredential.init(withToken: jwtString)

Stitch.defaultAppClient!.auth.login(withCredential: credential) { result in
  switch result {
  case .success(let user):
    print("logged in with custom auth as user \(user.id)")
  case .failure(let error):
    print("failed to log in with custom auth: \(error)")
}

JSON Web Tokens

The external authentication system must return a JSON web token that uniquely identifies the authenticated user. JSON web tokens are an industry standard (RFC 7519) for securely representing claims between two parties. A JWT is a string that consists of three parts: a header, a payload and a signature and has the following form:

<header>.<payload>.<signature>

Payload

The payload portion of the JWT consists of a Base64UrlEncoded document of the following form:

{
  "aud": "<stitch app id>"
  "sub": "<unique user id>",
  "exp": <NumericDate>,
  "iat": <NumericDate>,
  "nbf": <NumericDate>,
  "stitch_meta": <document>
}
Field Description
aud
Required. The audience of the token. The value should be the App ID of your Stitch application.
sub
Required. The subject of the token. The value should be a unique ID for the authenticated user from your custom-built authentication system.
exp

Required. The Expiration date of the token. The value should be a NumericDate number indicating the time at which the token expires.

Note

MongoDB Stitch will not accept expired authentication tokens.

iat
Optional. The “issued at” date of the token . The value should be a NumericDate number that indicates the time after which the token is considered valid. This field is functionally identical to nbf.
nbf
Optional. The “not before” date of the token. The value should be a NumericDate number that indicates the time before which the token is considered invalid. This field is functionally identical to iat.
stitch_meta
Optional. A document containing metadata for the authenticated user. The document will be exposed in the data field of the Stitch user object. Each metadata field in the document must be specified in the authentication provider configuration.

Signature

The signature portion of the JWT is a hash of the encoded token header and payload. To form the signature, concatentate the encoded header and payload with a period and sign the result with the Signing Key specified in the authentication provider configuration using the hashing algorithm specified in the "alg" field of the header.

HMACSHA256(
  base64UrlEncode(header) + "." + base64UrlEncode(payload),
  signingKey
)