charleslemaux/Mirror
1
0
Fork 0
mirror of https://github.com/MirrorNetworking/Mirror.git synced 2024-11-18 02:50:32 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

doc: Merged Authentication documents

Browse Source
This commit is contained in:
Chris Langsenkamp 2020-05-07 01:52:35 -04:00
parent 08390cb801
commit 811c9d3e02
5 changed files with 49 additions and 66 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

48
doc/Components/Authenticators/index.md
View File

@ -9,9 +9,53 @@ When you have a multiplayer game, often you need to store information about your
- Use Game Center in IOS
- Use a web service in your website
In addition to the Authenticators listed below, you can make your own! Check out this [Guide](../../Guides/Authentication.md) for details.
## Encryption Notice
## Authenticators
By default Mirror uses Telepathy, which is not encrypted, so if you want to do authentication through Mirror, we highly recommend you use a transport that supports encryption.
## Basic Authenticator
- [Basic Authenticator](Basic.md)
Mirror includes a Basic Authenticator in the Mirror / Authenticators folder which just uses a simple username and password.
## Custom Authenticators
Authenticators are derived from an `Authenticator` abstract class that allows you to implement any authentication scheme you need.
From the Assets menu, click Create > Mirror > Network Authenticator to make your own custom Authenticator from our [Script Templates](../General/ScriptTemplates.md), and just fill in the messages and validation code to suit your needs. When a client is successfully authenticated, call `base.OnServerAuthenticated.Invoke(conn)` on the server and `base.OnClientAuthenticated.Invoke(conn)` 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.
## 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<AuthenticationRequest>(OnAuthRequestMessage, false);
```
Certain internal messages already have been set to bypass authentication:
- Server
- `ConnectMessage`
- `DisconnectMessage`
- `ErrorMessage`
- `NetworkPingMessage`
- Client
- `ConnectMessage`
- `DisconnectMessage`
- `ErrorMessage`
- `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.
- `NetworkConnection` has an `authenticationData` object where you can drop any data you need to persist on the server related to the authentication, such as account id's, tokens, character selection, etc.
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.

4
doc/General/ChangeLog.md
View File

@ -146,7 +146,7 @@ Mirror uses semantic versioning, and the versions shown here are those that were
- Removed: Network Identity: Local Player Authority has been removed as no longer necessary.
## Version 4.0.7 - 2019-Oct-03
- Added: [Authentication](../Guides/Authentication.md) support to authenticate clients in the Connect phase.
- Added: [Authenticators](Components/Authenticators/index.md) support to authenticate clients in the Connect phase.
- Added: Profiler events. These events can be subscribed to by the [Network Profiler](../Guides/Profiler.md) to provide visual information.
- Added: Transports now include channel in profiler events.
- Added: Transport abstract class now supports sending a message to a list of connection id's.
@ -290,7 +290,7 @@ Mirror uses semantic versioning, and the versions shown here are those that were
- Changed: Documentation for [Transports](../Transports/index.md).
- Changed: Weaver is now full source...FINALLY!
- Changed: ClientScene.AddPlayer 2nd parameter is now `byte[] extraData` instead of `MessageBase extraMessage`.
- Please refer to the code sample [here](../Guides/Authentication.md) to see how to update your code.
- Please refer to the code sample [here](../Guides/GameObjects/SpawnPlayerCustom.md) to see how to update your code.
- Changed: NetworkManager -- Headless Auto-Start moved to `Start()` from `Awake()`.
- Changed: Removed Message ID's for all messages - See [Network Messages](../Guides/Communications/NetworkMessages.md) for details.
- Message IDs are now generated automatically based on the message name.

59
doc/Guides/Authentication.md
View File

@ -1,59 +0,0 @@
# Authentication
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 oath 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 Warning
By default Mirror uses Telepathy, which is not encrypted, so if you want to do authentication through Mirror, we highly recommend you use a transport that supports encryption.
## 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 new bool parameter to the `RegisterMessage` method:
```
NetworkServer.RegisterHandler<ConnectMessage>(OnServerConnectInternal, false);
```
Certain internal messages already have been set to bypass authentication:
- Server
- `ConnectMessage`
- `DisconnectMessage`
- `ErrorMessage`
- `NetworkPingMessage`
- Client
- `ConnectMessage`
- `DisconnectMessage`
- `ErrorMessage`
- `SceneMessage`
- `NetworkPongMessage`
## Basic Authenticator
Mirror includes a [Basic Authenticator](../Components/Authenticators/Basic.md) in the Mirror / Authenticators folder which just uses a simple username and password.
## Custom Authenticators
Authenticators are derived from an `Authenticator` abstract class that allows you to implement any authentication scheme you need.
From the Assets menu, click Create > Mirror > Network Authenticator to make your own custom Authenticator from our [Script Templates](../General/ScriptTemplates.md), and just fill in the messages and validation code to suit your needs. When a client is successfully authenticated, call `base.OnServerAuthenticated.Invoke(conn)` on the server and `base.OnClientAuthenticated.Invoke(conn)` 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.
### 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.
- `NetworkConnection` has an `authenticationData` object where you can drop any data you need to persist on the server related to the authentication, such as account id's, tokens, character selection, etc.
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.
If you write a good authenticator, consider sharing it with other users or donating it to the mirror project.

2
doc/Guides/toc.yml
View File

@ -4,8 +4,6 @@
href: Authority.md
- name: About IDs
href: IDs.md
- name: Authentication
href: Authentication.md
- name: Network Discovery
href: NetworkDiscovery.md
- name: Network Profiler

2
doc/index.md
View File

@ -28,7 +28,7 @@ We've developed a [List Server](https://mirror-networking.com/list-server/) wher
- [Transports](Transports/index.md) are interchangeable components
- Additive Scene Loading
- Single and separated Unity projects supported
- Network [Authenticators](Guides/Authentication.md) to protect your game
- Network [Authenticators](Components/Authenticators/index.md) to protect your game
- Network [Discovery](Guides/NetworkDiscovery.md) to easily connect LAN players to a LAN Server or Host
- Network [Manager](Components/NetworkManager.md) and [HUD](Components/NetworkManagerHUD.md)
- Network [Room Manager](Components/NetworkRoomManager.md) and [Room Player](Components/NetworkRoomPlayer.md)