Help Wanted: Clarify how to use mmctl with non-email authentication systems

[matterdoc]

Context

The Mattermost Product Documentation is missing details on how to use mmctl with non-email authentication systems, such as Okta.

Documentation request

Document how to use mmctl to authenticate with non-email authentication systems by generating and using a personal access token or by granting the ability to generate tokens by individual user, as detailed below.

Generate a Personal Access Token

1. Go to your Mattermost instance.
2. Navigate to your profile and select Profile.
3. Under the Security tab, find Personal Access Tokens.
4. Generate a new token by selecting Create Token, providing a token description, and then copying it/storing it in a secure place since you'll only see it once.

Log in Using mmctl with Token

In a terminal, use the following command to login to mmctl using the generated token:

mmctl auth login <your-mattermost-server-url> --name <login-name> --token <your-access-token>



Replace <your-mattermost-server-url> with your Mattermost server URL, <login-name> with a name to refer to this login, and <your-access-token> with the token generated above.

Example
Assuming your Mattermost server URL is https://mattermost.example.com, your desired login name is my-profile, and your token is abcd1234, the command would be:

mmctl auth login https://mattermost.example.com --name my-profile --token abcd1234

Additional Notes

• Token security: Make sure your token is kept secure and do not share it.
• Logging out: To logout or remove the authentication, you can use:

 mmctl auth remove <login-name>

, and replace <login-name> with the name you provided, for example:

 mmctl auth remove my-profile

• Ensure you have the necessary permissions to generate and use personal access tokens on your Mattermost instance.

Grant the ability to create user-tokens individually

Alternatively, admins can permit only admins to generate and use personal access tokens while restricting regular users.

1. Access System Console as an admin.

2. Disable Personal Access Token Permissions for all users by going to Integrations > Integration Management > Enable Personal Access Tokens. Set to false.

3. Allow admin to generate tokens

• Select an admin user.
• Select Manage Roles from the Actions drop-down menu.
• Enable the Allow this account to generate personal access tokens, and select Save.

4. Verify Configuration

• For Admin Users:
  • Log in as an admin and go to Profile > Security > Personal Access Tokens.
  • Ensure the option to generate tokens is available.
• For Regular Users:
  • Log in as a regular user, and confirm that the Personal Access Tokens section under Security is absent.

This approach ensures that only users with admin privileges can generate and manage personal access tokens, providing an additional layer of security and control over token usage within your organization.

[Rutam21]

@cwarnermm I’d be happy to work on this! Could you let me know if we’re adding this content to a new page or integrating it into an existing one? Also, is the content provided all that’s needed, or should we include additional details for a more complete overview? Thanks!

[cwarnermm]

Thanks, @Rutam21! The mmctl page is where this content is needed, and I suggest adding it directly before the subsection on running mmctl tests.

What's included here is a good start. Once the docs PR is available, I'll add Engineering SMEs as reviewers to confirm the content and suggest any updates. Thanks!