Photon JWT Authentication
Overview
JWT (JSON Web Tokens) authentication is different from the existing custom authentication. To use JWT authentication the client has to pass a special token. Photon server just validates the token instead of calling an external web service. The token uses JWT and is encrypted for security reasons.
Dashboard Setup
Adding JWT as an authentication provider is easy and it could be done in few seconds from your Photon Applications' Dashboard. Go to the "Manage" page of an application and scroll down to the "Authentication" section. If you add a new authentication provider for JWT or edit an existing one, here the mandatory settings:
- secret1, REQUIRED value
<KeyHash>;<KeyEncryption>;<KeySignature>
. Always configure "secret1". - secret2, OPTIONAL value
<KeyHash2>;<KeyEncryption2>;<KeySignature2>
. "secret2" can be used if the keys have to be changed. Because it takes some time until changes in the dashboard reach all servers you can enter the old values in "secret2" and the new values in "secret1". Just adjust the values in the dashboard ahead of times.
Example Secret
secret1: 00000000-0000-0000-0000-000000000001;00000000-0000-0000-0000-000000000002;00000000-0000-0000-0000-000000000003
where:
- Key Hash:
00000000-0000-0000-0000-000000000001
- Key Encryption:
00000000-0000-0000-0000-000000000002
- Key Signature:
00000000-0000-0000-0000-000000000003
Note: We used GUIDs for the sake of simplicity you can choose different strings.
Token Generation
There are multiple libraries for token creation available (e.g. System.IdentityModel.Tokens.Jwt
for C#).
For encryption you can take a look at the source of the supplied test console application for a sample implementation in C#.
Token format: <base64UrlEncode(header)>.<base64UrlEncode(payload)>.<Signature>
Header
JSON
{
"alg": "HS256",
"typ": "JWT"
}
Payload
JSON
{
// jwt
"exp" : [timestamp], // expires at
"iat" : [timestamp], // issued at (optional)
"nbf" : [timestamp], // not before (optional)
// Photon
"UserId" : [string:value, optional],
"Nickname" : [string:value, optional],
"AuthCookie" : [Dictionary<string, object>, optional]
}
Signature
Unknown
MACSHA256(
base64UrlEncode(header) + "." +
base64UrlEncode(payload),
[secret]
)
Example
JSON:
JSON
{
"alg":"HS256",
"typ":"JWT"
}
.
{
"UserId":"Jason2000",
"Nickname":"Jason",
"nbf":1519314827,
"exp":1519318427,
"iat":1519314827
}
Signed + Encoded (with secret "00000000-0000-0000-0000-000000000003"):
text
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJVc2VySWQiOiJKYXNvbjIwMDAiLCJOaWNrbmFtZSI6Ikphc29uIiwibmJmIjoxNTE5MzE0ODI3LCJleHAiOjE1MTkzMTg0MjcsImlhdCI6MTUxOTMxNDgyN30.B2gs4_qEBbwXsjOvW8ZbORiBxLrcmsE96P77Kzyaf2c
You can test the token in the JWT debugger, just paste the signed and encoded token into the "Encoded" field.
To verify the signature paste the secret 00000000-0000-0000-0000-000000000003
into the "secret" field.
Encryption
Some details about the encryption used:
- Format:
[IV][encrypted data][HMAC]
- Encryption algorithm: AES
- IV size: 16
- Padding: PKCS7 (default for
System.Security.Cryptography
) - Block size: 16
- HMAC size: 32
- Hash algorithm: SHA256
- Hash and Encryption keys: dashboard string values converted to byte arrays (UTF-8 encoding) and hashed SHA256
Client Code
Client needs to send the generated JWT token string, encrypted, URL encoded and in a Base64 format:
C#
AuthenticationValues authValues = new AuthenticationValues();
authValues.AuthType = CustomAuthenticationType.Jwt; // 9
authValues.SetAuthPostData(jwtTokenString);
authValues.UserId = userId; // UserId is always required in Photon Chat
// do not set authValues.Token or authentication will fail
chatClient.Connect(chatAppId, chatAppVersion, authValues);
Back to top