mirror of
https://github.com/wassname/talk.git
synced 2026-06-30 02:56:56 +08:00
immber
113 lines
4.9 KiB
Markdown
113 lines
4.9 KiB
Markdown
---
|
|
title: Authenticating with Talk
|
|
permalink: /integrating/authentication/
|
|
---
|
|
|
|
Out of the box Talk supports account registration with username and password, as well as features like forgot password.
|
|
|
|
You can also integrate Talk with any external authentication service that will enable
|
|
seamless single sign-on (SSO) for users within your organization. There are a few
|
|
methods of doing so:
|
|
|
|
1. Passport Middleware
|
|
2. Custom Token Integration
|
|
|
|
Both methods work, but there are product decisions that will affect the overall
|
|
choice.
|
|
|
|
## Passport Middleware
|
|
|
|
You would choose the **Passport Middleware** route when you are OK using an auth
|
|
that is triggered from inside Talk that is not connected to an external auth
|
|
state (you don't use the auth anywhere else now).
|
|
|
|
Plugins are available for the following 3rd party authentication providers:
|
|
|
|
* [Facebook](/talk/plugin/talk-plugin-facebook-auth/)
|
|
* [Google](/talk/plugin/talk-plugin-google-auth/)
|
|
|
|
_FAQ: Can I create a Twitter auth plugin?_
|
|
This is currently not possible because Talk uses passport.js which does not support Twitter's oAuth2 requirements.
|
|
|
|
## Custom Token Integration
|
|
|
|
You can integrate Talk with any authentication service to enable single sign-on
|
|
for users. The steps to do that are:
|
|
|
|
1. Create a service that generates [JWT tokens](https://jwt.io/introduction/).
|
|
2. Push the token into the embed.
|
|
3. Implement the [`tokenUserNotFound`](#implement-tokenusernotfound) hook to
|
|
process the token.
|
|
|
|
### Create JWT Token
|
|
|
|
You should create an external service that is responsible for generating a JWT
|
|
for use with Talk. The token can be generated as easy as checking out the
|
|
following node app: https://github.com/coralproject/talk-token-example
|
|
|
|
Using that demo application, you'll see how you can:
|
|
|
|
1. Create a node application that can issue JWT's that are compatible with Talk.
|
|
2. Provide a validation endpoint that can be used by Talk to validate the token
|
|
and get the user via the [`tokenUserNotFound`](#implement-tokenusernotfound)
|
|
hook.
|
|
|
|
It's also important to note a few requirements for proper integration with Talk.
|
|
The generated JWT must contain the following claims:
|
|
|
|
- [`jti`](https://tools.ietf.org/html/rfc7519#section-4.1.7): a unique identifier for the token (like a uuid/v4)
|
|
- [`exp`](https://tools.ietf.org/html/rfc7519#section-4.1.4): the expiry date of the token as a unix timestamp
|
|
- [`sub`](https://tools.ietf.org/html/rfc7519#section-4.1.2): the user identifier that can be used to lookup the user in the mongo
|
|
database
|
|
- The user may not yet exist in the database, but that's the responsibility
|
|
of the [`tokenUserNotFound`](#implement-tokenusernotfound) hook.
|
|
- [`iss`](https://tools.ietf.org/html/rfc7519#section-4.1.1): the issuer for the token must match the value of `TALK_JWT_ISSUER`
|
|
- [`aud`](https://tools.ietf.org/html/rfc7519#section-4.1.3): the audience for the token must match the value of `TALK_JWT_AUDIENCE`
|
|
|
|
### Generate a key to sign the JWT
|
|
Optionally you can use https://github.com/coralproject/coralcert to generate a key with which to sign the JWTs and specify the secret as an environment variable.
|
|
|
|
### Push token into embed
|
|
|
|
We're assuming that your CMS is capable of authenticating a user account, or
|
|
at least having the user's details available to send off to the token creation
|
|
service we created/used in the previous step.
|
|
|
|
Using the token that was created for the user, you simply have to amend the
|
|
template where Talk is rendering to read as the following:
|
|
|
|
```js
|
|
Coral.Talk.render(document.getElementById('coralStreamEmbed'), {
|
|
// ...
|
|
auth_token: '<your generated JWT token issued for this user>',
|
|
});
|
|
```
|
|
|
|
Which will pass down the token to Talk and will fire the next steps
|
|
`tokenUserNotFound` hook to complete the auth flow.
|
|
|
|
### Implement `tokenUserNotFound`
|
|
|
|
This is the only piece of code you'll have to write that lives inside Talk.
|
|
The role of this code is to live as a plugin and provide Talk with a way of
|
|
taking the token that you gave it, and turning into a user.
|
|
|
|
Using the example application we were working with in the JWT issuing step
|
|
above, we'll need to ensure that the configuration is consistent in-between both
|
|
Talk and the JWT issuer. Namely, the following environment variables from our
|
|
example issuer and Talk must match:
|
|
|
|
| Talk | Token Issuer Example |
|
|
|------|----------------------|
|
|
|[`TALK_JWT_ISSUER`](/talk/advanced-configuration/#talk-jwt-issuer)|`JWT_ISSUER`|
|
|
|[`TALK_JWT_AUDIENCE`](/talk/advanced-configuration/#talk-jwt-audience)|`JWT_AUDIENCE`|
|
|
|[`TALK_JWT_SECRET`](/talk/advanced-configuration/#talk-jwt-secret)|`JWT_SECRET`*|
|
|
|
|
\* Note that secrets is a pretty complex topic, refer to the
|
|
[TALK_JWT_SECRET](/talk/advanced-configuration/#talk-jwt-secret) configuration
|
|
reference, the basic takeaway is that the secret used to sign the tokens issued
|
|
by the issuer must be able to be verified by Talk.
|
|
|
|
For an example of implementing the plugin, refer to [`tokenUserNotFound`](/talk/api/server/#tokenusernotfound)
|
|
reference.
|