Skip to main content
Customize every aspect of your login experience, from which sign-in methods your users see to branding on the OAuth consent screen. Go to Branding & SEO → Customize Auth Portal to customize
Login and OTP email customization

​
How do I customize Auth Portal logo, colors, and appearance?

Go to Branding → Customize Auth Portal. You customize the Auth Portal’s colors, logo, terms and conditions, privacy policy and more. Learn more here.

​
How do I customize login options?

Go to Branding → Customize Auth Portal in the sidebar to enable specific login methods for your users
MethodDefaultDescription
GoogleOnSign in with a Google account
AppleOnSign in with an Apple ID
MicrosoftOnSign in with a Microsoft account (personal or work)
Email OTPOnSign in with a one-time code sent to email
LinkedInOffSign in with a LinkedIn account
Phone OTPOffSign in with a one-time code sent via SMS
SSO (SAML/OIDC)OffSign in with user’s organization’s Single Sign-On provider (SAML or OpenID Connect)
Login method toggle settings
Changes take effect within about a minute. Your users will see the updated options on their next visit to the Auth Portal.

​
How do I customize the Auth Portal’s domain?

By default, the Auth Portal uses yourapp.auth.onhercules.app. You can change this to auth.yourdomain.com so your users see your domain during sign-in. Configuration depends on how you connect your domain to your Hercules app.
Domain setupWhat to do
Purchased through HerculesNothing. Automatically configured
3rd party domain with wildcard redirectAdd a CNAME record pointing auth to cname.onhercules.app
3rd party domain without wildcard redirectGo to Domains → Connect Domain and add auth.yourdomain.com as a separate domain
Auth Portal with custom auth domain in browser address bar
Additional notes
  1. SSL is provisioned automatically
  2. To use a subdomain other than auth, contact hello@hercules.app

​
How do I customize the email OTP email address?

  1. Configure a sender identity in Hercules Email
  2. Once your identity is verified, go to Branding & SEO → Customize Auth Portal and select the email as the OTP sender
Login and OTP email customization

​
How do I customize OAuth branding?

By default, your users see “Hercules” on the OAuth consent screen during social login. Use custom credentials to show your brand name, privacy policy, and terms of service instead. Go to Branding & SEO → Customize Auth Portal → Login Options, select a provider, and enter your OAuth credentials. After saving, Hercules gives you a Callback URL to add to your provider’s developer console. See provider-specific guides below.
1

Create a Google Cloud project

Go to the Google Cloud Console. Create a new project or select an existing one.
2

Configure the OAuth consent screen

Go to APIs & Services → OAuth consent screen.
  • Set the User Type to External (unless you are restricting to a Google Workspace organization)
  • Fill in the App name, User support email, and Developer contact email
  • Add your logo, privacy policy URL, and terms of service URL
  • Under Scopes, add openid, email, and profile
  • Save
Google OAuth apps start in “Testing” status with a 100-user limit. To remove this limit, click Publish App and complete Google’s verification process. This can take several days.
3

Create OAuth credentials

Go to APIs & Services → Credentials → Create Credentials → OAuth client ID.
  • Set Application type to Web application
  • Under Authorized redirect URIs, add the Callback URL shown in Hercules (you can come back to this step after saving in Hercules)
  • Click Create
  • Copy the Client ID and Client Secret
4

Enter credentials in Hercules

Go to your app’s Auth settings → Google → Custom Credentials.
  • Paste the Client ID and Client Secret
  • Click Save
  • Copy the Callback URL shown after saving
5

Add the Callback URL to Google

Go back to the Google Cloud Console → APIs & Services → Credentials → click your OAuth client.
  • Under Authorized redirect URIs, add the Callback URL from Hercules
  • Save
1

Register an app in Microsoft Entra ID

Go to the Microsoft Entra admin center → Identity → App registrations → New registration.
  • Set a Name for the app (your users will see this)
  • Under Supported account types, select Accounts in any organizational directory and personal Microsoft accounts (this covers both work and personal accounts)
  • Under Redirect URI, select Web and enter the Callback URL shown in Hercules (you can come back to this step after saving in Hercules)
  • Click Register
2

Create a client secret

In your app registration, go to Certificates & secrets → New client secret.
  • Add a description and choose an expiry period
  • Click Add
  • Copy the Value (this is your Client Secret, shown only once)
Copy the secret value immediately. Microsoft only shows it once. If you lose it, you will need to create a new secret.
3

Copy the Client ID

Go to Overview in your app registration. Copy the Application (client) ID.
4

Enter credentials in Hercules

Go to your app’s Auth settings → Microsoft → Custom Credentials.
  • Paste the Client ID (Application ID from Microsoft) and Client Secret (secret value)
  • Click Save
  • If you haven’t added the Callback URL yet, copy it now and add it to the Redirect URIs in Microsoft Entra
Apple Sign In requires more setup than other providers because Apple uses a private key instead of a simple client secret.
1

Create an App ID

Go to the Apple Developer portal → Certificates, Identifiers & Profiles → Identifiers → click +.
  • Select App IDs → Continue
  • Select App → Continue
  • Enter a Description and a Bundle ID (e.g. com.yourcompany.yourapp)
  • Under Capabilities, check Sign In with Apple
  • Click Continue → Register
2

Create a Services ID

Go to Identifiers → click + → select Services IDs → Continue.
  • Enter a Description (your users will see this on the Apple consent screen)
  • Enter an Identifier (e.g. com.yourcompany.yourapp.auth)
  • Click Continue → Register
Then click on your new Services ID:
  • Check Sign In with Apple → click Configure
  • Under Domains and Subdomains, add the domain shown in the Hercules Callback URL (e.g. auth.onhercules.app)
  • Under Return URLs, add the full Callback URL from Hercules
  • Click Save → Continue → Save
3

Create a private key

Go to Keys → click +.
  • Enter a Key Name
  • Check Sign In with Apple → click Configure
  • Select the App ID you created in Step 1
  • Click Save → Continue → Register
  • Download the .p8 key file. Store it securely. Apple only lets you download it once.
  • Note the Key ID shown on this page
The .p8 private key file can only be downloaded once. If you lose it, you must create a new key.
4

Find your Team ID

Go to Membership details in the Apple Developer portal. Copy your Team ID (a 10-character string).
5

Enter credentials in Hercules

Go to your app’s Auth settings → Apple → Custom Credentials.
  • Client ID: Enter the Identifier of your Services ID (from Step 2, e.g. com.yourcompany.yourapp.auth)
  • Team ID: Paste your Team ID
  • Key ID: Paste the Key ID from Step 3
  • Private Key: Open the .p8 file in a text editor and paste the entire contents, including the -----BEGIN PRIVATE KEY----- and -----END PRIVATE KEY----- lines
  • Click Save
1

Create a LinkedIn app

Go to the LinkedIn Developer Portal → Create App.
  • Enter an App name, LinkedIn Page, and Logo
  • Accept the terms and click Create app
2

Add the Sign In with LinkedIn product

In your app’s Products tab, find Sign In with LinkedIn using OpenID Connect and click Request access.
3

Configure OAuth redirect

Go to the Auth tab.
  • Under Authorized redirect URLs for your app, add the Callback URL from Hercules
  • Copy the Client ID and Client Secret
4

Enter credentials in Hercules

Go to your app’s Auth settings → LinkedIn → Custom Credentials.
  • Paste the Client ID and Client Secret
  • Click Save
Custom OAuth credentials form
Additional notes
  • If you remove custom credentials, Hercules automatically falls back to its own managed credentials. Social login continues to work. Your users will see “Hercules” on the consent screen again.
  • Custom OAuth credentials are available on the Business plan

​
Can I bring my own auth provider?

Currently, Hercules apps only support Hercules Auth. Authentication is a fragile part of building software. If auth breaks, your entire app can break. We prioritize making Hercules Auth a stable, well-supported, secure, and robust auth system. We are working on supporting custom auth providers in the future.

​
Additional FAQ

Auth is how your users prove their identity (sign in / sign up). Users is where you manage the people who have signed up for your app, including their roles, permissions, and account status. Configure auth options here; manage your user base in the Users, Roles & Permissions tab.
Yes. Hercules Auth blocks throwaway and temporary email addresses (like Mailinator, Guerrilla Mail, etc.) by default. This prevents spam signups. This applies to all email-based login methods (email OTP, email + password, and social providers that return a disposable email).
Not currently. Hercules Auth works by redirecting to a Hercules-hosted Auth Portal. We are working on allowing in-app authentication flows in the near future.
No. Existing users can sign in with any enabled method that matches their email address. If a user signed up with Google and you later enable Apple, they can sign in with Apple using the same email and both accounts are automatically linked.