Mirror
  • Mirror Networking
  • API Reference
  • Development Blog
    • A Brief History of Mirror
  • User Manual
    • General
      • Getting Started
      • Script Templates
      • Change Log
        • 2024 Change Log
        • 2023 Change Log
        • 2022 Change Log
        • 2021 Change Log
        • 2020 Change Log
        • 2019 Change Log
      • Deprecations
      • Migration Guide
      • Integrations
      • Timestamp Batching
      • TCP and UDP
      • CCU
      • SyncDirection
      • Round Trip Time (RTT)
      • Connection Quality
      • Lag Compensation
      • Client Side Prediction
      • History Bounds
      • Tests
      • NetGraph
    • FAQ
      • Execution Order
    • Transports
      • KCP Transport
      • Telepathy Transport
      • WebSockets Transport
        • Reverse Proxy
          • Windows
            • IIS
          • Linux
            • NGINX
            • Caddy
            • Apache
            • HA Proxy
        • SSL
      • Multiplex Transport
      • Latency Simulation Transport
      • Ignorance
      • LiteNetLib Transport
      • FizzySteamworks Transport
      • FizzyFacepunch Transport
      • Encryption Transport
      • Edgegap Transports
        • Edgegap Relay
        • Edgegap Lobby
    • Components
      • Network Animator
      • Network Authenticators
        • Basic Authenticator
        • Device Authenticator
      • Network Behaviour
      • Network Discovery
      • Network Identity
      • Network Manager
      • Network Manager HUD
      • Network Ping Display
      • Network Profiler
      • Network Rigidbody
      • Network Lerp Rigidbody
      • Network Room Manager
      • Network Room Player
      • Network Start Position
      • Network Statistics
      • Remote Statistics
      • Network Transform
        • Snapshot Interpolation
      • Deprecated
        • Network Proximity Checker
        • Network Scene Checker
        • Network Match Checker
        • Network Owner Checker
    • Interest Management
      • Spatial Hashing
      • Distance
      • Scene
      • Scene + Distance
      • Match
      • Team
      • Custom
      • Legacy
    • Guides
      • Authority
      • IDs
      • Attributes
      • Time Synchronization
      • Data types
      • Serialization
      • Synchronization
        • SyncVars
        • SyncVar Hooks
        • SyncEvent (Obsolete)
        • SyncLists
        • SyncDictionary
        • SyncHashSet
        • SyncSortedSet
      • Communications
        • Remote Actions
        • NetworkManager Callbacks
        • NetworkBehaviour Callbacks
        • Network Messages
      • GameObjects
        • Player Game Objects
        • Custom Character Spawning
        • Custom Spawn Functions
        • Scene GameObjects
        • Pickups, Drops, and Child Objects
    • Examples
      • Additive Levels
      • Additive Scenes
      • Basic
      • Billiards
      • Multiple Additive Scenes
      • Pong
      • Room
      • Tanks
      • EdgegapLobby
  • Server Hosting
    • The Pragmatic Hosting Guide
    • Cloud Hosting Guides
      • AWS
      • Google Cloud
      • Oracle Free Tier
    • Hosting with a Remote Desktop
    • Edgegap Hosting Plugin Guide
  • Security
    • Security Overview
    • Cheat Protection Stages
    • Cheats & Anticheats
  • Community Guides
    • Community Translations
    • Video Tutorials
    • Resources
    • Mirror Quick Start Project
    • Unity for MMORPGs
    • Unity Canvas HUD
    • Odin Inspector Support
    • Ready Up And Die!
    • iOS AppStore
    • Mirror Docker Guide
    • Gitbook Guide
    • Mirror Branding
    • Contributors Agreement
    • Documentation License
Powered by GitBook
On this page
  • Encryption Notice
  • Offline / Online Scenes
  • Persisting Data
  • Built-in Authenticators
  • Custom Authenticators
  • Message Registration
  • Tips
  1. User Manual
  2. Components

Network Authenticators

PreviousNetwork AnimatorNextBasic Authenticator

Last updated 3 years ago

When you have a multiplayer game, often you need to store information about your player for later games, keep game stats or communicate with your friends. For all these use cases, you often need a way to uniquely identify a user. Being able to tell users apart is called authentication. There are several methods available, some examples include:

  • Ask the user for username and password

  • Use a third party OAuth2 or OpenID identity provider, such as Facebook, Twitter, Google

  • Use a third party service such as PlayFab, GameLift or Steam

  • Use the device id, very popular method in mobile

  • Use Google Play in Android

  • Use Game Center in IOS

  • Use a web service in your website

Encryption Notice

Few of the available transports support encryption, so if you want to do authentication through Mirror, we highly recommend you use a transport that does, e.g. Transport, or carry out your exchange of sensitive data using UnityWebRequest with a service over HTTPS. This can be done inside an Authenticator, or before calling StartClient.

Offline / Online Scenes

Authentication takes place in the Offline scene, and messages are exchanged with the game server in a pre-connect phase, so client stays in the Offline scene until authentication completes.

Persisting Data

NetworkConnection has an authenticationData property of type Object that can be set to pretty much anything you need, such as account id's, tokens, character selection, etc., including a struct of data, on the server and/or client during the authentication process. That data is available everywhere else in Mirror where you have the client's NetworkConnection...just cast it back to whatever type you put into it.

Built-in Authenticators

  • Uses SystemInfo.deviceUniqueIdentifier on supported platforms, and GUID in PlayerPrefs as a fallback for platforms that don't.

Custom Authenticators

Authenticators are derived from an Authenticator abstract class that allows you to implement any authentication scheme you need.

Message Registration

By default all messages registered to NetworkServer and NetworkClient require authentication unless explicitly indicated otherwise. To register messages to bypass authentication, you need to specify false for a bool parameter to the RegisterMessage method:

NetworkServer.RegisterHandler(OnAuthRequestMessage, false);

Certain internal messages already have been set to bypass authentication:

  • Server

    • NetworkPingMessage

  • Client

    • SceneMessage

    • NetworkPongMessage

Tips

  • Register handlers for messages in OnStartServer and OnStartClient. They're called from StartServer/StartHost, and StartClient, respectively.

  • Send a message to the client if authentication fails, especially if there's some issue they can resolve.

  • Call the Disconnect() method of the NetworkConnection on the server and client when authentication fails. If you want to give the user a few tries to get their credentials right, you certainly can, but Mirror will not do the disconnect for you.

    • Remember to put a small delay on the Disconnect call on the server if you send a failure message so that it has a chance to be delivered before the connection is dropped. At a minimum, yield one frame.

Now that you have the foundation of a custom Authenticator component, the rest is up to you. You can exchange any number of custom messages between the server and client as necessary to complete your authentication process before approving the client.

Authentication can also be extended to character selection and customization, just by crafting additional messages and exchanging them with the client before completing the authentication process. This means this process takes place before the client player actually enters the game or changes to the Online scene.

If you write a good authenticator, consider sharing it with other users or donating it to the Mirror project.

Mirror includes a Basic Authenticator in the Mirror / Authenticators folder which just uses a simple username and password.

From the Assets menu, click Create > Mirror > Network Authenticator to make your own custom Authenticator from our , and just fill in the messages and validation code to suit your needs. When a client is successfully authenticated, call ServerAccept(conn) on the server and ClientAccept() on the client. Mirror is listening for these events to proceed with the connection sequence. Subscribe to OnServerAuthenticated and OnClientAuthenticated events if you wish to perform additional steps after authentication.

SimpleWebSocket
Basic Authenticator
Device Authenticator
Script Templates