- Stitch >
- Users & Authentication >
- Authentication Providers
Custom Authentication¶
On this page
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.
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:
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: 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 map between fields in the external system’s
JSON Web Token and the values in a
customer user object’s ![]() To require a metadata field from an import/export
configuration file, add an entry for the field to the
|
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.
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().
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.
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¶
The header portion of the JWT consists of a Base64UrlEncoded
document of the following form:
Field | Description | ||||||
---|---|---|---|---|---|---|---|
|
Required. A string representing the hashing algorithm being used. Stitch supports JWTs encoded with the following algorithms:
|
||||||
|
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:
Field | Description |
---|---|
|
Required. The audience of the token. The value should be the App ID of your Stitch application. |
|
Required. The subject of the token. The value should be a unique ID for the authenticated user from your custom-built authentication system. |
|
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. |
|
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 . |
|
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 . |
Note
Stitch ignores any additional fields in the JWT payload unless you
have mapped them to metadata fields in the provider
configuration. Stitch includes the
values of mapped fields in the data
document of the authenticated
user’s user object.
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.