- Stitch >
- Users & Authentication >
- Authentication Providers
Custom Function Authentication¶
On this page
Overview¶
The Custom Function authentication provider allows you to use a Stitch function to implement your own user authentication logic or flexibly integrate an external authentication system. You can use the Custom Function provider to integrate with any authentication system as long as the system maintains a unique ID value for each user.
The authentication function is a Stitch function that you define to handle authentication logic for users that log in with the Custom Function provider. You can use the function to coordinate with an external authentication system and/or use data that you store in MongoDB to identify and authenticate users.
Validate and Authenticate Custom Function Users
Stitch does not perform any data validation or authentication checks for the Custom Function provider. Make sure that you validate incoming data and that your authentication system performs appropriate authentication checks, such as requiring a password, two factor authentication, or a single sign-on token.
Configure Custom Function Authentication¶
- Stitch UI
- Import/Export
Enable the Provider¶
To create new users and allow them to log in, you must enable the Custom Function provider. To do so, set the Provider Enabled toggle to On.
Define the Authentication Function¶
The authentication function must return a string ID value that uniquely identifies the user. Stitch uses this value to lookup an existing Stitch user and automatically creates a new user if it does not match an existing user. If the function does not return a string, Stitch throws an error and does not create or authenticate a user.
Stitch Generates New User ID Values
The ID value that you return from the authentication function is
not the internal Stitch user id (i.e. the value that
%%user
and context.user
resolve to). Stitch automatically generates a unique id for Custom
Function users when it creates them.
To define a new authentication function, click the Function dropdown and select New Function.
Example
An application implements a Custom Function authentication provider
that stores user data in the app.users
MongoDB collection. The
app lets users log in by specifying their username
but does not
require a password or any other type of authentication.
The appication’s authentication function queries the users
collection for an existing user with the specified username. If the
user already exists, the function returns their stored id
value. If
the user does not exist, the function stores a new user document in
the collection and returns that document’s id
value.
Deploy the Updated Application¶
Once you have written and saved the authentication function, you can make Custom Function authentication available to client applications by deploying your application. To deploy a draft application from the Stitch UI:
- Click Deploy in the left-hand navigation
- Find the draft in the deployment history table and then click Review & Deploy Changes.
- Review the diff of changes and then click Deploy.
Once the application successfully deploys, you will be able to create and log in as a Custom Function user from a client application.
Export Your Stitch Application¶
You can set up and enable the Custom Function authentication provider through Stitch CLI or automatic GitHub deployment. To configure the provider, you need the latest version of the application directory for your application.
You can export your application from the Export tab of the Settings page in the Stitch UI, or by running the following command from an authenticated instance of stitch-cli:
Define the Authentication Function¶
The authentication function must return a string ID value that uniquely identifies the user. Stitch uses this value to lookup an existing Stitch user and automatically creates a new user if it does not match an existing user. If the function does not return a string, Stitch throws an error and does not create or authenticate a user.
Stitch Generates New User ID Values
The ID value that you return from the authentication function is
not the internal Stitch user id (i.e. the value that
%%user
and context.user
resolve to). Stitch automatically generates a unique id for Custom
Function users when it creates them.
To create the authentication function, write the function code and then follow the steps in Define a Function to add it to your application.
Example
An application implements a Custom Function authentication provider
that stores user data in the app.users
MongoDB collection. The
app lets users log in by specifying their username
but does not
require a password or any other type of authentication.
The application’s authentication function queries the users
collection for an existing user with the specified username. If the
user already exists, the function returns their stored id
value. If
the user does not exist, the function stores a new user document in
the collection and returns that document’s id
value.
Add a Provider Configuration File¶
To configure the Custom Function authentication provider, create a new
authentication provider configuration file named
custom-function.json
in the auth_providers
directory and set
the value of config.authFunctionName
the name of the
authentication function:
Deploy the Updated Application¶
Once you have created the authentication function and configured the provider, you can make Custom Function authentication available to client applications by deploying your application.
To deploy a draft application with Stitch CLI:
To deploy a draft application with automatic GitHub deployment:
Once the application successfully deploys, you will be able to create a user and log in with the Custom Function provider from a client application.
Use Custom Function Authentication¶
Authenticate a User¶
- JavaScript SDK
- Android SDK
- iOS SDK
To log a user in to your app with the Custom Function authentication provider, call StitchAuth.loginWithCredential() with an instantiated FunctionCredential that contains any data required for authentication.
To log a user in to your app with the Custom Function authentication provider, call StitchAuth.loginWithCredential() with an instantiated FunctionCredential that contains any data required for authentication.
To log a user in to your app with the Custom Function authentication provider, call StitchAuth.login(withCredential:_:) with an instantiated FunctionCredential that contains any data required for authentication.