Cardinal Media Server Accounts
Your Cardinal Media Server is an identity provider, meaning it can create and manage user accounts for people. Colloquially, it is known as the "local IdP", and it supports two types of user accounts: cloud and local. This guide details how both account types work in your Media Server and, by extension, your other self-hosted apps.
Cloud Accounts
The first user to log in with a Cardinal Account will be made the Media Server owner.
Cloud accounts are a type of account in your Media Server that can only be logged into using a Cardinal Account. Cardinal Accounts come with a number of features, like hardened security and access to Cardinal's cloud services. You can read more about what Cardinal Accounts can do on the product page.
When a user in your Media Server uses a cloud account, your server does not need to manage their credentials. Your Media Server, acting as the local IdP, will still issue an access token and refresh token for cloud users, but only at the discretion of Cardinal's cloud authentication servers.
Claiming Your Media Server
Claiming your Media Server with your Cardinal Account is the most powerful way to secure it. Once your Media Server is up and running, just log in with your Cardinal Account and you will be asked to confirm your claim. You can self-host and claim multiple Media Servers.
Once claimed, all of your self-hosted apps gain access to all of the features included in your subscription tier. To confirm that the claim was processed correctly, verify these things:
- In your self-hosted Admin app, your Cardinal Account should have the Owner role.
- In the Account Portal, under Claims, confirm that the
instanceIdmatches the one you see in your self-hosted Admin app.
Inviting Cloud Accounts
Owners of self-hosted apps can invite other users using Invitations. When a cloud user logs into a new self-hosted app for the first time, they will be asked to authorize exactly which bits of information the self-hosted app can see about their Cardinal Account. This set of permissions is called "permission scopes".
When you authorize an app's request for these scopes, you are also allowing the app to refresh the data for as long as the authorization is active. Your can manage your app authorizations in the Account Portal.
Permission Scopes
| Scope | Description |
|---|---|
| user_id | Your unique Cardinal user ID. |
| user_public_name | The public name you've set, if you've set one. |
| user_email_confirmed | A boolean indicating whether you have confirmed your email. Your actual email is never shared with server owners or other users. |
| user_avatar | Your cloud avatar. |
| subscription | Your subscription tier. |
Seats
The number of cloud seats that a Media Server supports is determined by the subscription of the server owner. Each seat can be occupied by a one cloud user at a time. When the server is at capacity, no new cloud users will be able to join until a seat becomes available.
Local Accounts
Your Media Server also supports local accounts, and you can create and manage local accounts in your Admin dashboard. There is no limit to how many you can make, and they support all of your self-hosted app's offline features.
Local accounts use a simpler authentication layer that is provided entirely by your Media Server. Passwords are encrypted and stored in your database. Cardinal's cloud authentication servers are not involved with local accounts in any way.
Guest Account
The Guest account is a special built-in local account with the Admin role. You can disable the Guest account once you've created another Admin user.
User Sessions
When a cloud user or local user logs into your Media Server, your server issues a short-lived access token that expires after 15 minutes. The app stores it in localStorage or sessionStorage and sends it with every request. What the app renews it with once it expires depends on where the app is running relative to your Media Server.
Same-site sessions
The apps that your Media Server serves itself (the bundled Music, Photos, Cinema, and Admin apps) are on the same site as its API, whether you reach them on your LAN, through your Remote Access hostname, or on a custom domain. For these logins, your server also issues a refresh token in an httpOnly cookie, and the app renews its access token with that cookie. The session lasts as long as the cookie does: its lifetime follows the Session timeout setting in the Admin app (7 days by default), and it is renewed on every refresh.
The cookie is named cardinal_refresh_tolkien_<instance ID> so that two Media Servers on the same host do not overwrite each other's session, and it is scoped to Path=/api/v1/auth. Its remaining attributes depend on the SECURE_COOKIES environment variable:
| Cookie attributes | Works over | |
|---|---|---|
SECURE_COOKIES=true | Secure, SameSite=Strict | HTTPS only. Over plain HTTP the browser discards the cookie, so users are signed out again after 15 minutes. |
SECURE_COOKIES=false | SameSite=Lax | HTTP and HTTPS. |
Cross-site sessions
A Cardinal-hosted app, like music.cardinalapps.cloud, reaches your Media Server through the Remote Access edge on cardinalapps.host, which is a different site from the page itself. Browsers do not send a refresh cookie across sites (and Safari and every iOS browser block third-party cookies outright, whatever their attributes), so your server does not set one for these logins.
Instead, the app renews its access token with the Cardinal Account token. On every refresh, your server verifies that token with Cardinal's cloud authentication servers and, if the Cardinal Account is linked to an account on your server, issues a new access token. This means:
- The session lasts as long as the Cardinal Account session does (a 7-day window that slides with use). The Session timeout setting does not apply to it.
- If Cardinal's cloud cannot be reached, the refresh is refused temporarily and the app retries later; the session is not ended.
- Only cloud accounts can hold a cross-site session. A local account has no Cardinal Account token to renew with, so it is signed out once its access token expires.
Was this article helpful?