Connecting to your server

Podling connects to your own AudioBookShelf (ABS) server. Most people just enter a server address, a username, and a password. This page covers the three options for setups that need more: single sign-on, custom request headers, and self-signed certificates.

All three are per server — they apply only to the server you configure them on, and switching servers switches the settings with them.

How signing in works

When you enter your server address, Podling asks the server which sign-in methods it supports before showing you the login screen. So:

• If your server only does password login, you’ll see the username and password fields.
• If your server also has single sign-on turned on, a Continue with Single Sign-On button appears below them.

Your credentials always go straight to your own server. Podling has no account system and nothing sits in the middle.

Single sign-on (OIDC)

If your AudioBookShelf server is set up with an OpenID Connect provider — Authentik, Keycloak, Auth0, Google, and so on — you can sign in through it instead of with a username and password.

On the sign-in screen, tap Continue with Single Sign-On (your server admin can rename this button). Podling opens your identity provider in a browser tab, you log in there, and you’re returned to the app already signed in.

For server admins: enabling OIDC for the mobile app

Turning on OpenID in AudioBookShelf is documented in the ABS authentication guide. Two things specifically matter for Podling (and the official mobile app) to work:

1. Allow the mobile redirect URI. In your ABS OpenID settings, the Mobile Redirect URIs list must include:

   audiobookshelf://oauth

   This is the link the browser uses to hand you back to the app after you log in. It is on the default allow-list, but if you’ve customized that list, make sure it’s still there. (Setting the list to a single * also works but is less strict.)

2. Register that redirect with your identity provider. In your OIDC provider’s client/application config for AudioBookShelf, add audiobookshelf://oauth to its list of allowed redirect URIs, alongside the web ones ABS already uses. If it’s missing, the provider will reject the login with an “invalid redirect_uri” error.

If the official ABS app is also installed

Both apps register the same audiobookshelf://oauth link, so Android may ask which app to open when you finish logging in. Pick Podling. This only comes up if you have both installed.

Token refresh

Rotating access/refresh tokens (so your session renews itself instead of expiring) need AudioBookShelf 2.26.0 or newer. On older servers OIDC still works, but the session is a single long-lived token.

Custom HTTP headers

If your server sits behind an authenticating proxy — Cloudflare Access / Zero Trust, an mTLS or header-auth gateway, a WAF — you can attach custom headers to every request Podling makes to that server.

On the Find your server screen (and later under a server’s settings), tap Need custom headers? and add the header name/value pairs your proxy expects, for example:

Header	Value
CF-Access-Client-Id	<your client id>
CF-Access-Client-Secret	<your client secret>

These headers are sent with everything Podling asks that server for — the API, cover images, downloads, streaming audio, and the real-time sync connection — so a proxy in front of your whole server sees them on every request.

Caution

Custom headers are only ever sent to your configured server, never to third-party hosts (like podcast feeds or their cover CDNs). They also can’t override Podling’s own Authorization or User-Agent headers.

Self-signed or internal-CA certificates

If your server uses HTTPS with a self-signed certificate, or one issued by a private/internal certificate authority your phone doesn’t recognize, the connection would normally fail because the certificate can’t be verified.

When that happens, Podling shows you the certificate — its subject, issuer, SHA-256 fingerprint, and validity dates — and lets you trust it for that one server after you’ve looked it over.

1. Enter your server address and continue. If the certificate can’t be verified, the Untrusted certificate screen appears.

2. Review the details. The fingerprint is the important part: compare it against the one your server actually presents (openssl s_client -connect yourserver:443 </dev/null 2>/dev/null | openssl x509 -noout -fingerprint -sha256 on the server side) so you know you’re trusting the right certificate and not a machine in the middle.

3. Tap Trust this server only to proceed, or Go back if anything looks wrong.

Once trusted, that server’s connections validate against the exact certificate you approved.

This is not a global override

Trust is scoped to the single server and the single certificate you reviewed. Every other server keeps full, normal TLS validation, and there is no global option to disable certificate checking. If that server later presents a different certificate, Podling stops and asks you to review it again rather than trusting the new one silently.

Tip

Only trust a certificate you control or recognize. On a network you don’t run, an untrusted-certificate warning can mean someone is intercepting the connection — that’s exactly the case this warning exists to catch.