Custom Authentication¶

On this page

Overview
Configuration
Usage
- Authenticate a User
- JSON Web Tokens

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¶

Stitch UI
Import/Export

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:

copy

/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:

copy

"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:

copy

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

Usage¶

Authenticate a User¶

JavaScript SDK
Android SDK
iOS SDK

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.

copy

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().

copy

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.

copy

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:

copy

<header>.<payload>.<signature>

Header¶

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

copy

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

Field	Description
`alg`¶	Required. A string representing the hashing algorithm being used, e.g. `"HS256"` for HMAC SHA-256.
`typ`¶	Required. The type of the token. Stitch expects a JSON web token so the value should be `"JWT"`.

Payload¶

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

copy

{
  "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.

copy

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

← Google Authentication Linking User Accounts →