Security FAQ
32 questions on this page
Short answers to common questions about security.
What is Access Manager?
Access Manager is an optional, but recommended, add-on that controls which clients can read from or write to your channels and user metadata. Without it, any client that has your publish and subscribe keys can reach every channel on the keyset.
Access Manager uses tokens. An Access Manager token is a signed, time-limited access credential that your server generates with the secret key and passes to a client. The token lists the resources the client can use and the permissions on each, and PubNub checks it on every request. For how the pieces fit together, see Access Manager.
How do I turn on Access Manager?
Turn it on for each keyset in the Admin Portal. You need a role that can change the keyset, such as Account Admin or Key Admin.
- Select your app, then select the keyset.
- Scroll to the ACCESS MANAGER section and toggle Access Manager on.
- Select Save changes.
Once it's on, every request on that keyset needs a valid token. If clients already use the keyset in production, update your server and clients to grant and set tokens before you turn it on, or their requests are rejected. See Configure access control.
How do I grant permissions with Access Manager?
Call grantToken from your server, using a PubNub instance initialized with the secret key. In the call you set the authorized User ID, the permissions on each channel, channel group, or user ID, and the token's time to live (TTL). A pattern (an RE2 regular expression) can cover many channels in one grant. PubNub returns a token, and your server passes it to the client, which sets it with setToken.
To change permissions, grant a new token and send it to the client. See Grant, change, and revoke permissions for code in each SDK and Initialize a server SDK with a secret key for the server setup.
How long do granted permissions last?
Until the token's TTL (Time To Live) ends. Every Access Manager token requires a ttl in minutes, and there is no default. An Access Manager token's ttl ranges from 1 minute to 43,200 minutes (30 days). A request that uses an expired token fails with 403 Token is expired. The client then needs a new token from your server. See Update an expired token.
To end access sooner, revoke the token. Revocation is off by default and has its own limits. See Why doesn't revoking a token work immediately? and Token revocation.
How do I authenticate subscribers?
You authenticate them in your own app, and PubNub (via Access Manager) authorizes them by token. PubNub doesn't log users in or verify passwords, so your own application authenticates the user and then hands PubNub the resulting identity.
After your login succeeds, your server grants a token bound to that user's User ID, and the client sets it in the software development kit (SDK). PubNub then rejects requests that present the token with a different User ID. Treat the token as a secret, because the User ID alone doesn't prove who is calling. See Keyset credentials and authorization and Access Manager.
Why do I get "Invalid Timestamp" when I grant permissions?
Your server's clock is off. The SDK adds a timestamp to every Access Manager grant request, and PubNub rejects the request if the timestamp is more than 60 seconds from PubNub's time. The check protects against replay attacks.
To fix it, turn on NTP (Network Time Protocol) on your server to keep its clock in sync. On Linux or Unix, ntpdate -q pool.ntp.org shows how far your clock has drifted. If NTP is already installed, check its configuration and the time zone settings.
Why do I get "Token signature does not match"?
The token comes from a different keyset. Use each token only with the keyset that granted it.
Does Access Manager apply when I subscribe to several channels?
Yes. Access Manager requires the client's token to grant read permission on every channel in the subscribe request. If it lacks permission on any one of them, the subscribe fails on all of them.
Does Access Manager apply to stored messages?
Yes. Access Manager applies to Message Persistence. A token with read permission on a channel can fetch all stored messages on that channel. When the permission expires or you revoke the token, the client loses access to the history too. See Message Persistence permissions.
How do I use the secret key?
Initialize the PubNub SDK on your server with it. Any PubNub instance initialized with the secret key can grant tokens. You don't pass the key in the grant call. The secret key grants privileged access to your PubNub application. It must remain on a trusted server and must never be included in client applications. A Function can also grant tokens, with secure access to your secret key. See Initialize a server SDK with a secret key.
How do I sign REST API requests with the secret key?
Compute a Hash-based Message Authentication Code (HMAC) with SHA-256 of a signing message, using the secret key as the signing key, and send the result in the signature query parameter along with a timestamp parameter. The signing message joins the HTTP method, the publish key, the request path, the sorted query string, and the request body with newline characters, in that order.
Use the publish key, not the subscribe key. Sort the query parameters by key and percent-encode them. The body is the request body exactly as you send it, or an empty string if there is none, so the message still ends with a newline. Base64 URL-safe encode the digest and add the prefix v2.. The Access Manager section of the Representational State Transfer (REST) API reference has the full encoding rules and worked examples. See Signature generation. If you see "Invalid Timestamp", see Why do I get "Invalid Timestamp" when I grant permissions?.
Can I allowlist IPs for PubNub traffic?
Allowlist these domains: *.pubnub.com, *.pndsn.com, *.pubnub.net, and *.pubnubapi.com. If your firewall requires IP addresses instead of domains, you need a paid plan. Contact support for the list of PubNub IP addresses.
Can I hide my application keys?
No, not fully. Even if your app gets the keys only after the user logs in, someone can still read them from the running app. The publish and subscribe keys only identify your app. Without Access Manager, any client that has them can use every channel on the keyset.
To control access, turn on Access Manager:
- Your login process authenticates the user.
- Your server grants that user a token for specific channels. An Access Manager token's
ttlranges from 1 minute to 43,200 minutes (30 days). - Your app sets the token in the SDK.
A client can't use channels its token doesn't cover. To also encrypt message content, configure a CryptoModule with a cipher key. See Authentication.
Can I restrict subscribers by IP or URL?
No. PubNub doesn't restrict subscribers by IP address or referrer URL. To control who can read each channel, use Access Manager.
To limit publishing by IP address, use a Before Publish Function. It can read the publisher's IP address from request.meta.clientip, count the messages from each address, and call request.abort() to block a message when an address goes over your limit. Users behind one IP address share one count. For an example, see Put the limit somewhere the fan cannot edit.
Can I encrypt all messages with AES?
Yes. Configure a CryptoModule with a cipher key when you initialize the SDK. The SDK then encrypts message content with 256-bit AES-CBC. All clients that send and receive encrypted content must configure the SDK with the same cipher key. If SDK configuration sets a cipherKey without an explicit CryptoModule, the SDK defaults to legacy 128-bit encryption. To switch, see Migrate to 256-bit AES-CBC encryption. For setup, see Encrypt all messages and files.
Why does encryption stop working after an SDK update?
Encrypted content is unreadable when the sender and receiver use different cipher settings. A client without the correct cipher key receives unreadable content. If SDK configuration sets a cipherKey without an explicit CryptoModule, the SDK defaults to legacy 128-bit encryption. If you switch a client to 256-bit Advanced Encryption Standard (AES) encryption in cipher block chaining (CBC) mode, older clients can't read what it sends. An SDK version that doesn't support AES-CBC 256-bit encryption can't decrypt content encrypted with it.
To fix it, check that every client uses the same cipher key and that each one runs a software development kit (SDK) version with CryptoModule support. Update all clients first, then switch the algorithm. See Migrate to 256-bit AES-CBC encryption and Data security and encryption.
Can I use PubNub with TLS?
Yes. PubNub SDKs connect over TLS 1.2 by default, except the Lua SDK and the unsupported Twisted SDK, where you set ssl to true. Make sure your systems support TLS 1.2. PubNub can't control which TLS version your systems use. Some SDKs call the setting ssl, the old name for TLS. You can turn TLS off for debugging, but don't do it in production. See Disable TLS.
Can PubNub protect against DoS attacks?
PubNub protects its network against denial-of-service (DoS) and distributed denial-of-service (DDoS) attacks with technical and operational measures. They include blocking IP ranges, changing server IP addresses, firewalls, protection against TCP SYN flooding, DNS failover across data centers, and operator monitoring. If PubNub detects abnormal or abusive traffic on a keyset, it may also apply a temporary rate limit. See Limits. To control what clients can do on your keyset, use Access Manager.
How do the cipher key and the secret key differ?
They do different jobs. The secret key stays on your server and lets it grant Access Manager tokens. The cipher key encrypts message and file content on the client. All clients that send and receive encrypted content must configure the SDK with the same cipher key.
The cipher key isn't used for TLS either. TLS encrypts traffic between each device and PubNub. The cipher key encrypts content on the sending device, and it stays encrypted through PubNub and Message Persistence until the receiving device decrypts it. You can use TLS and a cipher key separately or together. With a CryptoModule configured, the SDK encrypts message and file payloads on the device. The cipher key never leaves the client, so PubNub can't decrypt those payloads. Metadata stays readable to PubNub: the meta field, channel names, user IDs, custom message types, presence state, App Context, message actions, and in most SDKs signals. See Data security and encryption.
Is PubNub blocked by firewalls or antivirus software?
PubNub traffic is ordinary HTTPS. Subscribe uses long polling, which is built from ordinary HTTP request and response pairs, so it passes through corporate proxies, load balancers, and restrictive firewalls the same way any other HTTPS request does. For how the transport works, see Data transport and delivery.
If your network allows only specific destinations, see Can I allowlist IPs for PubNub traffic?.
Is PubNub's connection safe from attacks?
Yes. A PubNub client opens only outbound connections, on port 80 or 443. You don't open any inbound ports in your firewall, and PubNub doesn't listen on any port in your network. Outside users can't get into your network through a PubNub connection.
Where can I find compliance reports?
PubNub is ISO 27001 certified, SOC 2 Type II and SOC 3 audited, and HIPAA, GDPR, and CCPA compliant. PubNub also participates in the EU–U.S. Data Privacy Framework (DPF) and uses a PCI DSS Level 1-certified payment service provider. For the certificate and audit reports, visit the PubNub Trust Center. Pro plan customers can access the most recent reports directly from the Admin Portal, under Organization settings. Other customers can request them from PubNub Compliance.
Why doesn't revoking a token work immediately?
Token revocation can take up to one minute to take effect, because PubNub caches a token's non-revoked state for that long. After that, a request that uses the token fails. A request that uses a revoked token fails with 403 Revoked Token. Token revocation is disabled by default. To turn it on, see Enable token revocation.
Can I add users to my account?
Yes. Invite them to your organization and give each one a role. Only an Account Owner or Account Admin can do this.
- In the Admin Portal, open the account menu from your email address in the top-right corner.
- Select Organization settings.
- Open the Members tab, and select Add member.
The person gets an invitation email. If they don't have a PubNub account with that email address, they create one first. See Invite organization members and Admin Portal roles.
How do I access an account shared with me?
In the Admin Portal, open the account menu and select Switch organization. Then select the organization. You see its apps, keysets, Functions, usage, and invoices only after you switch to it. Your role decides what you can do there. See Admin Portal roles.
How do I turn on SSO for the Admin Portal?
You can't turn it on yourself. You set up your identity provider (IdP), then ask PubNub to enable Security Assertion Markup Language (SAML) single sign-on (SSO) for your email domain. Availability depends on your plan. See Features by plan.
- In your IdP, create an application for the Admin Portal and pass the
email,firstName, andlastNameattributes. - In the Admin Portal, open the account menu, select Organization settings, and open the SSO tab.
- Fill in the Single Sign-On Request form and select Send request.
- After PubNub enables SSO, upload your IdP's x.509 certificate on the SSO tab if you didn't send it with the request.
Members then select SSO on the login page and enter your company's email domain. See Set up single sign-on for the Admin Portal for the full values and steps.
How do I switch from Google SSO back to a password?
To log in with a password instead of Google single sign-on (SSO), set one with the password reset flow, then log in with your email and password. A Google-created account starts without a password, so there's nothing to change yet.
- On the Admin Portal login page, select Forgot password?.
- Enter the email address of your account and select Reset password.
- Open the link in the email and choose a new password.
Your Profile settings page shows whether Password access is on and whether Google Single Sign-On is Connected. If your email domain uses company SSO and doesn't allow password login, the reset doesn't set a password, and you log in with SSO instead. See How do I turn on SSO for the Admin Portal?.
I'm locked out of my account. How do I reset my password?
On the Admin Portal login page, select Forgot password?, enter your account email, and select Reset password. PubNub emails you a link to choose a new password.
- Use the newest email. A new request replaces the earlier link, and each link expires.
- After a reset, PubNub logs you out of your other sessions.
- If login says the account is locked after repeated failed attempts, wait for the time in the message or contact support.
PubNub responds the same way for addresses it doesn't recognize, so if no email arrives, check that you entered the address you registered with.
What user roles exist in an account?
Admin Portal roles decide what each member can see and change in the Admin Portal. They don't affect what your app's clients can do on channels, which Access Manager controls.
Roles come in Admin and Viewer pairs at three levels: account, app, and keyset. There are also roles for Functions (Functions Developer and Functions Viewer), Business Insights, BizOps Dashboard Operator, and Illuminate Admin for Illuminate. A member can hold several roles, except for some combinations. See Admin Portal roles for what each role permits and the combinations you can't use.
Why do I get "Your email could not be changed at this time"?
Another PubNub account already uses that email address. To give that person access to your apps and keysets, add them to your organization instead. See Can I add users to my account?.
How do I delete my PubNub account?
In the Admin Portal, open the account menu, select Support, and send a request to delete your account. PubNub sends you an email to confirm the request. To delete data from your keysets instead, see Data deletion options.
How do I opt out of marketing emails from PubNub?
Use the communication preferences form.