Library authentication settings
Authentication settings define the identity providers and default sign-in experience available to services in a library. Individual services decide whether end-user sign-in is enabled and can override some defaults. Library authentication configuration must be applied separately to QA and Production.
Open the library, select Library settings, then Authentication.
Separate library defaults from service access
flowchart TD
A[Library authentication configuration] --> B[Default identity provider]
A --> C[Default sign-in content and policies]
A --> D[QA and Production credentials]
B --> E[Service enables sign-in]
C --> E
D --> E
E --> F[Service-specific overrides where needed]Configuring a provider does not make every service private. Use the service’s access settings to enable sign-in, choose or override the provider and define the service’s audience.
Choose the default identity provider
The default can be:
- Magic link email (passwordless) — verifies an email address by sending a time-limited sign-in link.
- OpenID Connect (OAuth 2.0) — redirects the user to an organisation-controlled identity provider and uses the authorization-code flow.
- AWS Cognito — uses platform-hosted sign-in pages connected to a configured Cognito user pool.
Choose the provider that matches the organisation’s identity ownership, assurance level, support model and user population. A service can override the default when its audience differs.
Configure OpenID Connect
OpenID Connect settings are environment-specific. Configure separate QA and Production clients at the identity provider and in the Builder.
| Setting group | What to provide |
|---|---|
| Provider discovery | issuer host for QA and Production; the Builder completes the well-known discovery path |
| Client identity | client ID for each environment |
| Token authentication | client secret, or a private-key JWT using an RSA key pair and the published JWKS endpoint |
| Scopes | the claims the service needs, normally beginning with openid |
| Sign-out | default provider discovery or a custom logout URL for each environment |
| Logout parameters | only the provider-required combination, such as an ID-token hint, logout hint, client ID or post-logout redirect |
| User information | whether to call the provider’s user-info endpoint for additional claims |
Register the exact callback, logout and JWKS destinations displayed by the current Builder in the identity-provider client. They may use the platform environment domains even when the service has a custom domain. Do not copy example hostnames from a different tenant or environment.
Client secrets and private keys are stored as secrets and are not displayed back. Record their owner and expiry in an approved credential register. Generate or rotate QA and Production keys independently, test sign-in and sign-out in QA, then apply the approved Production configuration.
Use private-key JWT only when the provider requires asymmetric client authentication. Give the provider the displayed JWKS URL and key ID, and coordinate key rotation so the old public key remains available until clients have moved safely.
Configure magic-link email
Choose the email provider used to send sign-in links. Where the configured provider uses a reusable message template, supply its template ID and ensure the template contains the required link variable. If the optional service-name variable is enabled, the template must also include the matching variable.
Test delivery, expiry, reuse of an old link, an unknown address and return to the original service page. Do not put personal or sensitive answers into sign-in email content.
Configure AWS Cognito
Provide the user-pool region, pool ID and client ID separately for QA and Production. Then set the password policy:
- minimum length between the allowed limits;
- whether an uppercase letter is required;
- whether a lowercase letter is required;
- whether a number is required;
- whether a special character is required.
The library also supplies the name shown in an authenticator app when a service enables Cognito multifactor authentication. Choose a name users can recognise and support teams can refer to consistently.
Changing a password policy can affect existing users and support demand. Test account creation, password reset, sign-in failure and multifactor recovery before applying it live.
Design the default sign-in experience
Library defaults include:
- sign-in page title;
- optional notification banner content;
- optional additional page content;
- the name shown in an authenticator app;
- terms and conditions as an external URL or inline Markdown;
- privacy policy as an external URL or inline Markdown.
Banner and additional content can use Markdown and Liquid. Keep the sign-in page concise and do not reveal whether a particular person has an account. If both a URL and inline policy content are available, the URL takes precedence.
Restrict the audience
An Email domain restriction allows only authenticated users from one domain. An allowed-email list is more restrictive: once at least one address is present, all other addresses are denied for services that use the library access restriction.
Before adding an allowlist, confirm how it will be maintained and how a user requests access. Use exact addresses, remove departed users and test both an allowed and denied account. QA services remain limited to approved Builder or QA users regardless of a public Production audience.
Apply to environments
The page shows the last user and time for each environment, or indicates that defaults still apply.
- Save the complete QA configuration with Apply to QA environment.
- Test sign-in, sign-out, timeout, denied access, recovery and service return routes.
- Confirm claims and user identifiers are mapped as expected.
- Apply the approved configuration with Apply to Production environment.
- Run a controlled Production smoke test with an authorised account.
Applying authentication settings is distinct from deploying a service version. When a release depends on both, record their order and verify both deployment states.