This page is a work in progress and could be pending updates.
server | v5 switch to v4  

Certificate Setup

Contents

Guide

To allow your clients connecting your Photon Server using Secure protocol proceed as follows.

  1. Obtain an SSL certificate:
    a. For development purposes, you can generate a self-signed SSL certificate.

  2. Add certificate and key to the same file "server.pem".

  3. Copy/paste the "server.pem" file under "deploy\bin_Win64\certs". If you want to change the folder path take a look here.

  4. Enable "Secure" attribute on the listener(s) 'to be secured' in "PhotonServer.config". Read more here.

  5. Restart your Photon Server ... voilà!
    If you open the log file: "deploy\bin_WinXX\log\Photon-LoadBalancing-.log", you can find something like this:

        65896: 12:51:13.577 - Config|INFO| HTTP: 0.0.0.0:19093 (*:19093::NameServer) - uses SSL
    65896: 12:51:13.577 - Config|INFO| HTTP: 0.0.0.0:19093 (*:19093::NameServer) - Cipher list: DEFAULT
    65896: 12:51:13.577 - Config|INFO| HTTP: 0.0.0.0:19093 (*:19093::NameServer) - Server Certficate: D:\ExitGames\SDKs\Server\Photon-OnPremises-Server-Classic-SDK_v5-0-12-24441-RC1\deploy\bin_Win64\certs\server.pem
    65896: 12:51:13.578 - Config|INFO| HTTP: 0.0.0.0:19093 (*:19093::NameServer) - Server Domain Name: www.myawesomegame.com

Back To Top

Secure Listeners Configuration

In v5 we use OpenSSL for certificates handling (format, configuration, etc.). In order to make a listener secure (use a certificate) set "Secure" to True. All other certificate related settings require this in order to be effective.

Back To Top

Common Attributes

You can skip all settings if the certificate file(s) path(s) match(es) default expected value(s). "RootCertificates" file can be skipped as it's completely optional and the server can work without it.

For ciphers list string, we recommend TLS >= 1.2 as SSLv3, TLS 1.0 and 1.1 should be deprecated.

  • Secure: True or False to define if this listener uses a secure connection.
  • CipherList: OpenSSL's ciphers list string. See OpenSSL's ciphers documentation page for more information, especially "CIPHER STRINGS" and "EXAMPLES" parts. Default is "DEFAULT". Requires "Secure" to be True.
  • CertificatePath: Absolute path of the directory that contains the certificate file with no trailing slash. You could use macros. Requires "Secure" to be True.
  • RootCertificates: Name of the file containing root certificates if any. Default is "root.pem". Folder is defined by "CertificatePath". Requires "Secure" to be True.
  • MinProtocolVersion: Minimal supported TLS version. For example can be set to "TLS12", default is "TLS".
  • MaxProtocolVersion: Maximum supported TLS version.

Back To Top

Client To Server Listeners

Here are the settings that should be used for the TCPListener, PolicyFileListener or HTTPListener.

  • ValidClientCertificateDomains:
  • CertificateValidationExceptions:
  • RemoteAddressRestrictions:
  • SupportClearTextConnections:
  • DefaultDomain:

Back To Top

Server Certificates Configuration

Example:

<TCPListener>
  <ServerCertificates>
    <ServerCertificate Path=""
     Certificate=""
     Key="">
    </ServerCertificate>
    <!-- add more ServerCertificate here if needed -->
  </ServerCertificates>
</TCPListener>
  • Path: Path to the folder containing the certificate and key files.
  • Certificate: Name of the file containing certificate.
  • Key: Name of the file containing private key.

Back To Top

Server To Server Listeners

Here are the settings that should be used for S2S or WebSocketS2S.

  • Certificate: Name of the file containing certificate.
  • Key: Name of the file containing private key.
  • Password: Password for the key.

Back To Top

Secure Ports Configuration

Example:

<S2S>
  <SecurePorts>
    <SecurePort Port="">
    </SecurePort>
    <!-- add more SecurePort here if needed -->
  </SecurePorts>
</S2S>

Back To Top

Generate Self-Signed Certificate

The following are just very basic and simple steps to generate a self-signed SSL certificate quickly for testing and development purposes. We will not give extensive detail about each method, step or command used. Feel free to look up more information on the internet.

You need OpenSSL installed with the binary properly added to the environment variable path.

  1. Prepare a configuration file, e.g. "req.conf" (replace values with your own):

        [req]
    distinguished_name = photon_wss
    x509_extensions = v3_req
    prompt = no
    [photon_wss]
    C = DE
    ST = HH
    L = Hamburg
    O = ExitGames
    OU = Photon
    CN = www.myawesomegame.com
    [v3_req]
    keyUsage = keyEncipherment, dataEncipherment
    extendedKeyUsage = serverAuth
    subjectAltName = @alt_names
    [alt_names]
    DNS.1 = www.myawesomegame.com
    DNS.2 = photon.myawesomegame.com
    DNS.3 = *.myawesomegame.com
  2. Generate certificate and key by running the following command with administrative privileges:

        openssl req -x509 -nodes -days 730 -newkey rsa:2048 -keyout cert.key -out cert.pem -config req.conf -extensions 'v3_req'
  3. Copy content of "cert.pem" and "cert.key" into one file "server.pem".

Back To Top

Troubleshooting

Make Sure To Use Domain Name And Not IP Address

From the client, the server address to connect to should be a domain name and not an IP address.

Back To Top

Make Sure To Use WSS Prefix

From the client, the server address to connect to should have the prefix or scheme "wss://" which indicates that you are using WebSockets Secure protocol.

Back To Top

Make Sure To Use The Correct Port Number

Double-check the port number used to connect to the server. It needs to match the port of the WebSocket Listener of the "Master" application as configured in "PhotonServer.config". In the example above (step 3 of the "Guide") it's 9090. On Photon Cloud we use 19090.

Back To Top

Make Sure Server Is Reachable By Client

Try reaching the server using "ping" command. For development purposes, if the domain name is not DNS ready yet you can add the IP address to your local "hosts" file. On Windows, it's located under "C:\Windows\system32\drivers\etc\hosts". Add a line with format: <IP Address> <domain name>.

Example:
If the server is on the same machine as the client and your domain is "photon.example.com"

127.0.0.1           photon.example.com

Also, don't forget to open the required ports from the server. Read more about "Firewall Settings".

Back To Top

Try Connecting To Photon Server Using UDP Or TCP

Try switching the transport protocol to make sure the client can connect to the server.

Back To Top

Try Connecting To Photon Cloud Using WSS

To make sure there is nothing wrong with the client, connect to Photon Cloud and see if it works.

Back To Top

Chrome Console Error: ERR_CERT_INVALID_AUTHORITY

If you encounter this error in Chrome, you can use the following workaround:

If your server address is "wss://photon.example.com:9090":

  1. Open a new tab.
  2. Enter "https://photon.example.com:9090" (Replace "wss://" with "https://" in the server address) in the address bar and click enter.
  3. Chrome will complain about the site not being secure.
  4. Click "Advanced".
  5. Click "Proceed to https://photon.example.com:9090 (unsafe)". This will make Chrome accept your self-signed certificate using wss.
  6. Restart Chrome.
  7. Test your client again.

Back To Top

Chrome Console Error: ERR_CERT_COMMON_NAME_INVALID

You can try the previous workaround used for ERR_CERT_INVALID_AUTHORITY error. Or you need to make sure your certificate uses Subject Alternative Names (SANs). See "Using OpenSSL" for how to generate a self-signed SSL certificate that uses SANs.

Back To Top

Try Guide From Clean SDK

If you encounter issues when configuring WSS for your self-hosted Photon Server, we recommend that you start by downloading a clean SDK version and following the steps provided here on it. If you don't encounter the same issue then you need to find out what is wrong with your own custom setup.

Back To Top

Try Starting Photon As An Application

Sometimes when Photon Server is configured to be started as a service some issues may be encountered. We recommend that you follow the steps provided here with a Photon Server started as an application.

Back To Top

Read The Server Logs

Always! Check the logs. The server's logs' files' locations can be found here.

To Document Top