The authorization allows:
Mattermost supports two types of OAuth 2.0 clients as defined in RFC 6749:
client_secret that must be kept secureclient_secret_postclient_secret (uses auth method none)noneis_public: true parameter, or via DCR with token_endpoint_auth_method: "none"You must register your application in Mattermost to generate OAuth 2.0 credentials (client ID and secret for confidential clients, or just client ID for public clients), which your application can use to authenticate API calls to Mattermost, and which Mattermost uses to authorize API requests from the application.
If you’d like to set up a Zapier integration with OAuth 2.0, see our Zapier documentation to learn more.
OAuth 2.0 applications are off by default and can be enabled by the System Admin as follows:
Go to Product menu > Integrations.
Select OAuth 2.0 Applications, then choose Add OAuth 2.0 Application.
Set Is Trusted: When set to Yes, your application is considered trusted by Mattermost. This means Mattermost doesn’t require users to accept authorization when signing to third-party applications. When set to No, users will be provided with the following page to accept or deny authorization when authenticating for the first time.
Only System Admins can set OAuth 2.0 applications as trusted.
Set Is Public Client: When set to Yes, your application is registered as a public client (for SPAs, mobile apps, etc.). Public clients do not receive a client secret and must use PKCE for the authorization code flow. When set to No (default), your application is registered as a confidential client with a client secret.
Specify the Display Name: Enter a name for your application made of up to 64 characters. This is the name users will see when granting access to the application, when viewing a list of authorized applications in Settings > Security > OAuth 2.0 Applications and when viewing a list of OAuth 2.0 applications in the Integrations menu.
Add Description: This is a short description of your application that users will see when viewing a list of authorized applications in Settings > Security > OAuth 2.0 Applications.
Specify the Homepage: This is the homepage of the OAuth 2.0 application and lets users visit the app page to learn more what it does. The URL must be a valid URL and start with http:// or https:// depending on your server configuration.
(Optional) Add Icon URL: The image users will see when viewing a list of authorized applications in Settings > Security > OAuth 2.0 Applications and when viewing a list of OAuth 2.0 applications in the Integrations menu. Must be a valid URL and start with http:// or https://.
Add Callback URLs: These are the URL(s) to which Mattermost will redirect users after accepting or denying authorization of your application, and which will be the only URL(s) that handle authorization codes or access tokens. If more than one URL is specified, users will be redirected to the URL used for the initial authorization of the app. Each URL must be on a separate line and start with http:// or https://.
Select Save to create the application.
You’ll be provided with a Client ID, Client Secret, and the authorized redirect URLs. Save these values and use them in your application to connect it to Mattermost.
Once you have created an OAuth 2.0 application, all users on the Mattermost server are automatically given access to it.
The application does not automatically have permissions based on the user who registers the app - the permissions are based on which users go through the OAuth flow, which could be the user who registers the app or anyone else on the system.
If the application was registered as a trusted OAuth 2.0 app on the Mattermost server, authorization from users is not required. Otherwise, the following page will be provided to accept or deny authorization when authenticating the app for the first time.
Once authorized, the application receives an access token to perform requests on behalf of that user. The application can then perform any action for which the user has permission.
Users can view a list of authorized apps from Settings > Security > OAuth 2.0 Applications, and revoke authorization from this setting.
Mattermost supports the authorization code and implicit grant flows for OAuth 2.0 applications.
| Client Type | Authorization Code Flow | Implicit Flow | PKCE Required |
|---|---|---|---|
| Public Client | Supported | Supported | YES (code flow only) |
| Confidential Client | Supported | Supported (Not recommended) | Optional |
Key notes:
code_challenge, it will be enforced throughout the flowPKCE (RFC 7636) is a security extension that protects against authorization code interception attacks. It’s especially important for public clients like single-page applications and mobile apps that cannot securely store client secrets.
PKCE adds two parameters to the OAuth flow:
code_challenge (a hashed value) and code_challenge_method (Mattermost supports S256 only)code_verifier (the original unhashed value)The server verifies that the code_verifier matches the original code_challenge, ensuring the same client that started the authorization is completing it.
Dynamic Client Registration (DCR) allows applications to programmatically register OAuth clients without requiring manual configuration by a System Admin. This follows RFC 7591.
DCR is disabled by default and can be enabled by a System Admin:
When enabled, applications can register themselves as either public or confidential clients by making a request to the registration endpoint (/api/v4/oauth/apps/register). The application specifies its redirect URIs and authentication method:
token_endpoint_auth_method: "none" creates a public client (no client secret)token_endpoint_auth_method: "client_secret_post" creates a confidential client (with client secret)Mattermost provides an OAuth 2.0 Authorization Server Metadata endpoint at /.well-known/oauth-authorization-server that advertises server capabilities, including whether DCR is enabled and what authentication methods are supported.
Confidential clients receive refresh tokens and can use them to obtain new access tokens. Public clients do not receive refresh tokens for security reasons.
/oauth/authorize/oauth/access_token/api/v4/users/meDeleting the application will revoke access from all users. Only the user who created the application or a System Admin can delete the app.